Merge pull request rails#44451 from p8/docs/add-documentation-for-csp

Document some methods in ActionDispatch::ContentSecurityPolicy [skip-ci]

Author: jonathanhefner

actionpack/lib/action_dispatch/http/content_security_policy.rb

@@ -3,6 +3,23 @@
 require "active_support/core_ext/object/deep_dup"
 
 module ActionDispatch # :nodoc:
+  # Allows configuring a
+  # {Content-Security-Policy}(https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)
+  # to help protect against XSS and injection attacks.
+  #
+  # Example global policy:
+  #
+  #   Rails.application.config.content_security_policy do |policy|
+  #     policy.default_src :self, :https
+  #     policy.font_src    :self, :https, :data
+  #     policy.img_src     :self, :https, :data
+  #     policy.object_src  :none
+  #     policy.script_src  :self, :https
+  #     policy.style_src   :self, :https
+  #
+  #     # Specify URI for violation reports
+  #     policy.report_uri "/csp-violation-report-endpoint"
+  #   end
   class ContentSecurityPolicy
     class Middleware
       CONTENT_TYPE = "Content-Type"
@@ -174,6 +191,15 @@ def initialize_copy(other)
       end
     end
 
+    # Specify whether to prevent the user agent from loading any assets over
+    # HTTP when the page uses HTTPS:
+    #
+    #   policy.block_all_mixed_content
+    #
+    # Pass +false+ to allow it again:
+    #
+    #   policy.block_all_mixed_content false
+    #
     def block_all_mixed_content(enabled = true)
       if enabled
         @directives["block-all-mixed-content"] = true
@@ -182,6 +208,14 @@ def block_all_mixed_content(enabled = true)
       end
     end
 
+    # Restricts the set of plugins that can be embedded:
+    #
+    #   policy.plugin_types "application/x-shockwave-flash"
+    #
+    # Leave empty to allow all plugins:
+    #
+    #   policy.plugin_types
+    #
     def plugin_types(*types)
       if types.first
         @directives["plugin-types"] = types
@@ -190,10 +224,24 @@ def plugin_types(*types)
       end
     end
 
+    # Enable the {report-uri}(https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-uri)
+    # directive. Violation reports will be sent to the specified URI:
+    #
+    #   policy.report_uri "/csp-violation-report-endpoint"
+    #
     def report_uri(uri)
       @directives["report-uri"] = [uri]
     end
 
+    # Specify asset types for which {Subresource Integrity}(https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity)
+    # is required:
+    #
+    #   policy.require_sri_for :script, :style
+    #
+    # Leave empty to not require Subresource Integrity:
+    #
+    #   policy.require_sri_for
+    #
     def require_sri_for(*types)
       if types.first
         @directives["require-sri-for"] = types
@@ -202,6 +250,19 @@ def require_sri_for(*types)
       end
     end
 
+    # Specify whether a {sandbox}(https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/sandbox)
+    # should be enabled for the requested resource:
+    #
+    #   policy.sandbox
+    #
+    # Values can be passed as arguments:
+    #
+    #   policy.sandbox "allow-scripts", "allow-modals"
+    #
+    # Pass +false+ to disable the sandbox:
+    #
+    #   policy.sandbox false
+    #
     def sandbox(*values)
       if values.empty?
         @directives["sandbox"] = true
@@ -212,6 +273,14 @@ def sandbox(*values)
       end
     end
 
+    # Specify whether user agents should treat any assets over HTTP as HTTPS:
+    #
+    #   policy.upgrade_insecure_requests
+    #
+    # Pass +false+ to disable it:
+    #
+    #   policy.upgrade_insecure_requests false
+    #
     def upgrade_insecure_requests(enabled = true)
       if enabled
         @directives["upgrade-insecure-requests"] = true