From ef5e1a8c95896993a97bb9e27326c9b6ae71b53a Mon Sep 17 00:00:00 2001 From: Artur Dryomov Date: Fri, 25 Jan 2013 01:27:37 +0300 Subject: [PATCH 1/2] Use syntax highlighting in the readme file. --- README.md | 196 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 109 insertions(+), 87 deletions(-) diff --git a/README.md b/README.md index 5681afd..de36b2a 100644 --- a/README.md +++ b/README.md @@ -11,15 +11,21 @@ The gem will automatically apply several headers that are related to security. Add to your Gemfile - gem 'secure-headers' +```ruby +gem 'secure-headers' +``` And then execute: - $ bundle +```console +$ bundle +``` Or install it yourself as: - $ gem install secure-headers +```console +$ gem install secure-headers +``` ## Usage @@ -43,29 +49,33 @@ This gem makes a few assumptions about how you will use some features. For exam **Place the following in an initializer:** - ::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", - # ALWAYS supply a full URL for report URIs - :report_uri => 'https://example.com/uri-directive', - :img_src => "https://* data:", - :frame_src => "https://* http://*.twimg.com http://itunes.apple.com" - } - end +```ruby +::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", + # ALWAYS supply a full URL for report URIs + :report_uri => 'https://example.com/uri-directive', + :img_src => "https://* data:", + :frame_src => "https://* http://*.twimg.com http://itunes.apple.com" + } +end - # and then simply include - ensure_security_headers +# and then simply include +ensure_security_headers +``` Or simply add it to application controller - ensure_security_headers - :hsts => {:include_subdomains, :x_frame_options => false}, - :x_frame_options => 'DENY', - :csp => false +```ruby +ensure_security_headers + :hsts => {:include_subdomains, :x_frame_options => false}, + :x_frame_options => 'DENY', + :csp => false +``` ## Options for ensure\_security\_headers @@ -77,8 +87,10 @@ header will be constructed using the supplied options. ### Widely supported - :hsts => {:max_age => 631138519, :include_subdomain => true} # HTTP Strict Transport Security. - :x_frame_options => {:value => 'SAMEORIGIN'} +```ruby +:hsts => {:max_age => 631138519, :include_subdomain => true} # HTTP Strict Transport Security. +:x_frame_options => {:value => 'SAMEORIGIN'} +``` ### Content Security Policy (CSP) @@ -86,81 +98,87 @@ All browsers will receive the webkit csp header except Firefox, which gets its o See [WebKit/W3C specification](http://www.w3.org/TR/CSP/) and [Firefox CSP specification](https://wiki.mozilla.org/Security/CSP/Specification) - :csp => { - :enforce => false, # sets header to report-only, by default - # default_src is required! - :default_src => nil, # sets the default-src/allow+options directives +```ruby +:csp => { + :enforce => false, # sets header to report-only, by default + # default_src is required! + :default_src => nil, # sets the default-src/allow+options directives - # Where reports are sent. Use full URLs. - :report_uri => 'https://mylogaggregator.example.com', + # Where reports are sent. Use full URLs. + :report_uri => 'https://mylogaggregator.example.com', - # Send reports that cannot be sent across host here (see below), forward them to report_uri - # override this if you have a route with the same value (content_security_policy#scribe) - :forward_endpoint => TwitterRailsSecurity::Headers::ContentSecurityPolicy::FF_CSP_ENDPOINT + # Send reports that cannot be sent across host here (see below), forward them to report_uri + # override this if you have a route with the same value (content_security_policy#scribe) + :forward_endpoint => TwitterRailsSecurity::Headers::ContentSecurityPolicy::FF_CSP_ENDPOINT - # these directives all take 'none', 'self', or a globbed pattern - :img_src => nil, - :frame_src => nil, - :connect_src => nil, - :font_src => nil, - :media_src => nil, - :object_src => nil, - :style_src => nil, - :script_src => nil, + # these directives all take 'none', 'self', or a globbed pattern + :img_src => nil, + :frame_src => nil, + :connect_src => nil, + :font_src => nil, + :media_src => nil, + :object_src => nil, + :style_src => nil, + :script_src => nil, - # http additions will be appended to the various directives when - # over http, relaxing the policy - # e.g. - # :csp => { - # :img_src => 'https://*', - # :http_additions => {:img_src => 'http//*'} - # } - # would produce the directive: "img-src https://* http://*;" - # when over http, ignored for https requests - :http_additions => {} - } + # http additions will be appended to the various directives when + # over http, relaxing the policy + # e.g. + # :csp => { + # :img_src => 'https://*', + # :http_additions => {:img_src => 'http//*'} + # } + # would produce the directive: "img-src https://* http://*;" + # when over http, ignored for https requests + :http_additions => {} +} +``` ### Only applied to IE - :x_content_type_options => {:value => 'nosniff'} - :x_xss_protection => {:value => '1', :mode => false} # set the :mode option to block +```ruby +:x_content_type_options => {:value => 'nosniff'} +:x_xss_protection => {:value => '1', :mode => false} # set the :mode option to block +``` ### Example CSP header config **Configure the CSP header as if it were the w3c-style header, no need to supply 'options' or 'allow' directives.** - # most basic example - :csp => { - :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;" +```ruby +# most basic example +:csp => { + :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;" - # turn off inline scripting/eval - :csp => { - :default_src => 'https://*', - :report_uri => '/uri-directive' - } - # Chrome - > "default-src https://*; report-uri /uri-directive;" - # Firefox - > "allow https://*; report-uri /uri-directive;" +# turn off inline scripting/eval +:csp => { + :default_src => 'https://*', + :report_uri => '/uri-directive' +} +# Chrome +> "default-src https://*; report-uri /uri-directive;" +# Firefox +> "allow 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 => { - :default_src => 'self', - :img_src => '*', - :object_src => ['media1.com', 'media2.com', '*.cdn.com'], - # 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;" +# 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 => { + :default_src => 'self', + :img_src => '*', + :object_src => ['media1.com', 'media2.com', '*.cdn.com'], + # 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 @@ -181,13 +199,17 @@ If you need to change the route for the internal forwarding point, be sure it ma #### Rails 2 - map.csp_endpoint +```ruby +map.csp_endpoint +``` #### Rails 3 If the csp reporting endpoint is clobbered by another route, add: - match SecureHeaders::ContentSecurityPolicy::FF_CSP_ENDPOINT => "content_security_policy#scribe" +```ruby +match SecureHeaders::ContentSecurityPolicy::FF_CSP_ENDPOINT => "content_security_policy#scribe" +``` ## Authors From d32869995e93052711cbe544f84b7c75f7027fc9 Mon Sep 17 00:00:00 2001 From: Neil Matatall Date: Thu, 24 Jan 2013 21:57:38 -0800 Subject: [PATCH 2/2] escape - --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index de36b2a..45ef541 100644 --- a/README.md +++ b/README.md @@ -40,9 +40,9 @@ By default, it will set all of the headers listed in the options section below u 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. -* 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 (the forward_endpoint value or 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 :report_uri 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. +* It copies the connect\-src value to xhr\-src for AJAX requests. +* 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 (the forward_endpoint value or 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 :report_uri without restriction. More information can be found in the "Note on Firefox handling of CSP" section. ## Configuration @@ -184,18 +184,18 @@ and [Firefox CSP specification](https://wiki.mozilla.org/Security/CSP/Specificat Currently, Firefox does not support the w3c draft standard. So there are a few steps taken to make the two interchangeable. -Firefox > 18 partially supports the standard via using the default-src directive over allow/options, but the following inconsistencies remain. +Firefox > 18 partially supports the standard via using the default\-src directive over allow/options, but the following inconsistencies remain. -* 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. +* 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. * Firefox adds port numbers to each /https?/ value which can make local development tricky with mocked services. Add environment specific code to configure this. ### Adding the Firefox report forwarding endpoint **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!!!** +**This is an unauthenticated, unauthorized endpoint. Only do this if your report\-uri is not on the same origin as your application!!!** -If you need to change the route for the internal forwarding point, be sure it matches what is set in :forward_endpoint or else the reports will post to a non-existent endpoint. +If you need to change the route for the internal forwarding point, be sure it matches what is set in :forward_endpoint or else the reports will post to a non\-existent endpoint. #### Rails 2