Module: Roda::RodaPlugins::ContentSecurityPolicy

Defined in:

lib/roda/plugins/content_security_policy.rb

Overview

The content_security_policy plugin allows you to easily set a Content-Security-Policy header for the application, which modern browsers will use to control access to specific types of page content.

You would generally call the plugin with a block to set the default policy:

plugin :content_security_policy do |csp|
csp.default_src :none
csp.img_src :self
csp.style_src :self
csp.script_src :self
csp.font_src :self
csp.form_action :self
csp.base_uri :none
csp.frame_ancestors :none
csp.block_all_mixed_content
end

Then, anywhere in the routing tree, you can customize the policy for just that branch or action using the same block syntax:

r.get 'foo' do
content_security_policy do |csp|
  csp.object_src :self
  csp.add_style_src 'bar.com'
end
# ...
end

In addition to using a block, you can also call methods on the object returned by the method:

r.get 'foo' do
content_security_policy.script_src :self, 'example.com', [:nonce, 'foobarbaz']
# ...
end

The following methods are available for configuring the content security policy, which specify the setting (substituting _ with -):

• base_uri
• child_src
• connect_src
• default_src
• font_src
• form_action
• frame_ancestors
• frame_src
• img_src
• manifest_src
• media_src
• object_src
• plugin_types
• report_to
• report_uri
• require_sri_for
• sandbox
• script_src
• style_src
• worker_src

All of these methods support any number of arguments, and each argument should be one of the following types:

String

used verbatim

Symbol

Substitutes _ with - and surrounds with '

Array

only accepts 2 element arrays, joins elements with - and surrounds the result with '

Example:

content_security_policy.script_src :self, :unsafe_eval, 'example.com', [:nonce, 'foobarbaz']
# script-src 'self' 'unsafe-eval' example.com 'nonce-foobarbaz'; 

When calling a method with no arguments, the setting is removed from the policy instead of being left empty, since all of these setting require at least one value. Likewise, if the policy does not have any settings, the header will not be added.

Calling the method overrides any previous setting. Each of the methods has add_* and get_* methods defined. The add_* method appends to any existing setting, and the get_* method returns the current value for the setting.

content_security_policy.script_src :self, :unsafe_eval
content_security_policy.add_script_src 'example.com', [:nonce, 'foobarbaz']
# script-src 'self' 'unsafe-eval' example.com 'nonce-foobarbaz'; 

content_security_policy.get_script_src
# => [:self, :unsafe_eval, 'example.com', [:nonce, 'foobarbaz']]

The clear method can be used to remove all settings from the policy. Empty policies do not set any headers. You can use response.skip_content_security_policy! to skip setting a policy. This is faster than calling content_security_policy.clear, since it does not duplicate the default policy.

The following methods to set boolean settings are also defined:

• block_all_mixed_content
• upgrade_insecure_requests

Calling these methods will turn on the related setting. To turn the setting off again, you can call them with a false argument. There is also a *? method for each setting for returning whether the setting is currently enabled.

Likewise there is also a report_only method for turning on report only mode (the default is enforcement mode), or turning off report only mode if a false argument is given. Also, there is a report_only? method for returning whether report only mode is enabled.

Defined Under Namespace

Modules: InstanceMethods, ResponseMethods Classes: Policy

Constant Summary

RESPONSE_INSTANCE_VARIABLES =

[:@content_security_policy, :@skip_content_security_policy].freeze

Class Method Summary

• .configure(app) {|policy| ... } ⇒ Object

  Yield the current Content Security Policy to the block.

Class Method Details

.configure(app) {|policy| ... } ⇒ Object

Yield the current Content Security Policy to the block.

Yields:

• (policy)

# File 'lib/roda/plugins/content_security_policy.rb', line 281

def self.configure(app)
  policy = app.opts[:content_security_policy] = if policy = app.opts[:content_security_policy]
    policy.dup
  else
    Policy.new
  end

  yield policy if defined?(yield)
  policy.freeze
end