aboutsummaryrefslogtreecommitdiffstats
path: root/guides/source
diff options
context:
space:
mode:
Diffstat (limited to 'guides/source')
-rw-r--r--guides/source/5_2_release_notes.md66
-rw-r--r--guides/source/security.md106
2 files changed, 109 insertions, 63 deletions
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 `<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
----------------------