Use syntax highlighting in the readme file.
This commit is contained in:
Artur Dryomov
Родитель
34f23c81c9
Коммит
ef5e1a8c95
196
README.md
196
README.md
|
|
@ -11,15 +11,21 @@ The gem will automatically apply several headers that are related to security.
|
|||
|
||||
Add to your Gemfile
|
||||
|
||||
gem 'secure-headers'
|
||||
```ruby
|
||||
gem 'secure-headers'
|
||||
```
|
||||
|
||||
And then execute:
|
||||
|
||||
$ bundle
|
||||
```console
|
||||
$ bundle
|
||||
```
|
||||
|
||||
Or install it yourself as:
|
||||
|
||||
$ gem install secure-headers
|
||||
```console
|
||||
$ gem install secure-headers
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
@ -43,29 +49,33 @@ This gem makes a few assumptions about how you will use some features. For exam
|
|||
|
||||
**Place the following in an initializer:**
|
||||
|
||||
::SecureHeaders::Configuration.configure do |config|
|
||||
config.hsts = {:max_age => 99, :include_subdomains => true}
|
||||
config.x_frame_options = 'DENY'
|
||||
config.x_content_type_options = "nosniff"
|
||||
config.x_xss_protection = {:value => '1', :mode => false}
|
||||
config.csp = {
|
||||
:default_src => "https://* inline eval",
|
||||
# ALWAYS supply a full URL for report URIs
|
||||
:report_uri => 'https://example.com/uri-directive',
|
||||
:img_src => "https://* data:",
|
||||
:frame_src => "https://* http://*.twimg.com http://itunes.apple.com"
|
||||
}
|
||||
end
|
||||
```ruby
|
||||
::SecureHeaders::Configuration.configure do |config|
|
||||
config.hsts = {:max_age => 99, :include_subdomains => true}
|
||||
config.x_frame_options = 'DENY'
|
||||
config.x_content_type_options = "nosniff"
|
||||
config.x_xss_protection = {:value => '1', :mode => false}
|
||||
config.csp = {
|
||||
:default_src => "https://* inline eval",
|
||||
# ALWAYS supply a full URL for report URIs
|
||||
:report_uri => 'https://example.com/uri-directive',
|
||||
:img_src => "https://* data:",
|
||||
:frame_src => "https://* http://*.twimg.com http://itunes.apple.com"
|
||||
}
|
||||
end
|
||||
|
||||
# and then simply include
|
||||
ensure_security_headers
|
||||
# and then simply include
|
||||
ensure_security_headers
|
||||
```
|
||||
|
||||
Or simply add it to application controller
|
||||
|
||||
ensure_security_headers
|
||||
:hsts => {:include_subdomains, :x_frame_options => false},
|
||||
:x_frame_options => 'DENY',
|
||||
:csp => false
|
||||
```ruby
|
||||
ensure_security_headers
|
||||
:hsts => {:include_subdomains, :x_frame_options => false},
|
||||
:x_frame_options => 'DENY',
|
||||
:csp => false
|
||||
```
|
||||
|
||||
## Options for ensure\_security\_headers
|
||||
|
||||
|
|
@ -77,8 +87,10 @@ header will be constructed using the supplied options.
|
|||
|
||||
### Widely supported
|
||||
|
||||
:hsts => {:max_age => 631138519, :include_subdomain => true} # HTTP Strict Transport Security.
|
||||
:x_frame_options => {:value => 'SAMEORIGIN'}
|
||||
```ruby
|
||||
:hsts => {:max_age => 631138519, :include_subdomain => true} # HTTP Strict Transport Security.
|
||||
:x_frame_options => {:value => 'SAMEORIGIN'}
|
||||
```
|
||||
|
||||
### Content Security Policy (CSP)
|
||||
|
||||
|
|
@ -86,81 +98,87 @@ All browsers will receive the webkit csp header except Firefox, which gets its o
|
|||
See [WebKit/W3C specification](http://www.w3.org/TR/CSP/)
|
||||
and [Firefox CSP specification](https://wiki.mozilla.org/Security/CSP/Specification)
|
||||
|
||||
:csp => {
|
||||
:enforce => false, # sets header to report-only, by default
|
||||
# default_src is required!
|
||||
:default_src => nil, # sets the default-src/allow+options directives
|
||||
```ruby
|
||||
:csp => {
|
||||
:enforce => false, # sets header to report-only, by default
|
||||
# default_src is required!
|
||||
:default_src => nil, # sets the default-src/allow+options directives
|
||||
|
||||
# Where reports are sent. Use full URLs.
|
||||
:report_uri => 'https://mylogaggregator.example.com',
|
||||
# Where reports are sent. Use full URLs.
|
||||
:report_uri => 'https://mylogaggregator.example.com',
|
||||
|
||||
# Send reports that cannot be sent across host here (see below), forward them to report_uri
|
||||
# override this if you have a route with the same value (content_security_policy#scribe)
|
||||
:forward_endpoint => TwitterRailsSecurity::Headers::ContentSecurityPolicy::FF_CSP_ENDPOINT
|
||||
# Send reports that cannot be sent across host here (see below), forward them to report_uri
|
||||
# override this if you have a route with the same value (content_security_policy#scribe)
|
||||
:forward_endpoint => TwitterRailsSecurity::Headers::ContentSecurityPolicy::FF_CSP_ENDPOINT
|
||||
|
||||
# these directives all take 'none', 'self', or a globbed pattern
|
||||
:img_src => nil,
|
||||
:frame_src => nil,
|
||||
:connect_src => nil,
|
||||
:font_src => nil,
|
||||
:media_src => nil,
|
||||
:object_src => nil,
|
||||
:style_src => nil,
|
||||
:script_src => nil,
|
||||
# these directives all take 'none', 'self', or a globbed pattern
|
||||
:img_src => nil,
|
||||
:frame_src => nil,
|
||||
:connect_src => nil,
|
||||
:font_src => nil,
|
||||
:media_src => nil,
|
||||
:object_src => nil,
|
||||
:style_src => nil,
|
||||
:script_src => nil,
|
||||
|
||||
# http additions will be appended to the various directives when
|
||||
# over http, relaxing the policy
|
||||
# e.g.
|
||||
# :csp => {
|
||||
# :img_src => 'https://*',
|
||||
# :http_additions => {:img_src => 'http//*'}
|
||||
# }
|
||||
# would produce the directive: "img-src https://* http://*;"
|
||||
# when over http, ignored for https requests
|
||||
:http_additions => {}
|
||||
}
|
||||
# http additions will be appended to the various directives when
|
||||
# over http, relaxing the policy
|
||||
# e.g.
|
||||
# :csp => {
|
||||
# :img_src => 'https://*',
|
||||
# :http_additions => {:img_src => 'http//*'}
|
||||
# }
|
||||
# would produce the directive: "img-src https://* http://*;"
|
||||
# when over http, ignored for https requests
|
||||
:http_additions => {}
|
||||
}
|
||||
```
|
||||
|
||||
### Only applied to IE
|
||||
|
||||
:x_content_type_options => {:value => 'nosniff'}
|
||||
:x_xss_protection => {:value => '1', :mode => false} # set the :mode option to block
|
||||
```ruby
|
||||
:x_content_type_options => {:value => 'nosniff'}
|
||||
:x_xss_protection => {:value => '1', :mode => false} # set the :mode option to block
|
||||
```
|
||||
|
||||
### Example CSP header config
|
||||
|
||||
**Configure the CSP header as if it were the w3c-style header, no need to supply 'options' or 'allow' directives.**
|
||||
|
||||
# most basic example
|
||||
:csp => {
|
||||
:default_src => "https://* inline eval",
|
||||
:report_uri => '/uri-directive'
|
||||
}
|
||||
# Chrome
|
||||
> "default-src 'unsafe-inline' 'unsafe-eval' https://* chrome-extension:; report-uri /uri-directive;"
|
||||
# Firefox
|
||||
> "options inline-script eval-script; allow https://*; report-uri /uri-directive;"
|
||||
```ruby
|
||||
# most basic example
|
||||
:csp => {
|
||||
:default_src => "https://* inline eval",
|
||||
:report_uri => '/uri-directive'
|
||||
}
|
||||
# Chrome
|
||||
> "default-src 'unsafe-inline' 'unsafe-eval' https://* chrome-extension:; report-uri /uri-directive;"
|
||||
# Firefox
|
||||
> "options inline-script eval-script; allow https://*; report-uri /uri-directive;"
|
||||
|
||||
# turn off inline scripting/eval
|
||||
:csp => {
|
||||
:default_src => 'https://*',
|
||||
:report_uri => '/uri-directive'
|
||||
}
|
||||
# Chrome
|
||||
> "default-src https://*; report-uri /uri-directive;"
|
||||
# Firefox
|
||||
> "allow https://*; report-uri /uri-directive;"
|
||||
# turn off inline scripting/eval
|
||||
:csp => {
|
||||
:default_src => 'https://*',
|
||||
:report_uri => '/uri-directive'
|
||||
}
|
||||
# Chrome
|
||||
> "default-src https://*; report-uri /uri-directive;"
|
||||
# Firefox
|
||||
> "allow https://*; report-uri /uri-directive;"
|
||||
|
||||
# Auction site wants to allow images from anywhere, plugin content from a list of trusted media providers (including a content distribution network), and scripts only from its server hosting sanitized JavaScript
|
||||
:csp => {
|
||||
:default_src => 'self',
|
||||
:img_src => '*',
|
||||
:object_src => ['media1.com', 'media2.com', '*.cdn.com'],
|
||||
# alternatively (NOT csv) :object_src => 'media1.com media2.com *.cdn.com'
|
||||
:script_src => 'trustedscripts.example.com'
|
||||
}
|
||||
# Chrome
|
||||
"default-src 'self'; img-src *; object-src media1.com media2.com *.cdn.com; script-src trustedscripts.example.com;"
|
||||
# Firefox
|
||||
"allow 'self'; img-src *; object-src media1.com media2.com *.cdn.com; script-src trustedscripts.example.com;"
|
||||
# Auction site wants to allow images from anywhere, plugin content from a list of trusted media providers (including a content distribution network), and scripts only from its server hosting sanitized JavaScript
|
||||
:csp => {
|
||||
:default_src => 'self',
|
||||
:img_src => '*',
|
||||
:object_src => ['media1.com', 'media2.com', '*.cdn.com'],
|
||||
# alternatively (NOT csv) :object_src => 'media1.com media2.com *.cdn.com'
|
||||
:script_src => 'trustedscripts.example.com'
|
||||
}
|
||||
# Chrome
|
||||
"default-src 'self'; img-src *; object-src media1.com media2.com *.cdn.com; script-src trustedscripts.example.com;"
|
||||
# Firefox
|
||||
"allow 'self'; img-src *; object-src media1.com media2.com *.cdn.com; script-src trustedscripts.example.com;"
|
||||
```
|
||||
|
||||
## Note on Firefox handling of CSP
|
||||
|
||||
|
|
@ -181,13 +199,17 @@ If you need to change the route for the internal forwarding point, be sure it ma
|
|||
|
||||
#### Rails 2
|
||||
|
||||
map.csp_endpoint
|
||||
```ruby
|
||||
map.csp_endpoint
|
||||
```
|
||||
|
||||
#### Rails 3
|
||||
|
||||
If the csp reporting endpoint is clobbered by another route, add:
|
||||
|
||||
match SecureHeaders::ContentSecurityPolicy::FF_CSP_ENDPOINT => "content_security_policy#scribe"
|
||||
```ruby
|
||||
match SecureHeaders::ContentSecurityPolicy::FF_CSP_ENDPOINT => "content_security_policy#scribe"
|
||||
```
|
||||
|
||||
## Authors
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче