Content Security Policy Headers¶

Content Security Policy headers¶

In a high-level example of web security using Content Security Policy (CSP), let’s consider a scenario. When a user’s web browser sends a request to a server for a particular web page, the server responds by generating the page response and including a CSP header. This CSP header specifies trusted sources from which scripts, stylesheets, images, and other assets can be loaded and executed. Additionally, the server generates a unique nonce (number used once) and adds it to all inline scripts and other assets within the response.

Once the response is sent to the user’s browser, the browser acts as a security enforcer. It checks each requested resource and script against the CSP directive. If any resource or script does not match the trusted sources specified in the CSP header or lacks the correct nonce, the browser rejects those elements, preventing them from loading or executing. This strict validation process ensures that only content from trusted sources, as defined by the CSP, is allowed to run on the webpage. In doing so, CSP effectively protects against cross-site scripting (XSS) attacks and other security threats, making the user’s browsing experience safer and more secure.

AtoM’s CSP configuration¶

This is the default configuration you’ll find in AtoM’s config/app.yml file:

# Content Security Policy (CSP) header configuration. CSP settings apply
# only when a B5 theme is active, else these settings are bypassed.
csp:
    response_header: Content-Security-Policy-Report-Only
    directives: "default-src 'self'; font-src 'self' https://fonts.gstatic.com; img-src 'self' https://*.googleapis.com https://*.gstatic.com *.google.com *.googleusercontent.com data: https://www.gravatar.com/avatar/ https://*.google-analytics.com https://*.googletagmanager.com blob:; script-src 'self' https://*.googletagmanager.com 'nonce' https://*.googleapis.com https://*.gstatic.com *.google.com https://*.ggpht.com *.googleusercontent.com blob:; style-src 'self' 'nonce' https://fonts.googleapis.com; worker-src 'self' blob:; connect-src 'self' https://*.google-analytics.com https://*.analytics.google.com https://*.googletagmanager.com https://*.googleapis.com *.google.com https://*.gstatic.com data: blob:; frame-ancestors 'self';"

The CSP repsonse_header setting is used to set the CSP header type and can have one of two values:

• Content-Security-Policy: This setting will enforce the defined policy. When set, the browser will block any resources (scripts, images, stylesheets, etc.) that violate the policy directives.
• Content-Security-Policy-Report-Only: This header works similarly to the Content-Security-Policy but does not block any resources allowing developers to test and monitor potential violations without affecting the functionality of the web page. This is useful for testing a new policy or changes to an existing policy without risking breakage. Violations will be reported to the browser’s console. This setting is the default.

The CSP directives setting contains the CSP policy that will be sent in the CSP header. The value for the directives setting above is the default when the Dominion theme is in use. Multiple directives get delineated with a semicolon (;).

The specific directives defined in the defaults above are as follows:

• default-src: If resources aren’t mentioned in other sections, this policy is applied.
• font-src: Stipulates which fonts can be loaded.
• img-src: Stipulates which images can be loaded.
• script-src: Stipulates which scripts can be loaded.
• style-src: Stipulates which styles or CSS can be loaded.
• worker-src: Defines valid sources for web workers and nested browsing contexts loaded using elements such as <frame> and <iframe>.
• connect-src: Specifies the URLs that the application can connect to using script interfaces like XMLHttpRequest, fetch, WebSocket, and EventSource.
• frame-ancestors ‘self’: Determines which domains can embed the page as a frame. This directive restricts who can embed the page in frames, iframes, embeds, or objects.

Specifying self ensures that only trusted resources from the same origin are loaded and executed.

Updating these settings will require restarting PHP-FPM.

CSP headers can be deactivated by deleting the CSP section from the config/app.yml file, saving the file, and restarting PHP-FPM.

Implementing a Content Security Policy For Your Custom Theme¶

1. Begin with a basic CSP directive.

   If your custom theme is derived from AtoM’s Dominion Bootstrap 5 theme, begin with the baseline CSP directive from AtoM’s config/app.yml:

   Content-Security-Policy-Report-Only: default-src 'self'; font-src 'self'; img-src 'self' https://www.gravatar.com/avatar/ blob:; script-src 'self' 'nonce'; style-src 'self' 'nonce'; worker-src 'self' blob:; frame-ancestors 'self';
   

   In app.yml this would look like:

   # Content Security Policy (CSP) header configuration. CSP settings apply
   # only when a B5 theme is active, else these settings are bypassed.
   csp:
      response_header: Content-Security-Policy-Report-Only
      directives: "default-src 'self'; font-src 'self' https://fonts.gstatic.com; img-src 'self' https://*.googleapis.com https://*.gstatic.com *.google.com *.googleusercontent.com data: https://www.gravatar.com/avatar/ https://*.google-analytics.com https://*.googletagmanager.com blob:; script-src 'self' https://*.googletagmanager.com 'nonce' https://*.googleapis.com https://*.gstatic.com *.google.com https://*.ggpht.com *.googleusercontent.com blob:; style-src 'self' 'nonce' https://fonts.googleapis.com; worker-src 'self' blob:; connect-src 'self' https://*.google-analytics.com https://*.analytics.google.com https://*.googletagmanager.com https://*.googleapis.com *.google.com https://*.gstatic.com data: blob:; frame-ancestors 'self';"
   

   For those who have crafted a custom theme, but haven’t used AtoM’s default Bootstrap 5 Dominion theme as a foundation, it’s recommended to start with a more restrictive content-security-policy header:

   Content-Security-Policy-Report-Only: default-src 'self'; font-src 'self'; img-src 'self'; script-src 'self'; style-src 'self'; frame-ancestors 'self';
   

   In app.yml this would look like:

   # Content Security Policy (CSP) header configuration. CSP settings apply
   # only when a B5 theme is active, else these settings are bypassed.
   csp:
      response_header: Content-Security-Policy-Report-Only
      directives: "default-src 'self'; font-src 'self'; img-src 'self'; script-src 'self'; style-src 'self'; frame-ancestors 'self';"
   

   These examples reference the Content-Security-Policy-Report-Only header - this header will log violations in Chrome’s Developer Tools but will not prevent a script from loading and running. This is helpful when developing a policy so that the pages and all scripts still load properly - while ensuring all violations will be seen in the console log. When the policy definition is ready to go live this CSP header type can be changed to Content-Security-Policy to activate enforcement.

2. Monitor in the browser watching for CSP violations.

   In Chrome’s Developer Tools, click on the “Console” tab. This tab displays logs, errors, and warnings related to the webpage you are inspecting.

   In the Console, look for messages that begin with Content Security Policy. These messages indicate CSP violations. CSP violation messages typically include information about what part of the policy was violated and what resource was blocked.

3. Look for and fix any violations by adding nonce to inline script, style, etc.

   Alongside each CSP violation message in the Console, Chrome provides the source file’s name and the line number where the violation occurred. This information is useful for pinpointing the exact part of your code responsible for the violation.

   Use “view source” to find the implicated line and find the violation in the underlying code. Most of these are going to be inline assets - scripts, styles, etc. See: Safely Allowing Inline Sources.

4. Activate policy enforcement.

   Once you are convinced you’ve caught all the violations, activate enforcement of the CSP policy by changing the header from Content-Security-Policy-Report-Only to Content-Security-Policy.

Safely Allowing Inline Sources¶

If your application has inline scripts there are 4 choices:

1. Usage of unsafe-inline should be avoided.

   Allowing unsafe-inline in a CSP directive permits inline scripts or styles from any source to run. While it offers design flexibility, it’s discouraged due to heightened risk of XSS attacks. This setting can expose web applications to malicious script injections, undermining CSP’s security benefits and so using unsafe-inline should be avoided.

2. Add the hash of the script to the CSP directive.

   Adding a script’s hash to the CSP directive allows for specific inline scripts to execute based on their hashed content. While this method ensures only the approved script runs, it’s fragile because any change to the script’s content requires recalculating and updating its hash in the CSP. This can be cumbersome and error-prone, especially with frequent script modifications.

   In addition, if there are a large number of violations, there could mean a lot of hashes to add, creating a very messy CSP directive.

3. For a given request generate a random nonce value to be returned in the CSP header directive and on each inline script, style etc tag.

   Each inline script or style has to be flagged as ‘ok’ with a nonce (a random token) value that is uniquely generated for a specific request/response pair. This nonce must be included in the Header directive, and in each inline script (or style, font, img source) tag. If your application has lots of inline scripts, styles and whatnot this could be a lot of work, but it will be more robust than using script hashes.

   Content-Security_policy-Report-Only: default-src 'self'; font-src 'self'; img-src 'self' https://www.gravatar.com/avatar/ blob:; script-src 'self' 'nonce-abcd1234567890'; style-src 'self' 'nonce-abcd1234567890'; worker-src 'self' blob:; frame-ancestors 'self';
   

4. Remove the inline asset! Refactor the code to move the inline asset to the script and style bundle. If it’s an inline style can it be replaced with a Bootstrap 5 equivalent?

Work completed to make the Dominion theme compatible with CSP headers can be viewed in this AtoM CSP commit. This commit provides examples of how to refer to the nonce value generated by AtoM from your theme templates, and examples of refactoring code to remove inline styles in favour of Bootstrap 5 equivalents.

Allowing External Sources¶

If for example the application makes use of Gravatar assets, we could allow them by adding:

Content-Security-Policy-Report-Only: default-src 'self'; font-src 'self'; img-src 'self' https://www.gravatar.com/avatar/; script-src 'self'; style-src 'self'; frame-ancestors 'self';

Note it is good to be as specific as possible without creating a maintenance headache when specifying the domain. E.g. if all assets are loaded from the avatar endpoint, then it is better to be more specific than allow scripts to be run from the entire https://www.gravatar.com domain.

If your theme makes use of other services beyond Google Analytics, or the Maps API, then you may need to whitelist additional sources. We recommend consulting the vendor’s documentation for this. For example, Matomo Analytics provides the following configuration tips:

• https://matomo.org/faq/general/faq_20904/