diff options
| author | bogdanvlviv <bogdanvlviv@gmail.com> | 2018-03-18 23:07:12 +0200 |
|---|---|---|
| committer | bogdanvlviv <bogdanvlviv@gmail.com> | 2018-03-18 23:25:19 +0200 |
| commit | 8b26de85e84ab5acfed087b4b2b1b31a6f6b96a7 (patch) | |
| tree | fcca3d8bef11156102c8e88674682ef4aa158d2f /guides/source/security.md | |
| parent | d9736e50d8d6fc9fad32e16ebdc8dcd0a0a3ec61 (diff) | |
| download | rails-8b26de85e84ab5acfed087b4b2b1b31a6f6b96a7.tar.gz rails-8b26de85e84ab5acfed087b4b2b1b31a6f6b96a7.tar.bz2 rails-8b26de85e84ab5acfed087b4b2b1b31a6f6b96a7.zip | |
Move CSP info from 5.2 release notes to guide [ci skip]
- Add mention about "nonce".
Related to https://github.com/rails/rails/pull/32222#issuecomment-372268157
Diffstat (limited to 'guides/source/security.md')
| -rw-r--r-- | guides/source/security.md | 106 |
1 files changed, 106 insertions, 0 deletions
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 `<script>` tags. + +```html+erb +<head> + <%= csp_meta_tag %> +</head> +``` + +This is used by the Rails UJS helper to create dynamically +loaded inline `<script>` elements. + Environmental Security ---------------------- |