Mitigate cross-site scripting (XSS) with a strict Content Security Policy (CSP)

This content originally appeared on web.dev and was authored by Lukas Weichselbaum

Why should you deploy a strict Content Security Policy (CSP)?

Cross-site scripting (XSS)—the ability to inject malicious scripts into a web application—has been one of the biggest web security vulnerabilities for over a decade.

Content Security Policy (CSP) is an added layer of security that helps to mitigate XSS. Configuring a CSP involves adding the Content-Security-Policy HTTP header to a web page and setting values to control what resources the user agent is allowed to load for that page. This article explains how to use a CSP based on nonces or hashes to mitigate XSS instead of the commonly used host-allowlist-based CSPs which often leave the page exposed to XSS as they can be bypassed in most configurations.

Key Term:
A nonce is a random number used only once that can be used to mark a <script> tag as trusted.

Key Term:
A hash function is a mathematical function that converts an input value into a compressed numerical value—a hash. A hash (such as SHA-256) can be used to mark an inline <script> tag as trusted.

A Content Security Policy based on nonces or hashes is often called a strict CSP. When an application uses a strict CSP, attackers who find HTML injection flaws will generally not be able to use them to force the browser to execute malicious scripts in the context of the vulnerable document. This is because strict CSP only permits hashed scripts or scripts with the correct nonce value generated on the server, so attackers cannot execute the script without knowing the correct nonce for a given response.

To protect your site from XSS, make sure to sanitize user input and use CSP as an extra security layer. CSP is a defense-in-depth technique that can prevent the execution of malicious scripts, but it's not a substitute for avoiding (and promptly fixing) XSS bugs.

Why a strict CSP is recommended over allowlist CSPs

If your site already has a CSP that looks like this: script-src www.googleapis.com, it may not be effective against cross-site scripting! This type of CSP is called an allowlist CSP and it has a couple of downsides:

It requires a lot of customization.
It can be bypassed in most configurations.

This makes allowlist CSPs generally ineffective at preventing attackers from exploiting XSS. That's why it's recommended to use a strict CSP based on cryptographic nonces or hashes, which avoids the pitfalls outlined above.

Allowlist CSP

Doesn't effectively protect your site. ❌
Must be highly customized. ?

Strict CSP

Effectively protects your site. ✅
Always has the same structure. ?

What is a strict Content Security Policy?

A strict Content Security Policy has the following structure and is enabled by setting one of the following HTTP response headers:

Nonce-based strict CSP

Content-Security-Policy:
  script-src 'nonce-{RANDOM}' 'strict-dynamic';
  object-src 'none';
  base-uri 'none';

Hash-based strict CSP

Content-Security-Policy:
  script-src 'sha256-{HASHED_INLINE_SCRIPT}' 'strict-dynamic';
  object-src 'none';
  base-uri 'none';

This is the most stripped-down version of a strict CSP. You'll need to tweak it to make it effective across browsers. See add a fallback to support Safari and older browsers for details.

The following properties make a CSP like the one above "strict" and hence secure:

Uses nonces 'nonce-{RANDOM}' or hashes 'sha256-{HASHED_INLINE_SCRIPT}' to indicate which <script> tags are trusted by the site's developer and should be allowed to execute in the user's browser.
Sets 'strict-dynamic' to reduce the effort of deploying a nonce- or hash-based CSP by automatically allowing the execution of scripts that are created by an already trusted script. This also unblocks the use of most third party JavaScript libraries and widgets.
Not based on URL allowlists and therefore doesn't suffer from common CSP bypasses.
Blocks untrusted inline scripts like inline event handlers or javascript: URIs.
Restricts object-src to disable dangerous plugins such as Flash.
Restricts base-uri to block the injection of <base> tags. This prevents attackers from changing the locations of scripts loaded from relative URLs.

Another advantage of a strict CSP is that the CSP always has the same structure and doesn't need to be customized for your application.

Adopting a strict CSP

To adopt a strict CSP, you need to:

Decide if your application should set a nonce- or hash-based CSP.
Copy the CSP from the What is a strict Content Security Policy section and set it as a response header across your application.
Refactor HTML templates and client-side code to remove patterns that are incompatible with CSP.
Add fallbacks to support Safari and older browsers.
Deploy your CSP.

You can use Lighthouse (v7.3.0 and above) Best Practices audit throughout this process to check whether your site has a CSP, and whether it's strict enough to be effective against XSS.

Step 1: Decide if you need a nonce- or hash-based CSP

There are two types of strict CSPs, nonce- and hash-based. Here's how they work:

Nonce-based CSP: You generate a random number at runtime, include it in your CSP, and associate it with every script tag in your page. An attacker can't include and run a malicious script in your page, because they would need to guess the correct random number for that script. This only works if the number is not guessable and newly generated at runtime for every response.
Hash-based CSP: The hash of every inline script tag is added to the CSP. Note that each script has a different hash. An attacker can't include and run a malicious script in your page, because the hash of that script would need to be present in your CSP.

Criteria for choosing a strict CSP approach:

Criteria for choosing a strict CSP approach
Nonce-based CSP	For HTML pages rendered on the server where you can create a new random token (nonce) for every response.
Hash-based CSP	For HTML pages served statically or those that need to be cached. For example, single-page web applications built with frameworks such as Angular, React or others, that are statically served without server-side rendering.

Step 2: Set a strict CSP and prepare your scripts

When setting a CSP, you have a few options:

Report-only mode (Content-Security-Policy-Report-Only) or enforcement mode (Content-Security-Policy). In report-only, the CSP won't block resources yet—nothing will break—but you'll be able to see errors and receive reports for what would have been blocked. Locally, when you're in the process of setting a CSP, this doesn't really matter, because both modes will show you the errors in the browser console. If anything, enforcement mode will make it even easier for you to see blocked resources and tweak your CSP, since your page will look broken. Report-only mode becomes most useful later in the process (see Step 5).
Header or HTML <meta> tag. For local development, a <meta> tag may be more convenient for tweaking your CSP and quickly seeing how it affects your site. However:
- Later on, when deploying your CSP in production, it is recommended to set it as an HTTP header.
- If you want to set your CSP in report-only mode, you'll need to set it as a header—CSP meta tags don't support report-only mode.

Set the following Content-Security-Policy HTTP response header in your application:

Content-Security-Policy:
  script-src 'nonce-{RANDOM}' 'strict-dynamic';
  object-src 'none';
  base-uri 'none';

Caution:

Replace the {RANDOM} placeholder with a random nonce that is regenerated on every server response.

Generate a nonce for CSP

A nonce is a random number used only once per page load. A nonce-based CSP can only mitigate XSS if the nonce value is not guessable by an attacker. A nonce for CSP needs to be:

A cryptographically strong random value (ideally 128+ bits in length)
Newly generated for every response
Base64 encoded

Here are some examples on how to add a CSP nonce in server-side frameworks:

Django (python)
Express (JavaScript):

const app = express();
app.get('/', function(request, response) {
    // Generate a new random nonce value for every response.
    const nonce = crypto.randomBytes(16).toString("base64");
    // Set the strict nonce-based CSP response header
    const csp = `script-src 'nonce-${nonce}' 'strict-dynamic' https:; object-src 'none'; base-uri 'none';`;
    response.set("Content-Security-Policy", csp);
    // Every <script> tag in your application should set the `nonce` attribute to this value.
    response.render(template, { nonce: nonce });  
  });
}

Add a `nonce` attribute to `<script>` elements

With a nonce-based CSP, every <script> element must have a nonce attribute which matches the random nonce value specified in the CSP header (all scripts can have the same nonce). The first step is to add these attributes to all scripts:

Blocked by CSP

<script src="/path/to/script.js"></script>
<script>foo()</script>

CSP will block these scripts, because they don't have `nonce` attributes.

Allowed by CSP

<script nonce="${NONCE}" src="/path/to/script.js"></script>
<script nonce="${NONCE}">foo()</script>

CSP will allow the execution of these scripts if `${NONCE}` is replaced with a value matching the nonce in the CSP response header. Note that some browsers will hide the `nonce` attribute when inspecting the page source.

Gotchas!

With 'strict-dynamic' in your CSP, you'll only have to add nonces to <script> tags that are present in the initial HTML response.'strict-dynamic' allows the execution of scripts dynamically added to the page, as long as they were loaded by a safe, already-trusted script (see the specification).

Set the following Content-Security-Policy HTTP response header in your application:

Content-Security-Policy:
  script-src 'sha256-{HASHED_INLINE_SCRIPT}' 'strict-dynamic';
  object-src 'none';
  base-uri 'none';

For several inline scripts, the syntax is as follows: 'sha256-{HASHED_INLINE_SCRIPT_1}' 'sha256-{HASHED_INLINE_SCRIPT_2}'.

Caution:
The {HASHED_INLINE_SCRIPT} placeholder must be replaced with a base64-encoded SHA-256 hash of an inline script that can be used to load other scripts (see next section). You can calculate SHA hashes of static inline <script> blocks with this tool. An alternative is to inspect the CSP violation warnings in Chrome's developer console, which contains hashes of blocked scripts, and add these hashes to the policy as 'sha256-…'.

A script injected by an attacker will be blocked by the browser as only the hashed inline script and any scripts dynamically added by it will be allowed to execute by the browser.

Load sourced scripts dynamically

All scripts that are externally sourced need to be loaded dynamically via an inline script, because CSP hashes are supported across browsers only for inline scripts (hashes for sourced scripts are not well-supported across browsers).

Blocked by CSP

<script src="https://example.org/foo.js"></script>
<script src="https://example.org/bar.js"></script>

CSP will block these scripts since only inline-scripts can be hashed.

Allowed by CSP

<script>
var scripts = [ 'https://example.org/foo.js', 'https://example.org/bar.js'];
scripts.forEach(function(scriptUrl) {
  var s = document.createElement('script');
  s.src = scriptUrl;
  s.async = false; // to preserve execution order
  document.head.appendChild(s);
});
</script>

To allow execution of this script, the hash of the inline script must be calculated and added to the CSP response header, replacing the `{HASHED_INLINE_SCRIPT}` placeholder. To reduce the amount of hashes, you can optionally merge all inline scripts into a single script. To see this in action checkout the [example](https://strict-csp-codelab.glitch.me/solution_hash_csp#) and examine the [code](https://glitch.com/edit/#!/strict-csp-codelab?path=demo%2Fsolution_hash_csp.html%3A1%3A).

Gotchas!

When calculating a CSP hash for inline scripts, whitespace characters between the opening and closing <script> tags matter. You can calculate CSP hashes for inline scripts using this tool.

About `async = false` and script loading `async = false`

isn't blocking in this case, but use this with care.

In the code snippet above, s.async = false is added to ensure that foo executes before bar (even if bar loads first). In this snippet, s.async = false does not block the parser while the scripts load; that's because the scripts are added dynamically. The parser will only stop as the scripts are being executed, just like it would behave for async scripts. However, with this snippet, keep in mind: - One/both scripts may execute before the document has finished downloading. If you want the document to be ready by the time the scripts execute, you need to wait for the DOMContentLoaded event before you append the scripts. If this causes a performance issue (because the scripts don't start downloading early enough), you can use preload tags earlier in the page. - defer = true won't do anything. If you need that behaviour, you'll have to manually run the script at the time you want to run it.

Step 3: Refactor HTML templates and client-side code to remove patterns incompatible with CSP

Inline event handlers (such as onclick="…", onerror="…") and JavaScript URIs (<a href="javascript:…">) can be used to run scripts. This means that an attacker who finds an XSS bug could inject this kind of HTML and execute malicious JavaScript. A nonce- or hash-based CSP disallows the use of such markup. If your site makes use of any of the patterns described above, you'll need to refactor them into safer alternatives.

If you enabled CSP in the previous step, you'll be able to see CSP violations in the console every time CSP blocks an incompatible pattern.

In most cases, the fix is straightforward:

To refactor inline event handlers, rewrite them to be added from a JavaScript block

Blocked by CSP

<span onclick="doThings();">A thing.</span>

CSP will block inline event handlers.

Allowed by CSP

<span id="things">A thing.</span>
<script nonce="${nonce}">
  document.getElementById('things')
          .addEventListener('click', doThings);
</script>

CSP will allow event handlers that are registered via JavaScript.

For `javascript:` URIs, you can use a similar pattern

Blocked by CSP

<a href="javascript:linkClicked()">foo</a>

CSP will block javascript: URIs.

Allowed by CSP

<a id="foo">foo</a>
<script nonce="${nonce}">
  document.getElementById('foo')
          .addEventListener('click', linkClicked);
</script>

CSP will allow event handlers that are registered via JavaScript.

Use of `eval()` in JavaScript

If your application uses eval() to convert JSON string serializations into JS objects, you should refactor such instances to JSON.parse(), which is also faster.

If you cannot remove all uses of eval(), you can still set a strict nonce-based CSP, but you will have to use the 'unsafe-eval' CSP keyword which will make your policy slightly less secure.

You can find these and more examples of such refactoring in this strict CSP Codelab:

Step 4: Add fallbacks to support Safari and older browsers

CSP is supported by all major browsers, but you'll need two fallbacks:

Using 'strict-dynamic' requires adding https: as a fallback for Safari, the only major browser without support for 'strict-dynamic'. By doing so:
- All browsers that support 'strict-dynamic' will ignore the https: fallback, so this won't reduce the strength of the policy.
- In Safari, externally sourced scripts will be allowed to load only if they come from an HTTPS origin. This is less secure than a strict CSP–it's a fallback–but would still prevent certain common XSS causes like injections of javascript: URIs because 'unsafe-inline' is not present or ignored in presence of a hash or nonce.
To ensure compatibility with very old browser versions (4+ years), you can add 'unsafe-inline' as a fallback. All recent browsers will ignore 'unsafe-inline' if a CSP nonce or hash is present.

Content-Security-Policy:
  script-src 'nonce-{random}' 'strict-dynamic' https: 'unsafe-inline';
  object-src 'none';
  base-uri 'none';

https: and unsafe-inline don't make your policy less safe because they will be ignored by browsers which support strict-dynamic.

Step 5: Deploy your CSP

After confirming that no legitimate scripts are being blocked by CSP in your local development environment, you can proceed with deploying your CSP to your (staging, then) production environment:

(Optional) Deploy your CSP in report-only mode using the Content-Security-Policy-Report-Only header. Learn more about the Reporting API. Report-only mode is handy to test a potentially breaking change like a new CSP in production, before actually enforcing CSP restrictions. In report-only mode, your CSP does not affect the behavior of your application (nothing will actually break). But the browser will still generate console errors and violation reports when patterns incompatible with CSP are encountered (so you can see what would have broken for your end-users).
Once you're confident that your CSP won't induce breakage for your end-users, deploy your CSP using the Content-Security-Policy response header. Only once you've completed this step, will CSP begin to protect your application from XSS. Setting your CSP via a HTTP header server-side is more secure than setting it as a <meta> tag; use a header if you can.

Gotchas!

Make sure that the CSP you're using is "strict" by checking it with the CSP Evaluator or Lighthouse. This is very important, as even small changes to a policy can significantly reduce its security.

Caution:
When enabling CSP for production traffic, you may see some noise in the CSP violation reports due to browser extensions and malware.

Limitations

Generally speaking, a strict CSP provides a strong added layer of security that helps to mitigate XSS. In most cases, CSP reduces the attack surface significantly (dangerous patterns like javascript: URIs are completely turned off). However, based on the type of CSP you're using (nonces, hashes, with or without 'strict-dynamic'), there are cases where CSP doesn't protect:

If you nonce a script, but there's an injection directly into the body or into the src parameter of that <script> element.
If there are injections into the locations of dynamically created scripts (document.createElement('script')), including into any library functions which create script DOM nodes based on the value of their arguments. This includes some common APIs such as jQuery's .html(), as well as .get() and .post() in jQuery < 3.0.
If there are template injections in old AngularJS applications. An attacker who can inject an AngularJS template can use it to execute arbitrary JavaScript.
If the policy contains 'unsafe-eval', injections into eval(), setTimeout() and a few other rarely used APIs.

Developers and security engineers should pay particular attention to such patterns during code reviews and security audits. You can find more details on the cases described above in this CSP presentation.

Trusted Types complements strict CSP very well and can efficiently protect against some of the limitations listed above. Learn more about how to use Trusted Types at web.dev.

Option A: Nonce-based CSP

Option B: Hash-based CSP Response Header

About `async = false` and script loading `async = false`

Why should you deploy a strict Content Security Policy (CSP)? #

Why a strict CSP is recommended over allowlist CSPs #

What is a strict Content Security Policy? #

Adopting a strict CSP #

Step 1: Decide if you need a nonce- or hash-based CSP #

Step 2: Set a strict CSP and prepare your scripts #

Option A: Nonce-based CSP

Generate a nonce for CSP #

Add a nonce attribute to <script> elements #

Option B: Hash-based CSP Response Header

Load sourced scripts dynamically #

About async = false and script loading async = false

Step 3: Refactor HTML templates and client-side code to remove patterns incompatible with CSP #

To refactor inline event handlers, rewrite them to be added from a JavaScript block #

For javascript: URIs, you can use a similar pattern #

Use of eval() in JavaScript #

Step 4: Add fallbacks to support Safari and older browsers #

Step 5: Deploy your CSP #

Limitations #

Further reading #

Related Posts

Why should you deploy a strict Content Security Policy (CSP)?

Why a strict CSP is recommended over allowlist CSPs

What is a strict Content Security Policy?

Adopting a strict CSP

Step 1: Decide if you need a nonce- or hash-based CSP

Step 2: Set a strict CSP and prepare your scripts

Generate a nonce for CSP

Add a `nonce` attribute to `<script>` elements

Load sourced scripts dynamically

About `async = false` and script loading `async = false`

Step 3: Refactor HTML templates and client-side code to remove patterns incompatible with CSP

To refactor inline event handlers, rewrite them to be added from a JavaScript block

For `javascript:` URIs, you can use a similar pattern

Use of `eval()` in JavaScript

Step 4: Add fallbacks to support Safari and older browsers

Step 5: Deploy your CSP

Limitations

Further reading