Skip to content

Latest commit

 

History

History
162 lines (134 loc) · 8.62 KB

README.md

File metadata and controls

162 lines (134 loc) · 8.62 KB
Raw

Secure Headers Build Status Code Climate Coverage Status

master represents the unreleased 4.x line. See the upgrading to 4.x doc for instructions on how to upgrade. Bug fixes should go in the 3.x branch for now.

The 3.x branch is moving into maintenance mode. See the upgrading to 3.x doc for instructions on how to upgrade including the differences and benefits of using the 3.x branch.

The 2.x branch will be not be maintained once 4.x is released. The documentation below only applies to the 3.x branch. See the 2.x README for the old way of doing things.

The gem will automatically apply several headers that are related to security. This includes:

It can also mark all http cookies with the Secure, HttpOnly and SameSite attributes (when configured to do so).

secure_headers is a library with a global config, per request overrides, and rack middleware that enables you customize your application settings.

Documentation

Getting Started

Rails 3+

For Rails 3+ applications, secure_headers has a railtie that should automatically include the middleware. If for some reason the middleware is not being included follow the instructions for Rails 2.

Rails 2

For Rails 2 or non-rails applications, an explicit statement is required to use the middleware component.

use SecureHeaders::Middleware

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 values. SecureHeaders::OPT_OUT will disable the header entirely.

Word of caution: The following is not a default configuration per se. It serves as a sample implementation of the configuration. You should read more about these headers and determine what is appropriate for your requirements.

SecureHeaders::Configuration.default do |config|
  config.cookies = {
    secure: true, # mark all cookies as "Secure"
    httponly: true, # mark all cookies as "HttpOnly"
    samesite: {
      lax: true # mark all cookies as SameSite=lax
    }
  }
  # Add "; preload" and submit the site to hstspreload.org for best protection.
  config.hsts = "max-age=#{20.years.to_i}; includeSubdomains"
  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.referrer_policy = "origin-when-cross-origin"
  config.clear_site_data = [
    "cache",
    "cookies",
    "storage",
    "executionContexts"
  ]
  config.expect_certificate_transparency = {
    enforce: false,
    max_age: 1.day.to_i,
    report_uri: "https://report-uri.io/example-ct"
  }
  config.csp = {
    # "meta" values. these will shape the header, but the values are not included in the header.
    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'),
    base_uri: %w('self'),
    block_all_mixed_content: true, # see http://www.w3.org/TR/mixed-content/
    child_src: %w('self'), # if child-src isn't supported, the value for frame-src will be set.
    connect_src: %w(wss:),
    font_src: %w('self' data:),
    form_action: %w('self' github.com),
    frame_ancestors: %w('none'),
    img_src: %w(mycdn.com data:),
    manifest_src: %w('self'),
    media_src: %w(utoob.com),
    object_src: %w('self'),
    sandbox: true, # true and [] will set a maximally restrictive setting
    plugin_types: %w(application/x-shockwave-flash),
    script_src: %w('self'),
    style_src: %w('unsafe-inline'),
    upgrade_insecure_requests: true, # see https://www.w3.org/TR/upgrade-insecure-requests/
    report_uri: %w(https://report-uri.io/example-csp)
  }
  # This is available only from 3.5.0; use the `report_only: true` setting for 3.4.1 and below.
  config.csp_report_only = config.csp.merge({
    img_src: %w(somewhereelse.com),
    report_uri: %w(https://report-uri.io/example-csp-report-only)
  })
  config.hpkp = {
    report_only: false,
    max_age: 60.days.to_i,
    include_subdomains: true,
    report_uri: "https://report-uri.io/example-hpkp",
    pins: [
      {sha256: "abc"},
      {sha256: "123"}
    ]
  }
end

Default values

All headers except for PublicKeyPins and ClearSiteData have a default value. The default set of headers is:

Content-Security-Policy: default-src 'self' https:; font-src 'self' https: data:; img-src 'self' https: data:; object-src 'none'; script-src https:; style-src 'self' https: 'unsafe-inline'
Strict-Transport-Security: max-age=631138519
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Frame-Options: sameorigin
X-Permitted-Cross-Domain-Policies: none
X-Xss-Protection: 1; mode=block

Similar libraries

License

Copyright 2013-2014 Twitter, Inc and other contributors.

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0