secure_headers 1.1.1 → 2.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 16e634b2502cd5ee9d87fac9a9d2c6af9bc48fda
+  data.tar.gz: 1416e09703db75cdf25379a1273477f346080c72
+SHA512:
+  metadata.gz: d1483f86c255f59593766bf3312d0085df5b59281c2daf426c16bf930c92c06ae17c17e07984be696b1719336e89ea7000e19948713b310354c749200e2debd6
+  data.tar.gz: eaf23b06c98757048b1516d87e429a23b5c70606db476f90eb042250bbd863bd1fddfdbcf12a6fce51e077a0ee3e6332cedcc041514de6a0ce55295d77a4bd65

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 @@
+2.1.6

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,17 +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 'spork'
-  gem 'pry'
-  gem 'rspec'
-  gem 'guard-spork', :platform => :ruby_19
-  gem 'guard-rspec', :platform => :ruby_19
+  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,41 +1,18 @@
-# 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)
+- 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)
-
-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)
+- Public Key Pinning - Pin certificate fingerprints in the browser to prevent man-in-the-middle attacks due to compromised Certificate Authorites. [Public Key Pinnning  Specification](https://tools.ietf.org/html/draft-ietf-websec-key-pinning-21)
 
 ## 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
 
@@ -45,17 +22,18 @@ The following methods are going to be called, unless they are provided in a `ski
 
 * `:set_csp_header`
 * `:set_hsts_header`
+* `:set_hpkp_header`
 * `: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`
 
 ### Bonus Features
 
 This gem makes a few assumptions about how you will use some features.  For example:
 
 * 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
 
@@ -67,27 +45,39 @@ This gem makes a few assumptions about how you will use some features.  For exam
   config.x_frame_options = 'DENY'
   config.x_content_type_options = "nosniff"
   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://* self",
-    :frame_src => "https://* http://*.twimg.com http://itunes.apple.com",
-    :img_src => "https://*",
+    :default_src => "https: self",
+    :frame_src => "https: http:.twimg.com http://itunes.apple.com",
+    :img_src => "https:",
     :report_uri => '//example.com/uri-directive'
   }
+  config.hpkp = {
+    :max_age => 60.days.to_i,
+    :include_subdomains => true,
+    :report_uri => '//example.com/uri-directive',
+    :pins => [
+      {:sha256 => 'abc'},
+      {:sha256 => '123'}
+    ]
+  }
 end
 
-# and then simply include this in application_controller.rb
+# and then include this in application_controller.rb
 class ApplicationController < ActionController::Base
   ensure_security_headers
 end
 ```
 
-Or simply add it to application controller
+Or do the config as a parameter to `ensure_security_headers`
 
 ```ruby
 ensure_security_headers(
-  :hsts => {:include_subdomains, :x_frame_options => false},
+  :hsts => {:include_subdomains => true, :max_age => 20.years.to_i},
   :x_frame_options => 'DENY',
-  :csp => false)
+  :csp => false
+)
 ```
 
 ## Options for ensure\_security\_headers
@@ -107,14 +97,12 @@ This configuration will likely work for most applications without modification.
 :x_frame_options  => {:value => 'SAMEORIGIN'}
 :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
@@ -124,11 +112,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,
@@ -143,32 +126,12 @@ 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 => lambda { @script_nonce = SecureRandom.hex }
-  # which can be used to whitelist a script block:
-  # script_tag :nonce = @script_nonce { inline_script_call() }
 }
 ```
 
@@ -178,19 +141,19 @@ and [Mozilla CSP specification](https://wiki.mozilla.org/Security/CSP/Specificat
 ```ruby
 # most basic example
 :csp => {
-  :default_src => "https://* inline eval",
+  :default_src => "https: inline eval",
   :report_uri => '/uri-directive'
 }
 
-> "default-src 'unsafe-inline' 'unsafe-eval' 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'
 }
 
-> "default-src  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 => {
@@ -203,30 +166,169 @@ and [Mozilla CSP specification](https://wiki.mozilla.org/Security/CSP/Specificat
 "default-src  '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
+```
+
+### CSP Level 2 features
+
+*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.*
+
+#### Nonce
+
+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.
+
+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
+:csp => {
+  :default_src => 'self',
+  :script_src => 'self nonce'
+}
+```
+
+> 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>
+
+<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:
 
-Currently, Firefox does not support the w3c draft standard.  So there are a few steps taken to make the two interchangeable.
+```html
+<script nonce="/jRAxuLJsDXAxqhNBB7gg7h55KETtDQBXe4ZL+xIXwI=">
+console.log("nonced!")
+</script>
+```
 
-* 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`
+#### Hash
 
-### Adding the Firefox report forwarding endpoint
+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.
 
-**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!!!**
+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.
 
-#### Rails 2
+If you only have a few hashes, you can hardcode them for the entire app:
 
 ```ruby
-map.csp_endpoint
+  config.csp = {
+    :default_src => "https:",
+    :script_src => 'self'
+    :script_hashes => ['sha1-abc', 'sha1-qwe']
+  }
 ```
 
-#### Rails 3
+The following will work as well, but may not be as clear:
+
+```ruby
+  config.csp = {
+    :default_src => "https:",
+    :script_src => "self 'sha1-qwe'"
+  }
+```
 
-If the csp reporting endpoint is clobbered by another route, add:
+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
-post SecureHeaders::ContentSecurityPolicy::FF_CSP_ENDPOINT => "content_security_policy#scribe"
+# config.ru
+require 'secure_headers/headers/content_security_policy/script_hash_middleware'
+use ::SecureHeaders::ContentSecurityPolicy::ScriptHashMiddleware
+```
+
+```ruby
+  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 %>
+```
+
+### Public Key Pins
+
+Be aware that pinning error reporting is governed by the same rules as everything else. If you have a pinning failure that tries to report back to the same origin, by definition this will not work.
+
+```
+config.hpkp = {
+  max_age: 60.days.to_i,   # max_age is a required parameter
+  include_subdomains: true, # whether or not to apply pins to subdomains
+  # Per the spec, SHA256 hashes are the only currently supported format.
+  pins: [
+    {sha256: 'b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c'},
+    {sha256: '73a2c64f9545172c1195efb6616ca5f7afd1df6f245407cafb90de3998a1c97f'}
+  ],
+  enforce: true,            # defaults to false (report-only mode)
+  report_uri: '//example.com/uri-directive',
+  app_name: 'example',
+  tag_report_uri: true
+}
+```
+
 ### Using with Sinatra
 
 Here's an example using SecureHeaders for Sinatra applications:
@@ -242,12 +344,15 @@ 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"
   }
+  config.hpkp = false
 end
 
 class Donkey < Sinatra::Application
@@ -274,22 +379,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
@@ -299,12 +393,33 @@ 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/tree/master/csp) + [commonware](https://github.com/jsocol/commonware/tree/master/commonware/request)
+* Python - [django-csp](https://github.com/mozilla/django-csp/) + [commonware](https://github.com/jsocol/commonware/)
 * Go - [secureheader](https://github.com/kr/secureheader)
 
 ## Authors
@@ -321,6 +436,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