secure_headers 3.2.0 → 4.0.0

data/docs/hashes.md

@@ -0,0 +1,64 @@
+## Hash
+
+`script`/`style-src` hashes can be used to whitelist inline content that is static. This has the benefit of allowing inline content without opening up the possibility of dynamic javascript like you would with a `nonce`.
+
+You can add hash sources directly to your policy :
+
+```ruby
+::SecureHeaders::Configuration.default do |config|
+   config.csp = {
+     default_src: %w('self')
+
+     # this is a made up value but browsers will show the expected hash in the console.
+     script_src: %w(sha256-123456)
+   }
+ end
+ ```
+
+ You can also use the automated inline script detection/collection/computation of hash source values in your app.
+
+ ```bash
+ rake secure_headers:generate_hashes
+ ```
+
+ This will generate a file (`config/secure_headers_generated_hashes.yml` by default, you can override by setting `ENV["secure_headers_generated_hashes_file"]`) containing a mapping of file names with the array of hash values found on that page. When ActionView renders a given file, we check if there are any known hashes for that given file. If so, they are added as values to the header.
+
+```yaml
+---
+scripts:
+  app/views/asdfs/index.html.erb:
+  - "'sha256-yktKiAsZWmc8WpOyhnmhQoDf9G2dAZvuBBC+V0LGQhg='"
+styles:
+  app/views/asdfs/index.html.erb:
+  - "'sha256-SLp6LO3rrKDJwsG9uJUxZapb4Wp2Zhj6Bu3l+d9rnAY='"
+  - "'sha256-HSGHqlRoKmHAGTAJ2Rq0piXX4CnEbOl1ArNd6ejp2TE='"
+```
+
+##### Helpers
+
+**This will not compute dynamic hashes** by design. The output of both helpers will be a plain `script`/`style` tag without modification and the known hashes for a given file will be added to `script-src`/`style-src` when `hashed_javascript_tag` and `hashed_style_tag` are used. You can use `raise_error_on_unrecognized_hash = true` to be extra paranoid that you have precomputed hash values for all of your inline content. By default, this will raise an error in non-production environments.
+
+```erb
+<%= hashed_style_tag do %>
+body {
+  background-color: black;
+}
+<% end %>
+
+<%= hashed_style_tag do %>
+body {
+  font-size: 30px;
+  font-color: green;
+}
+<% end %>
+
+<%= hashed_javascript_tag do %>
+console.log(1)
+<% end %>
+```
+
+```
+Content-Security-Policy: ...
+ script-src 'sha256-yktKiAsZWmc8WpOyhnmhQoDf9G2dAZvuBBC+V0LGQhg=' ... ;
+ style-src 'sha256-SLp6LO3rrKDJwsG9uJUxZapb4Wp2Zhj6Bu3l+d9rnAY=' 'sha256-HSGHqlRoKmHAGTAJ2Rq0piXX4CnEbOl1ArNd6ejp2TE=' ...;
+```

data/docs/named_overrides_and_appends.md

@@ -0,0 +1,107 @@
+## Named Appends
+
+Named Appends are blocks of code that can be reused and composed during requests. e.g. If a certain partial is rendered conditionally, and the csp needs to be adjusted for that partial, you can create a named append for that situation. The value returned by the block will be passed into `append_content_security_policy_directives`. The current request object is passed as an argument to the block for even more flexibility.
+
+```ruby
+def show
+  if include_widget?
+    @widget = widget.render
+    use_content_security_policy_named_append(:widget_partial)
+  end
+end
+
+
+SecureHeaders::Configuration.named_append(:widget_partial) do |request|
+  SecureHeaders.override_x_frame_options(request, "DENY")
+  if request.controller_instance.current_user.in_test_bucket?
+    { child_src: %w(beta.thirdpartyhost.com) }
+  else
+    { child_src: %w(thirdpartyhost.com) }
+  end
+end
+```
+
+You can use as many named appends as you would like per request, but be careful because order of inclusion matters. Consider the following:
+
+```ruby
+SecureHeader::Configuration.default do |config|
+  config.csp = { default_src: %w('self')}
+end
+
+SecureHeaders::Configuration.named_append(:A) do |request|
+  { default_src: %w(myhost.com) }
+end
+
+SecureHeaders::Configuration.named_append(:B) do |request|
+  { script_src: %w('unsafe-eval') }
+end
+```
+
+The following code will produce different policies due to the way policies are normalized (e.g. providing a previously undefined directive that inherits from `default-src`, removing host source values when `*` is provided. Removing `'none'` when additional values are present, etc.):
+
+```ruby
+def index
+  use_content_security_policy_named_append(:A)
+  use_content_security_policy_named_append(:B)
+  # produces default-src 'self' myhost.com; script-src 'self' myhost.com 'unsafe-eval';
+end
+
+def show
+  use_content_security_policy_named_append(:B)
+  use_content_security_policy_named_append(:A)
+  # produces default-src 'self' myhost.com; script-src 'self' 'unsafe-eval';
+end
+```
+
+
+## Named overrides
+
+Named overrides serve two purposes:
+
+* To be able to refer to a configuration by simple name.
+* By precomputing the headers for a named configuration, the headers generated once and reused over every request.
+
+To use a named override, drop a `SecureHeaders::Configuration.override` block **outside** of method definitions and then declare which named override you'd like to use. You can even override an override.
+
+```ruby
+class ApplicationController < ActionController::Base
+  SecureHeaders::Configuration.default do |config|
+    config.csp = {
+      default_src: %w('self'),
+      script_src: %w(example.org)
+    }
+  end
+
+  # override default configuration
+  SecureHeaders::Configuration.override(:script_from_otherdomain_com) do |config|
+    config.csp[:script_src] << "otherdomain.com"
+  end
+
+  # overrides the :script_from_otherdomain_com configuration
+  SecureHeaders::Configuration.override(:another_config, :script_from_otherdomain_com) do |config|
+    config.csp[:script_src] << "evenanotherdomain.com"
+  end
+end
+
+class MyController < ApplicationController
+  def index
+    # Produces default-src 'self'; script-src example.org otherdomain.com
+    use_secure_headers_override(:script_from_otherdomain_com)
+  end
+
+  def show
+    # Produces default-src 'self'; script-src example.org otherdomain.org evenanotherdomain.com
+    use_secure_headers_override(:another_config)
+  end
+end
+```
+
+By default, a no-op configuration is provided. No headers will be set when this default override is used.
+
+```ruby
+class MyController < ApplicationController
+  def index
+    SecureHeaders.opt_out_of_all_protection(request)
+  end
+end
+```

data/docs/per_action_configuration.md

@@ -0,0 +1,133 @@
+## Per-action configuration
+
+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 = {
+     default_src: %w('self'),
+     script_src: %w('self')
+   }
+ end
+
+class MyController < ApplicationController
+  def index
+    # Append value to the source list, override 'none' values
+    # Produces: default-src 'self'; script-src 'self' s3.amazonaws.com; object-src 'self' www.youtube.com
+    append_content_security_policy_directives(script_src: %w(s3.amazonaws.com), object_src: %w('self' www.youtube.com))
+
+    # Overrides the previously set source list, override 'none' values
+    # Produces: default-src 'self'; script-src s3.amazonaws.com; object-src 'self'
+    override_content_security_policy_directives(script_src: %w(s3.amazonaws.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_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:)}`.
+
+#### Append to the policy with a directive other than `default_src`
+
+The value of `default_src` is joined with the addition if the it is a [fetch directive](https://w3c.github.io/webappsec-csp/#directives-fetch). 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.default do |config|
+   config.csp = {
+     default_src: %w('self')
+   }
+ end
+ ```
+
+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`
+
+#### Nonce
+
+You can use a view helper to automatically add nonces to script tags:
+
+```erb
+<%= nonced_javascript_tag do %>
+console.log("nonced!");
+<% end %>
+
+<%= nonced_style_tag do %>
+body {
+  background-color: black;
+}
+<% end %>
+```
+
+becomes:
+
+```html
+<script nonce="/jRAxuLJsDXAxqhNBB7gg7h55KETtDQBXe4ZL+xIXwI=">
+console.log("nonced!")
+</script>
+<style nonce="/jRAxuLJsDXAxqhNBB7gg7h55KETtDQBXe4ZL+xIXwI=">
+body {
+  background-color: black;
+}
+</style>
+```
+
+```
+
+Content-Security-Policy: ...
+  script-src 'nonce-/jRAxuLJsDXAxqhNBB7gg7h55KETtDQBXe4ZL+xIXwI=' ...;
+  style-src 'nonce-/jRAxuLJsDXAxqhNBB7gg7h55KETtDQBXe4ZL+xIXwI=' ...;
+```
+
+`script`/`style-nonce` can be used to whitelist inline content. To do this, call the `content_security_policy_script_nonce` or `content_security_policy_style_nonce` then set the nonce attributes on the various tags.
+
+```erb
+<script nonce="<%= content_security_policy_script_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>
+```
+
+## Clearing browser cache
+
+You can clear the browser cache after the logout request by using the following.
+
+``` ruby
+class ApplicationController < ActionController::Base
+  # Configuration override to send the Clear-Site-Data header.
+  SecureHeaders::Configuration.override(:clear_browser_cache) do |config|
+    config.clear_site_data = [
+      SecureHeaders::ClearSiteData::ALL_TYPES
+    ]
+  end
+
+
+  # Clears the browser's cache for browsers supporting the Clear-Site-Data
+  # header.
+  #
+  # Returns nothing.
+  def clear_browser_cache
+    SecureHeaders.use_secure_headers_override(request, :clear_browser_cache)
+  end
+end
+
+class SessionsController < ApplicationController
+  after_action  :clear_browser_cache, only: :destroy
+end
+```

data/docs/sinatra.md

@@ -0,0 +1,25 @@
+## Sinatra
+
+Here's an example using SecureHeaders for Sinatra applications:
+
+```ruby
+require 'rubygems'
+require 'sinatra'
+require 'haml'
+require 'secure_headers'
+
+use SecureHeaders::Middleware
+
+SecureHeaders::Configuration.default do |config|
+  ...
+end
+
+class Donkey < Sinatra::Application
+  set :root, APP_ROOT
+
+  get '/' do
+    SecureHeaders.override_x_frame_options(request, SecureHeaders::OPT_OUT)
+    haml :index
+  end
+end
+```

data/lib/secure_headers/configuration.rb

@@ -1,4 +1,5 @@
-require 'yaml'
+# frozen_string_literal: true
+require "yaml"
 
 module SecureHeaders
   class Configuration
@@ -31,7 +32,7 @@ module SecureHeaders
           raise NotYetConfiguredError, "#{base} policy not yet supplied"
         end
         override = @configurations[base].dup
-        override.instance_eval &block if block_given?
+        override.instance_eval(&block) if block_given?
         add_configuration(name, override)
       end
 
@@ -46,6 +47,17 @@ module SecureHeaders
         @configurations[name]
       end
 
+      def named_appends(name)
+        @appends ||= {}
+        @appends[name]
+      end
+
+      def named_append(name, target = nil, &block)
+        @appends ||= {}
+        raise "Provide a configuration block" unless block_given?
+        @appends[name] = block
+      end
+
       private
 
       # Private: add a valid configuration to the global set of named configs.
@@ -61,6 +73,7 @@ module SecureHeaders
         config.validate_config!
         @configurations ||= {}
         config.send(:cache_headers!)
+        config.send(:cache_hpkp_report_host)
         config.freeze
         @configurations[name] = config
       end
@@ -73,7 +86,6 @@ module SecureHeaders
           ALL_HEADER_CLASSES.each do |klass|
             config.send("#{klass::CONFIG_KEY}=", OPT_OUT)
           end
-          config.dynamic_csp = OPT_OUT
         end
 
         add_configuration(NOOP_CONFIGURATION, noop_config)
@@ -82,6 +94,7 @@ module SecureHeaders
       # Public: perform a basic deep dup. The shallow copy provided by dup/clone
       # can lead to modifying parent objects.
       def deep_copy(config)
+        return unless config
         config.each_with_object({}) do |(key, value), hash|
           hash[key] = if value.is_a?(Array)
             value.dup
@@ -104,21 +117,41 @@ module SecureHeaders
 
     attr_writer :hsts, :x_frame_options, :x_content_type_options,
       :x_xss_protection, :x_download_options, :x_permitted_cross_domain_policies,
-      :hpkp, :dynamic_csp, :cookies
+      :referrer_policy, :clear_site_data, :expect_certificate_transparency
+
+    attr_reader :cached_headers, :csp, :cookies, :csp_report_only, :hpkp, :hpkp_report_host
 
-    attr_reader :cached_headers, :csp, :dynamic_csp, :cookies
+    @script_hashes = nil
+    @style_hashes = nil
 
     HASH_CONFIG_FILE = ENV["secure_headers_generated_hashes_file"] || "config/secure_headers_generated_hashes.yml"
-    if File.exists?(HASH_CONFIG_FILE)
+    if File.exist?(HASH_CONFIG_FILE)
       config = YAML.safe_load(File.open(HASH_CONFIG_FILE))
       @script_hashes = config["scripts"]
       @style_hashes = config["styles"]
     end
 
     def initialize(&block)
+      @cookies = nil
+      @clear_site_data = nil
+      @csp = nil
+      @csp_report_only = nil
+      @hpkp_report_host = nil
+      @hpkp = nil
+      @hsts = nil
+      @x_content_type_options = nil
+      @x_download_options = nil
+      @x_frame_options = nil
+      @x_permitted_cross_domain_policies = nil
+      @x_xss_protection = nil
+      @expect_certificate_transparency = nil
+
       self.hpkp = OPT_OUT
-      self.csp = self.class.send(:deep_copy, CSP::DEFAULT_CONFIG)
-      instance_eval &block if block_given?
+      self.referrer_policy = OPT_OUT
+      self.csp = ContentSecurityPolicyConfig.new(ContentSecurityPolicyConfig::DEFAULT)
+      self.csp_report_only = OPT_OUT
+
+      instance_eval(&block) if block_given?
     end
 
     # Public: copy everything but the cached headers
@@ -126,9 +159,9 @@ module SecureHeaders
     # Returns a deep-dup'd copy of this configuration.
     def dup
       copy = self.class.new
-      copy.cookies = @cookies
-      copy.csp = self.class.send(:deep_copy_if_hash, @csp)
-      copy.dynamic_csp = self.class.send(:deep_copy_if_hash, @dynamic_csp)
+      copy.cookies = self.class.send(:deep_copy_if_hash, @cookies)
+      copy.csp = @csp.dup if @csp
+      copy.csp_report_only = @csp_report_only.dup if @csp_report_only
       copy.cached_headers = self.class.send(:deep_copy_if_hash, @cached_headers)
       copy.x_content_type_options = @x_content_type_options
       copy.hsts = @hsts
@@ -136,15 +169,16 @@ module SecureHeaders
       copy.x_xss_protection = @x_xss_protection
       copy.x_download_options = @x_download_options
       copy.x_permitted_cross_domain_policies = @x_permitted_cross_domain_policies
+      copy.clear_site_data = @clear_site_data
+      copy.expect_certificate_transparency = @expect_certificate_transparency
+      copy.referrer_policy = @referrer_policy
       copy.hpkp = @hpkp
+      copy.hpkp_report_host = @hpkp_report_host
       copy
     end
 
     def opt_out(header)
       send("#{header}=", OPT_OUT)
-      if header == CSP::CONFIG_KEY
-        dynamic_csp = OPT_OUT
-      end
       self.cached_headers.delete(header)
     end
 
@@ -153,20 +187,6 @@ module SecureHeaders
       self.cached_headers[XFrameOptions::CONFIG_KEY] = XFrameOptions.make_header(value)
     end
 
-    # Public: generated cached headers for a specific user agent.
-    def rebuild_csp_header_cache!(user_agent)
-      self.cached_headers[CSP::CONFIG_KEY] = {}
-      unless current_csp == OPT_OUT
-        user_agent = UserAgent.parse(user_agent)
-        variation = CSP.ua_to_variation(user_agent)
-        self.cached_headers[CSP::CONFIG_KEY][variation] = CSP.make_header(current_csp, user_agent)
-      end
-    end
-
-    def current_csp
-      @dynamic_csp || @csp
-    end
-
     # Public: validates all configurations values.
     #
     # Raises various configuration errors if any invalid config is detected.
@@ -175,37 +195,87 @@ module SecureHeaders
     def validate_config!
       StrictTransportSecurity.validate_config!(@hsts)
       ContentSecurityPolicy.validate_config!(@csp)
+      ContentSecurityPolicy.validate_config!(@csp_report_only)
+      ReferrerPolicy.validate_config!(@referrer_policy)
       XFrameOptions.validate_config!(@x_frame_options)
       XContentTypeOptions.validate_config!(@x_content_type_options)
       XXssProtection.validate_config!(@x_xss_protection)
       XDownloadOptions.validate_config!(@x_download_options)
       XPermittedCrossDomainPolicies.validate_config!(@x_permitted_cross_domain_policies)
+      ClearSiteData.validate_config!(@clear_site_data)
+      ExpectCertificateTransparency.validate_config!(@expect_certificate_transparency)
       PublicKeyPins.validate_config!(@hpkp)
       Cookie.validate_config!(@cookies)
     end
 
     def secure_cookies=(secure_cookies)
-      Kernel.warn "#{Kernel.caller.first}: [DEPRECATION] `#secure_cookies=` is deprecated. Please use `#cookies=` to configure secure cookies instead."
-      @cookies = (@cookies || {}).merge(secure: secure_cookies)
+      raise ArgumentError, "#{Kernel.caller.first}: `#secure_cookies=` is no longer supported. Please use `#cookies=` to configure secure cookies instead."
     end
 
-    protected
-
     def csp=(new_csp)
-      if self.dynamic_csp
-        raise IllegalPolicyModificationError, "You are attempting to modify CSP settings directly. Use dynamic_csp= instead."
+      if new_csp.respond_to?(:opt_out?)
+        @csp = new_csp.dup
+      else
+        if new_csp[:report_only]
+          # invalid configuration implies that CSPRO should be set, CSP should not - so opt out
+          raise ArgumentError, "#{Kernel.caller.first}: `#csp=` was supplied a config with report_only: true. Use #csp_report_only="
+        else
+          @csp = ContentSecurityPolicyConfig.new(new_csp)
+        end
       end
+    end
 
-      @csp = new_csp
+    # Configures the Content-Security-Policy-Report-Only header. `new_csp` cannot
+    # contain `report_only: false` or an error will be raised.
+    #
+    # NOTE: if csp has not been configured/has the default value when
+    # configuring csp_report_only, the code will assume you mean to only use
+    # report-only mode and you will be opted-out of enforce mode.
+    def csp_report_only=(new_csp)
+      @csp_report_only = begin
+        if new_csp.is_a?(ContentSecurityPolicyConfig)
+          new_csp.make_report_only
+        elsif new_csp.respond_to?(:opt_out?)
+          new_csp.dup
+        else
+          if new_csp[:report_only] == false # nil is a valid value on which we do not want to raise
+            raise ContentSecurityPolicyConfigError, "`#csp_report_only=` was supplied a config with report_only: false. Use #csp="
+          else
+            ContentSecurityPolicyReportOnlyConfig.new(new_csp)
+          end
+        end
+      end
+    end
+
+    protected
+
+    def cookies=(cookies)
+      @cookies = cookies
     end
 
     def cached_headers=(headers)
       @cached_headers = headers
     end
 
+    def hpkp=(hpkp)
+      @hpkp = self.class.send(:deep_copy_if_hash, hpkp)
+    end
+
+    def hpkp_report_host=(hpkp_report_host)
+      @hpkp_report_host = hpkp_report_host
+    end
+
     private
 
-    # Public: Precompute the header names and values for this configuraiton.
+    def cache_hpkp_report_host
+      has_report_uri = @hpkp && @hpkp != OPT_OUT && @hpkp[:report_uri]
+      self.hpkp_report_host = if has_report_uri
+        parsed_report_uri = URI.parse(@hpkp[:report_uri])
+        parsed_report_uri.host
+      end
+    end
+
+    # Public: Precompute the header names and values for this configuration.
     # Ensures that headers generated at configure time, not on demand.
     #
     # Returns the cached headers
@@ -231,12 +301,16 @@ module SecureHeaders
     #
     # Returns nothing
     def generate_csp_headers(headers)
-      unless @csp == OPT_OUT
-        headers[CSP::CONFIG_KEY] = {}
-        csp_config = self.current_csp
-        CSP::VARIATIONS.each do |name, _|
-          csp = CSP.make_header(csp_config, UserAgent.parse(name))
-          headers[CSP::CONFIG_KEY][name] = csp.freeze
+      generate_csp_headers_for_config(headers, ContentSecurityPolicyConfig::CONFIG_KEY, self.csp)
+      generate_csp_headers_for_config(headers, ContentSecurityPolicyReportOnlyConfig::CONFIG_KEY, self.csp_report_only)
+    end
+
+    def generate_csp_headers_for_config(headers, header_key, csp_config)
+      unless csp_config.opt_out?
+        headers[header_key] = {}
+        ContentSecurityPolicy::VARIATIONS.each do |name, _|
+          csp = ContentSecurityPolicy.make_header(csp_config, UserAgent.parse(name))
+          headers[header_key][name] = csp.freeze
         end
       end
     end

data/lib/secure_headers/hash_helper.rb

@@ -1,4 +1,5 @@
-require 'base64'
+# frozen_string_literal: true
+require "base64"
 
 module SecureHeaders
   module HashHelper

data/lib/secure_headers/headers/clear_site_data.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+module SecureHeaders
+  class ClearSiteDataConfigError < StandardError; end
+  class ClearSiteData
+    HEADER_NAME = "Clear-Site-Data".freeze
+
+    # Valid `types`
+    CACHE = "cache".freeze
+    COOKIES = "cookies".freeze
+    STORAGE = "storage".freeze
+    EXECUTION_CONTEXTS = "executionContexts".freeze
+    ALL_TYPES = [CACHE, COOKIES, STORAGE, EXECUTION_CONTEXTS]
+
+    CONFIG_KEY = :clear_site_data
+
+    class << self
+      # Public: make an Clear-Site-Data header name, value pair
+      #
+      # Returns nil if not configured, returns header name and value if configured.
+      def make_header(config = nil)
+        case config
+        when nil, OPT_OUT, []
+          # noop
+        when Array
+          [HEADER_NAME, make_header_value(config)]
+        when true
+          [HEADER_NAME, make_header_value(ALL_TYPES)]
+        end
+      end
+
+      def validate_config!(config)
+        case config
+        when nil, OPT_OUT, true
+          # valid
+        when Array
+          unless config.all? { |t| t.is_a?(String) }
+            raise ClearSiteDataConfigError.new("types must be Strings")
+          end
+        else
+          raise ClearSiteDataConfigError.new("config must be an Array of Strings or `true`")
+        end
+      end
+
+      # Public: Transform a Clear-Site-Data config (an Array of Strings) into a
+      # String that can be used as the value for the Clear-Site-Data header.
+      #
+      # types - An Array of String of types of data to clear.
+      #
+      # Returns a String of quoted values that are comma separated.
+      def make_header_value(types)
+        types.map { |t| "\"#{t}\""}.join(", ")
+      end
+    end
+  end
+end