secure_headers 1.0.0 → 2.0.0

data/.gitignore

@@ -1,4 +1,5 @@
 *.gem
+*.DS_STORE
 *.rbc
 .bundle
 .config
@@ -15,12 +16,7 @@ rdoc
 spec/reports
 test/tmp
 test/version_tmp
-tmp
-
-/fixtures/rails_3_2_12/log/test.log
-/fixtures/rails_3_2_12_no_init/log/test.log
+*tmp
 *.sqlite3
-test.sqlite3
-*test.sqlite3
-/fixtures/rails_3_2_12_no_init/db/test.sqlite3
-/fixtures/rails_3_2_12/db/test.sqlite3
+fixtures/rails_3_2_12_no_init/log
+fixtures/rails_3_2_12/log

data/.ruby-gemset

@@ -0,0 +1 @@
+secureheaders

data/.ruby-version

@@ -0,0 +1 @@
+ruby-1.9.3-p484

data/.travis.yml

@@ -1,6 +1,11 @@
+language: ruby
+
 rvm:
+  - "2.1"
+  - "2.0.0"
   - "1.9.3"
   - "1.8.7"
-#  - jruby-19mode
-#  - jruby-18mode
-#script: ./travis.sh
+  - "jruby-19mode"
+
+sudo: false
+cache: bundler

data/Gemfile

@@ -4,14 +4,12 @@ gemspec
 
 group :test do
   gem 'rails', '3.2.12'
-  gem 'sqlite3', :platform => [:ruby, :mswin, :mingw]
-  gem 'jdbc-sqlite3', :platform => :jruby
-  gem 'rspec-rails'
-  gem 'guard-spork'
-  gem 'guard-rspec'
+  gem 'sqlite3', :platforms => [:ruby, :mswin, :mingw]
+  gem 'jdbc-sqlite3', :platforms => [:jruby]
+  gem 'rspec-rails', '>= 3.1'
+  gem 'rspec', '>= 3.1'
   gem 'growl'
   gem 'rb-fsevent'
-  gem 'simplecov'
-  gem 'debugger', :platform => :ruby_19
-  gem 'ruby-debug', :platform => :ruby_18
+  gem 'coveralls', :platforms => [:ruby_19]
+  gem 'i18n', '< 0.7.0', :platforms => [:ruby_18]
 end

data/README.md

@@ -1,4 +1,4 @@
-# SecureHeaders [![Build Status](https://travis-ci.org/twitter/secureheaders.png?branch=master)](http://travis-ci.org/twitter/secureheaders) [![Code Climate](https://codeclimate.com/github/twitter/secureheaders.png)](https://codeclimate.com/github/twitter/secureheaders)
+# SecureHeaders [![Build Status](https://travis-ci.org/twitter/secureheaders.png?branch=master)](http://travis-ci.org/twitter/secureheaders) [![Code Climate](https://codeclimate.com/github/twitter/secureheaders.png)](https://codeclimate.com/github/twitter/secureheaders) [![Coverage Status](https://coveralls.io/repos/twitter/secureheaders/badge.png)](https://coveralls.io/r/twitter/secureheaders)
 
 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 1.1 Specification](https://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html)
@@ -6,36 +6,12 @@ The gem will automatically apply several headers that are related to security.
 - 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)
-
-This gem has integration with Rails, but works for any Ruby code. See the sinatra example section.
-
-## Installation
-
-Add to your Gemfile
-
-```ruby
-gem 'secure_headers'
-```
-
-And then execute:
-
-```console
-$ bundle
-```
-
-Or install it yourself as:
-
-```console
-$ gem install secure_headers
-```
+- X-Download-Options - [Prevent file downloads opening](http://msdn.microsoft.com/en-us/library/ie/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)
 
 ## Usage
 
-Functionality provided
-
-- `ensure_security_headers`: will set security-related headers automatically based on the configuration below.
-
-By default, it will set all of the headers listed in the options section below unless specified.
+- `ensure_security_headers` in a controller will set security-related headers automatically based on the configuration below.
 
 ### Disabling
 
@@ -48,16 +24,14 @@ The following methods are going to be called, unless they are provided in a `ski
 * `:set_x_frame_options_header`
 * `:set_x_xss_protection_header`
 * `:set_x_content_type_options_header`
+* `:set_x_download_options_header`
+* `:set_x_permitted_cross_domain_policies_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.
-* 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.
-
+* 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.
 
 ## Configuration
 
@@ -65,29 +39,34 @@ This gem makes a few assumptions about how you will use some features.  For exam
 
 ```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.x_download_options = 'noopen'
+  config.x_permitted_cross_domain_policies = 'none'
   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
-  :hsts => {:include_subdomains, :x_frame_options => false},
+ensure_security_headers(
+  :hsts => {:include_subdomains => true, :max_age => 20.years.to_i},
   :x_frame_options => 'DENY',
   :csp => false
+)
 ```
 
 ## Options for ensure\_security\_headers
@@ -98,20 +77,21 @@ 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'}
+:x_download_options => {:value => 'noopen'}
+:x_permitted_cross_domain_policies => {:value => 'none'}
 ```
 
 ### Content Security Policy (CSP)
 
-All browsers will receive the webkit csp header except Firefox, which gets its own header.
-See [WebKit specification](http://www.w3.org/TR/CSP/)
-and [Mozilla CSP specification](https://wiki.mozilla.org/Security/CSP/Specification)
-
 ```ruby
 :csp => {
   :enforce     => false,        # sets header to report-only, by default
@@ -121,11 +101,6 @@ and [Mozilla CSP specification](https://wiki.mozilla.org/Security/CSP/Specificat
   # Where reports are sent. Use protocol relative URLs if you are posting to the same domain (TLD+1). Use paths if you are posting to the application serving the header
   :report_uri  => '//mysite.example.com',
 
-  # Send reports that cannot be sent across host here. These requests are sent
-  # the server, not the browser. If no value is supplied, it will default to
-  # the value in report_uri. Use this if you cannot use relative protocols mentioned above due to host mismatches.
-  :forward_endpoint => 'https://internal.mylogaggregator.example.com'
-
   # these directives all take 'none', 'self', or a globbed pattern
   :img_src     => nil,
   :frame_src   => nil,
@@ -140,68 +115,34 @@ and [Mozilla CSP specification](https://wiki.mozilla.org/Security/CSP/Specificat
   # over http, relaxing the policy
   # e.g.
   # :csp => {
-  #   :img_src => 'https://*',
-  #   :http_additions => {:img_src => 'http//*'}
+  #   :img_src => 'https:',
+  #   :http_additions => {:img_src => 'http'}
   # }
-  # would produce the directive: "img-src https://* http://*;"
+  # would produce the directive: "img-src https: http:;"
   # when over http, ignored for https requests
   :http_additions => {}
-
-  # If you have enforce => true, you can use the `experiments` block to
-  # also produce a report-only header. Values in this block override the
-  # parent config for the report-only, and leave the enforcing header
-  # unaltered. http_additions work the same way described above, but
-  # are added to your report-only header as expected.
-  :experimental => {
-    :script_src => 'self',
-    :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' } 
-  # 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",
+  :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://*',
+  :default_src => 'https:',
   :report_uri => '/uri-directive'
 }
-# Chrome
-> "default-src  https://*; report-uri /uri-directive;"
-# Firefox
-> "allow https://*; report-uri /uri-directive;"
+
+> "default-src  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 => {
@@ -211,38 +152,152 @@ and [Mozilla CSP specification](https://wiki.mozilla.org/Security/CSP/Specificat
   # 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
+### Tagging Requests
+
+It's often valuable to send extra information in the report uri that is not available in the reports themselves. Namely, "was the policy enforced" and "where did the report come from"
+
+```ruby
+{
+  :tag_report_uri => true,
+  :enforce => true,
+  :app_name => 'twitter',
+  :report_uri => 'csp_reports'
+}
+```
+
+Results in
+```
+report-uri csp_reports?enforce=true&app_name=twitter
+```
 
-Currently, Firefox does not support the w3c draft standard.  So there are a few steps taken to make the two interchangeable.
+### CSP Level 2 features
 
-* 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.
+*NOTE: Currently, only erb is supported. Mustache support isn't far off. Hash sources are valid for inline style blocks but are not yet supported by secure_headers.*
 
-### Adding the Firefox report forwarding endpoint
+#### Nonce
 
-**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!!!**
+script/style-nonce can be used to whitelist inline content. To do this, add "nonce" to your script/style-src configuration, then set the nonce attributes on the various tags.
 
-#### Rails 2
+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.
 
 ```ruby
-map.csp_endpoint
+:csp => {
+  :default_src => 'self',
+  :script_src => 'self nonce'
+}
 ```
 
-#### Rails 3
+> content-security-policy: default-src 'self'; script-src 'self' 'nonce-abc123' 'unsafe-inline'
+
+```erb
+<script nonce="<%= @content_security_policy_nonce %>">
+  console.log("whitelisted, will execute")
+</script>
 
-If the csp reporting endpoint is clobbered by another route, add:
+<script nonce="lol">
+  console.log("won't execute, not whitelisted")
+</script>
+
+<script>
+  console.log("won't execute, not whitelisted")
+</script>
+```
+You can use a view helper to automatically add nonces to script tags:
+```erb
+<%= nonced_javascript_tag do %>
+  console.log("nonced!")
+<% end %>
+<%= nonced_javascript_tag("nonced without a block!") %>
+```
+
+becomes:
+
+```html
+<script nonce="/jRAxuLJsDXAxqhNBB7gg7h55KETtDQBXe4ZL+xIXwI=">
+console.log("nonced!")
+</script>
+```
+
+#### Hash
+
+setting hash source values will also set 'unsafe-inline' for browsers that don't support hash sources for backwards compatibility. 'unsafe-inline' is ignored if a hash is present in a directive in compliant browsers.
+
+Hash source support works by taking the hash value of the contents of an inline script block and adding the hash "fingerprint" to the CSP header.
+
+If you only have a few hashes, you can hardcode them for the entire app:
+
+```ruby
+  config.csp = {
+    :default_src => "https:",
+    :script_src => 'self'
+    :script_hashes => ['sha1-abc', 'sha1-qwe']
+  }
+```
+
+The following will work as well, but may not be as clear:
+
+```ruby
+  config.csp = {
+    :default_src => "https:",
+    :script_src => "self 'sha1-qwe'"
+  }
+```
+
+If you find you have many hashes or the content of the script tags change frequently, you can apply these hashes in a more intelligent way. This method expects config/script_hashes.yml to contain a map of templates => [hashes]. When the individual templates, layouts, or partials are rendered the hash values for the script tags in those templates will be automatically added to the header. *Currently, only erb layouts are supported.* This requires the use of middleware:
+
+```ruby
+# config.ru
+require 'secure_headers/headers/content_security_policy/script_hash_middleware'
+use ::SecureHeaders::ContentSecurityPolicy::ScriptHashMiddleware
+```
 
 ```ruby
-post SecureHeaders::ContentSecurityPolicy::FF_CSP_ENDPOINT => "content_security_policy#scribe"
+  config.csp = {
+    :default_src => "https:",
+    :script_src => 'self',
+    :script_hash_middleware => true
+  }
+```
+
+Hashes are stored in a yaml file with a mapping of Filename => [list of hashes] in config/script_hashes.yml. You can automatically populate this file by running the following rake task:
+
+```$ bundle exec rake secure_headers:generate_hashes```
+
+Which will generate something like:
+
+```yaml
+# config/script_hashes.yml
+app/views/layouts/application.html.erb:
+- sha256-l8OLjZqYRnKilpdE0VosRMvhdYArjXT4NZaK2p7QVvs=
+app/templates/articles/edit.html.erb:
+- sha256-+7mij1/uCwtCQRWrof2NmOln5qX+5WdVwTLMpi8nuoA=
+- sha256-Ny4TRIhhFpnYnSeKC274P6bfAz4TOkezLabavIAU4dA=
+- sha256-I5e58Gqbu4WpO9dck18QxO7aYOHKrELIi70it4jIPi0=
+- sha256-Po4LMynwnAJHxiTp3DQaQ3YDBj3paN/xrDoKl4OyxY4=
+```
+
+In this example, if we visit /articles/edit/[id], the above hashes will automatically be added to the CSP header's
+script-src value!
+
+You can use plain "script" tags or you can use a built-in helper:
+
+```erb
+<%= hashed_javascript_tag do %>
+console.log("hashed automatically!")
+<% end %>
+```
+
+By using the helper, hash values will be computed dynamically in development/test environments. If a dynamically computed hash value does not match what is expected to be found in config/script_hashes.yml a warning message will be printed to the console. If you want to raise exceptions instead, use:
+
+```erb
+<%= hashed_javascript_tag(raise_error_on_unrecognized_hash = true) do %>
+console.log("will raise an exception if not in script_hashes.yml!")
+<% end %>
 ```
+
 ### Using with Sinatra
 
 Here's an example using SecureHeaders for Sinatra applications:
@@ -258,11 +313,13 @@ require 'secure_headers'
   config.x_frame_options = 'DENY'
   config.x_content_type_options = "nosniff"
   config.x_xss_protection = {:value => 1, :mode => false}
+  config.x_download_options = 'noopen'
+  config.x_permitted_cross_domain_policies = 'none'
   config.csp = {
-    :default_src => "https://* inline eval",
+    :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"
+    :img_src => "https: data:",
+    :frame_src => "https: http:.twimg.com http://itunes.apple.com"
   }
 end
 
@@ -290,22 +347,11 @@ In your `Gemfile`:
 then in your `app.rb` file you can:
 
 ```ruby
+require 'secure_headers/padrino'
+
 module Web
   class App < Padrino::Application
-    include SecureHeaders
-
-    ::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",
-        :report_uri => '//example.com/uri-directive',
-        :img_src => "https://* data:",
-        :frame_src => "https://* http://*.twimg.com http://itunes.apple.com"
-      }
-    end
+    register SecureHeaders::Padrino
 
     get '/' do
       set_csp_header
@@ -315,6 +361,34 @@ module Web
 end
 ```
 
+and in `config/boot.rb`:
+
+```ruby
+def before_load
+  ::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.x_download_options     = 'noopen'
+    config.x_permitted_cross_domain_policies = 'none'
+    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"
+    }
+  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/) + [commonware](https://github.com/jsocol/commonware/)
+* Go - [secureheader](https://github.com/kr/secureheader)
 
 ## Authors
 
@@ -330,6 +404,6 @@ end
 
 ## License
 
-Copyright 2013 Twitter, Inc.
+Copyright 2013-2014 Twitter, Inc and other contributors.
 
 Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0