README.md in secure_headers-1.0.0 vs README.md in secure_headers-1.1.0
- old
+ new
@@ -47,65 +47,68 @@
* `:set_hsts_header`
* `:set_x_frame_options_header`
* `:set_x_xss_protection_header`
* `:set_x_content_type_options_header`
-### Automagic
+### Bonus Features
This gem makes a few assumptions about how you will use some features. For example:
-* It adds 'chrome-extension:' to your CSP directives by default. This helps drastically reduce the amount of reports, but you can also disable this feature by supplying `:disable_chrome_extension => true`.
-* It fills any blank directives with the value in `:default_src` Getting a default\-src report is pretty useless. This way, you will always know what type of violation occurred. You can disable this feature by supplying `:disable_fill_missing => true`.
-* It copies the connect\-src value to xhr\-src for AJAX requests when using Firefox.
+* It fills any blank directives with the value in `:default_src` Getting a default\-src report is pretty useless. This way, you will always know what type of violation occurred. You can disable this feature by supplying `:disable_fill_missing => true`. This is referred to as the "effective-directive" in the spec, but is not well supported as of Nov 5, 2013.
* Firefox does not support cross\-origin CSP reports. If we are using Firefox, AND the value for `:report_uri` does not satisfy the same\-origin requirements, we will instead forward to an internal endpoint (`FF_CSP_ENDPOINT`). This is also the case if `:report_uri` only contains a path, which we assume will be cross host. This endpoint will in turn forward the request to the value in `:forward_endpoint` without restriction. More information can be found in the "Note on Firefox handling of CSP" section.
## Configuration
**Place the following in an initializer (recommended):**
```ruby
::SecureHeaders::Configuration.configure do |config|
- config.hsts = {:max_age => 99, :include_subdomains => true}
+ config.hsts = {:max_age => 20.years.to_i, :include_subdomains => true}
config.x_frame_options = 'DENY'
config.x_content_type_options = "nosniff"
- config.x_xss_protection = {:value => 1, :mode => false}
+ config.x_xss_protection = {:value => 1, :mode => 'block'}
config.csp = {
- :default_src => "https://* inline eval",
- :report_uri => '//example.com/uri-directive',
- :img_src => "https://* data:",
- :frame_src => "https://* http://*.twimg.com http://itunes.apple.com"
+ :default_src => "https://* self",
+ :frame_src => "https://* http://*.twimg.com http://itunes.apple.com",
+ :img_src => "https://*",
+ :report_uri => '//example.com/uri-directive'
}
end
-# and then simply include this in application_controller
-ensure_security_headers
+# and then simply include this in application_controller.rb
+class ApplicationController < ActionController::Base
+ ensure_security_headers
+end
```
-Or simply add it to application controller (not recommended, currently a bug)
+Or simply add it to application controller
```ruby
-ensure_security_headers
+ensure_security_headers(
:hsts => {:include_subdomains, :x_frame_options => false},
:x_frame_options => 'DENY',
- :csp => false
+ :csp => false)
```
## Options for ensure\_security\_headers
**To disable any of these headers, supply a value of false (e.g. :hsts => false), supplying nil will set the default value**
Each header configuration can take a hash, or a string, or both. If a string
is provided, that value is inserted verbatim. If a hash is supplied, a
header will be constructed using the supplied options.
-### Widely supported
+### The Easy Headers
+This configuration will likely work for most applications without modification.
+
```ruby
-:hsts => {:max_age => 631138519, :include_subdomains => true}
+:hsts => {:max_age => 631138519, :include_subdomains => false}
:x_frame_options => {:value => 'SAMEORIGIN'}
-:x_xss_protection => {:value => 1, :mode => false} # set the :mode option to 'block' to enforce the browser's xss filter
+:x_xss_protection => {:value => 1, :mode => 'block'} # set the :mode option to false to use "warning only" mode
+:x_content_type_options => {:value => 'nosniff'}
```
### Content Security Policy (CSP)
All browsers will receive the webkit csp header except Firefox, which gets its own header.
@@ -157,75 +160,56 @@
:img_src => 'https://mycdn.example.com',
:http_additions {
:img_src => 'http://mycdn.example.com'
}
}
-
+
# script-nonce is an experimental feature of CSP 1.1 available in Chrome. It allows
# you to whitelist inline script blocks. For more information, see
# https://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html#script-nonce
- :script_nonce => { 'abc123' }
-
- # you can also use lambdas to use dynamically generated nonces
- :script_nonce => lambda { @script_nonce] = 'something' }
+ :script_nonce => lambda { @script_nonce = SecureRandom.hex }
# which can be used to whitelist a script block:
# script_tag :nonce = @script_nonce { inline_script_call() }
}
```
-### Only applied to IE
-
-```ruby
-:x_content_type_options => {:value => 'nosniff'}
-```
-
### Example CSP header config
-**Configure the CSP header as if it were the webkit-style header, no need to supply 'options' or 'allow' directives.**
```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;"
+> "default-src 'unsafe-inline' 'unsafe-eval' 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;"
```
## Note on Firefox handling of CSP
Currently, Firefox does not support the w3c draft standard. So there are a few steps taken to make the two interchangeable.
-* inline\-script or eval\-script values in default/style/script\-src directives are moved to the options directive. Note: the style\-src directive is not fully supported in Firefox \- see https://bugzilla.mozilla.org/show_bug.cgi?id=763879.
* CSP reports will not POST cross\-origin. This sets up an internal endpoint in the application that will forward the request. Set the `forward_endpoint` value in the CSP section if you need to post cross origin for firefox. The internal endpoint that receives the initial request will forward the request to `forward_endpoint`
-* Ffirefox adds port numbers to each /https?/ value which can make local development tricky with mocked services. Add environment specific code to configure this.
### Adding the Firefox report forwarding endpoint
**You need to add the following line to the TOP of confib/routes.rb**
**This is an unauthenticated, unauthorized endpoint. Only do this if your report\-uri is not on the same origin as your application!!!**
@@ -313,9 +297,16 @@
end
end
end
```
+## Similar libraries
+
+* Node.js (express) [helmet](https://github.com/evilpacket/helmet) and [hood](https://github.com/seanmonstar/hood)
+* J2EE Servlet >= 3.0 [highlines](https://github.com/sourceclear/headlines)
+* ASP.NET - [NWebsec](http://nwebsec.codeplex.com/)
+* Python - [django-csp](https://github.com/mozilla/django-csp/tree/master/csp) + [commonware](https://github.com/jsocol/commonware/tree/master/commonware/request)
+* Go - [secureheader](https://github.com/kr/secureheader)
## Authors
* Neil Matatall [@ndm](https://twitter.com/ndm) - primary author.
* Nicholas Green [@nickgreen](https://twitter.com/nickgreen) - code contributions, main reviewer.