diff --git a/guides/source/5_2_release_notes.md b/guides/source/5_2_release_notes.md index 8086c8cb55..541c025fac 100644 --- a/guides/source/5_2_release_notes.md +++ b/guides/source/5_2_release_notes.md @@ -85,69 +85,9 @@ Rails 5.2 ships with a new DSL that allows you to configure a for your application. You can configure a global default policy and then override it on a per-resource basis and even use lambdas to inject per-request values into the header such as account subdomains in a multi-tenant application. - -Example global policy: - -```ruby -# config/initializers/content_security_policy.rb -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 -``` - -Example controller overrides: - -```ruby -# Override policy inline -class PostsController < ApplicationController - content_security_policy do |p| - p.upgrade_insecure_requests true - end -end - -# Using literal values -class PostsController < ApplicationController - content_security_policy do |p| - p.base_uri "https://www.example.com" - end -end - -# Using mixed static and dynamic values -class PostsController < ApplicationController - content_security_policy do |p| - p.base_uri :self, -> { "https://#{current_user.domain}.example.com" } - end -end - -# Disabling the global CSP -class LegacyPagesController < ApplicationController - content_security_policy false, only: :index -end -``` - -To report only content violations for migrating -legacy content using the `content_security_policy_report_only` -configuration attribute: - -```ruby -# config/initializers/content_security_policy.rb -Rails.application.config.content_security_policy_report_only = true -``` - -```ruby -# Controller override -class PostsController < ApplicationController - content_security_policy_report_only only: :index -end -``` +You can read more about this in the +[Securing Rails Applications](security.html#content-security-policy) +guide. Railties -------- diff --git a/guides/source/security.md b/guides/source/security.md index 4cf6c06f2d..b419f7b48d 100644 --- a/guides/source/security.md +++ b/guides/source/security.md @@ -1089,6 +1089,112 @@ Here is a list of common headers: * **Access-Control-Allow-Origin:** Used to control which sites are allowed to bypass same origin policies and send cross-origin requests. * **Strict-Transport-Security:** [Used to control if the browser is allowed to only access a site over a secure connection](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) +### Content Security Policy + +Rails provides a DSL that allows you to configure a +[Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) +for your application. You can configure a global default policy and then +override it on a per-resource basis and even use lambdas to inject per-request +values into the header such as account subdomains in a multi-tenant application. + +Example global policy: + +```ruby +# config/initializers/content_security_policy.rb +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 +``` + +Example controller overrides: + +```ruby +# Override policy inline +class PostsController < ApplicationController + content_security_policy do |p| + p.upgrade_insecure_requests true + end +end + +# Using literal values +class PostsController < ApplicationController + content_security_policy do |p| + p.base_uri "https://www.example.com" + end +end + +# Using mixed static and dynamic values +class PostsController < ApplicationController + content_security_policy do |p| + p.base_uri :self, -> { "https://#{current_user.domain}.example.com" } + end +end + +# Disabling the global CSP +class LegacyPagesController < ApplicationController + content_security_policy false, only: :index +end +``` + +Use the `content_security_policy_report_only` +configuration attribute to set +[Content-Security-Policy-Report-Only](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy-Report-Only) +in order to report only content violations for migrating +legacy content + +```ruby +# config/initializers/content_security_policy.rb +Rails.application.config.content_security_policy_report_only = true +``` + +```ruby +# Controller override +class PostsController < ApplicationController + content_security_policy_report_only only: :index +end +``` + +You can enable automatic nonce generation: + +```ruby +# config/initializers/content_security_policy.rb +Rails.application.config.content_security_policy do |policy| + policy.script_src :self, :https +end + +Rails.application.config.content_security_policy_nonce_generator = -> request { SecureRandom.base64(16) } +``` + +Then you can add an automatic nonce value by passing `nonce: true` +as part of `html_options`. Example: + +```html+erb +<%= javascript_tag nonce: true do -%> + alert('Hello, World!'); +<% end -%> +``` + +Use [`csp_meta_tag`](http://api.rubyonrails.org/classes/ActionView/Helpers/CspHelper.html#method-i-csp_meta_tag) +helper to create a meta tag "csp-nonce" with the per-session nonce value +for allowing inline `