secure_headers 3.4.0 → 4.0.0

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.
@@ -74,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)
@@ -83,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
@@ -103,26 +115,43 @@ module SecureHeaders
       end
     end
 
-    attr_accessor :dynamic_csp
-
     attr_writer :hsts, :x_frame_options, :x_content_type_options,
       :x_xss_protection, :x_download_options, :x_permitted_cross_domain_policies,
-      :referrer_policy
+      :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, :cookies, :hpkp, :hpkp_report_host
+    @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.referrer_policy = OPT_OUT
-      self.csp = self.class.send(:deep_copy, CSP::DEFAULT_CONFIG)
-      instance_eval &block if block_given?
+      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
@@ -130,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
@@ -140,6 +169,8 @@ 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
@@ -148,9 +179,6 @@ module SecureHeaders
 
     def opt_out(header)
       send("#{header}=", OPT_OUT)
-      if header == CSP::CONFIG_KEY
-        dynamic_csp = OPT_OUT
-      end
       self.cached_headers.delete(header)
     end
 
@@ -159,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.
@@ -181,31 +195,60 @@ 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 = self.class.send(:deep_copy_if_hash, 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
@@ -232,7 +275,7 @@ module SecureHeaders
       end
     end
 
-    # Public: Precompute the header names and values for this configuraiton.
+    # Public: Precompute the header names and values for this configuration.
     # Ensures that headers generated at configure time, not on demand.
     #
     # Returns the cached headers
@@ -258,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