README.md in secure_headers-3.0.0.pre2 vs README.md in secure_headers-3.0.0.pre3
- old
+ new
@@ -1,44 +1,52 @@
-# SecureHeaders [](http://travis-ci.org/twitter/secureheaders) [](https://codeclimate.com/github/twitter/secureheaders) [](https://coveralls.io/r/twitter/secureheaders)
+# Secure Headers [](http://travis-ci.org/twitter/secureheaders) [](https://codeclimate.com/github/twitter/secureheaders) [](https://coveralls.io/r/twitter/secureheaders)
+
**The 3.x branch was recently merged**. See the [upgrading to 3.x doc](upgrading-to-3-0.md) for instructions on how to upgrade including the differences and benefits of using the 3.x branch.
-**The [2.x branch](https://github.com/twitter/secureheaders/tree/2.x) will be maintained**. The documentation below only applies to the 2.x branch. See the 2.x [README](https://github.com/twitter/secureheaders/blob/2.x/README.md) for the old way of doing things.
+**The [2.x branch](https://github.com/twitter/secureheaders/tree/2.x) will be maintained**. The documentation below only applies to the 3.x branch. See the 2.x [README](https://github.com/twitter/secureheaders/blob/2.x/README.md) for the old way of doing things.
The gem will automatically apply several headers that are related to security. This includes:
- Content Security Policy (CSP) - Helps detect/prevent XSS, mixed-content, and other classes of attack. [CSP 2 Specification](http://www.w3.org/TR/CSP2/)
- HTTP Strict Transport Security (HSTS) - Ensures the browser never visits the http version of a website. Protects from SSLStrip/Firesheep attacks. [HSTS Specification](https://tools.ietf.org/html/rfc6797)
- X-Frame-Options (XFO) - Prevents your content from being framed and potentially clickjacked. [X-Frame-Options draft](https://tools.ietf.org/html/draft-ietf-websec-x-frame-options-02)
-- X-XSS-Protection - [Cross site scripting heuristic filter for IE/Chrome](http://msdn.microsoft.com/en-us/library/dd565647\(v=vs.85\).aspx)
-- X-Content-Type-Options - [Prevent content type sniffing](http://msdn.microsoft.com/en-us/library/ie/gg622941\(v=vs.85\).aspx)
-- X-Download-Options - [Prevent file downloads opening](http://msdn.microsoft.com/en-us/library/ie/jj542450(v=vs.85).aspx)
+- X-XSS-Protection - [Cross site scripting heuristic filter for IE/Chrome](https://msdn.microsoft.com/en-us/library/dd565647\(v=vs.85\).aspx)
+- X-Content-Type-Options - [Prevent content type sniffing](https://msdn.microsoft.com/library/gg622941\(v=vs.85\).aspx)
+- X-Download-Options - [Prevent file downloads opening](https://msdn.microsoft.com/library/jj542450(v=vs.85).aspx)
- X-Permitted-Cross-Domain-Policies - [Restrict Adobe Flash Player's access to data](https://www.adobe.com/devnet/adobe-media-server/articles/cross-domain-xml-for-streaming.html)
- Public Key Pinning - Pin certificate fingerprints in the browser to prevent man-in-the-middle attacks due to compromised Certificate Authorities. [Public Key Pinning Specification](https://tools.ietf.org/html/rfc7469)
-`secure_headers` is a library with a global config, per request overrides, and rack milddleware that enables you customize your application settings.
+`secure_headers` is a library with a global config, per request overrides, and rack middleware that enables you customize your application settings.
+## Use
+
+`gem install secure_headers`
+
## Configuration
If you do not supply a `default` configuration, exceptions will be raised. If you would like to use a default configuration (which is fairly locked down), just call `SecureHeaders::Configuration.default` without any arguments or block.
-All `nil` values will fallback to their default value. `SecureHeaders::OPT_OUT` will disable the header entirely.
+All `nil` values will fallback to their default values. `SecureHeaders::OPT_OUT` will disable the header entirely.
```ruby
SecureHeaders::Configuration.default do |config|
config.hsts = "max-age=#{20.years.to_i}"
config.x_frame_options = "DENY"
config.x_content_type_options = "nosniff"
config.x_xss_protection = "1; mode=block"
config.x_download_options = "noopen"
config.x_permitted_cross_domain_policies = "none"
config.csp = {
+ # "meta" values. these will shaped the header, but the values are not included in the header.
+ report_only: true, # default: false
+ preserve_schemes: true, # default: false. Schemes are removed from host sources to save bytes and discourage mixed content.
+
+ # directive values: these values will directly translate into source directives
default_src: %w(https: 'self'),
- report_only: false,
- frame_src: %w(*.twimg.com itunes.apple.com),
+ frame_src: %w('self' *.twimg.com itunes.apple.com),
connect_src: %w(wws:),
font_src: %w('self' data:),
- frame_src: %w('self'),
img_src: %w(mycdn.com data:),
media_src: %w(utoob.com),
object_src: %w('self'),
script_src: %w('self'),
style_src: %w('unsafe-inline'),
@@ -127,11 +135,11 @@
end
```
## Per-action configuration
-You can override the settings for a given action by producing a temporary override. This approach is not recommended because the header values will be computed per request.
+You can override the settings for a given action by producing a temporary override. Be aware that because of the dynamic nature of the value, the header values will be computed per request.
```ruby
# Given a config of:
::SecureHeaders::Configuration.default do |config|
config.csp = {
@@ -146,20 +154,20 @@
# Produces: default-src 'self'; script-src 'self' s3.amazaonaws.com; object-src 'self' youtube.com
append_content_security_policy_directives(script_src: %w(s3.amazaonaws.com), object_src: %w('self' youtube.com))
# Overrides the previously set source list, override 'none' values
# Produces: default-src 'self'; script-src s3.amazaonaws.com; object-src 'self'
- override_content_security_policy_directive(script_src: %w(s3.amazaonaws.com), object_src: %w('self'))
+ override_content_security_policy_directives(script_src: %w(s3.amazaonaws.com), object_src: %w('self'))
# Global settings default to "sameorigin"
override_x_frame_options("DENY")
end
```
The following methods are available as controller instance methods. They are also available as class methods, but require you to pass in the `request` object.
* `append_content_security_policy_directives(hash)`: appends each value to the corresponding CSP app-wide configuration.
-* `override_content_security_policy_directive(hash)`: merges the hash into the app-wide configuration, overwriting any previous config
+* `override_content_security_policy_directives(hash)`: merges the hash into the app-wide configuration, overwriting any previous config
* `override_x_frame_options(value)`: sets the `X-Frame-Options header` to `value`
## Appending / overriding Content Security Policy
When manipulating content security policy, there are a few things to consider. The default header value is `default-src https:` which corresponds to a default configuration of `{ default_src: %w(https:)}`.
@@ -167,11 +175,11 @@
#### Append to the policy with a directive other than `default_src`
The value of `default_src` is joined with the addition. Note the `https:` is carried over from the `default-src` config. If you do not want this, use `override_content_security_policy_directives` instead. To illustrate:
```ruby
-::SecureHeaders::Configuration.configure do |config|
+::SecureHeaders::Configuration.default do |config|
config.csp = {
default_src: %w('self')
}
end
```
@@ -179,15 +187,10 @@
Code | Result
------------- | -------------
`append_content_security_policy_directives(script_src: %w(mycdn.com))` | `default-src 'self'; script-src 'self' mycdn.com`
`override_content_security_policy_directives(script_src: %w(mycdn.com))` | `default-src 'self'; script-src mycdn.com`
-Code | Result
-------------- | -------------
-`append_content_security_policy_directives(script_src: %w(mycdn.com))` | `default-src https:; script-src https: mycdn.com`
-`override_content_security_policy_directives(script_src: %w(mycdn.com))` | `default-src https:; script-src mycdn.com`
-
#### Nonce
script/style-nonce can be used to whitelist inline content. To do this, call the SecureHeaders::content_security_policy_nonce then set the nonce attributes on the various tags.
Setting a nonce will also set 'unsafe-inline' for browsers that don't support nonces for backwards compatibility. 'unsafe-inline' is ignored if a nonce is present in a directive in compliant browsers.
@@ -267,11 +270,11 @@
require 'haml'
require 'secure_headers'
use SecureHeaders::Middleware
-SecureHeaders::Configuration.configure do |config|
+SecureHeaders::Configuration.default do |config|
...
end
class Donkey < Sinatra::Application
set :root, APP_ROOT
@@ -312,24 +315,25 @@
and in `config/boot.rb`:
```ruby
def before_load
- SecureHeaders::Configuration.configure do |config|
+ SecureHeaders::Configuration.default do |config|
...
end
end
```
## Similar libraries
-* Rack [rack-secure_headers](https://github.com/harmoni/rack-secure_headers)
-* Node.js (express) [helmet](https://github.com/evilpacket/helmet) and [hood](https://github.com/seanmonstar/hood)
+* Rack [rack-secure_headers](https://github.com/frodsan/rack-secure_headers)
+* Node.js (express) [helmet](https://github.com/helmetjs/helmet) and [hood](https://github.com/seanmonstar/hood)
* Node.js (hapi) [blankie](https://github.com/nlf/blankie)
* J2EE Servlet >= 3.0 [headlines](https://github.com/sourceclear/headlines)
* ASP.NET - [NWebsec](https://github.com/NWebsec/NWebsec/wiki)
* Python - [django-csp](https://github.com/mozilla/django-csp) + [commonware](https://github.com/jsocol/commonware/); [django-security](https://github.com/sdelements/django-security)
* Go - [secureheader](https://github.com/kr/secureheader)
+* Elixir [secure_headers](https://github.com/anotherhale/secure_headers)
## License
Copyright 2013-2014 Twitter, Inc and other contributors.