TheContent-Security-Policy HTTP header provides fine-grained control over the code that can be loaded on a site, and what it is allowed to do.

Problem

The main problem this article focuses on is cross-site scripting (XSS) attacks. These are generally due to a lack of control and awareness of the sources from which site resources are loaded. This problem gets more difficult to manage as sites become larger and more complex and increasingly rely on third-party resources such as JavaScript libraries.

CSP can also help to fix other problems, which are covered in other articles:

• Preventingclickjacking by stopping your site being embedded into<iframe> elements. This is done using the CSPframe-ancestors directive.
• Preventingmanipulator-in-the-middle (MiTM) attacks by upgrading any HTTP connections to HTTPS. This is helped by the CSPupgrade-insecure-requests directive. SeeUpgrading insecure requests.

Solution

Implementing astrict CSP is the best way to mitigate XSS vulnerabilities with CSP. This usesnonce- orhash-based fetch directives to ensure that only scripts and/or styles that include the correctnonce or hash will be executed. JavaScript inserted by a hacker will simply not run.

Strict CSPs also:

• Disable the use of unsafeinline JavaScript, meaning inlineevent handler attributes such asonclick. This prevents improperly-escaped user inputs from being interpreted by the web browser as JavaScript.
• Disable the use ofrisky API calls such aseval(), which is another effect of thescript-src directive.
• Disable all object embeds viaobject-src 'none'.
• Disable uses of the<base> element to set a base URI viabase-uri 'none';.

Strict CSPs are preferred overlocation-based policies, also called allowlist policies, where you specify which domains scripts can be run from. This is because allowlist policies often end up allowing unsafe domains, which defeats the entire point of having a CSP, and they can get very large and unwieldy, especially if you are trying to permit services that require many third party scripts to function.

Steps for implementing CSP

Implement a strict CSP, then start to pinpoint resources that are failing to load as a result of the policy, taking steps to work around these issues.

1. Decide whether to use nonces or hashes. You should use nonces if you can dynamically generate content or hashes if you need to serve static content.
2. Implement a strict CSP, as outlined in theSolution section. Make sure that external and internal scripts (included via<script> elements) that you want to run have the correct nonce inserted into thenonce attributes by the server. If you are instead using hashes, external scripts should have the correct hash inserted intointegrity attributes.
3. If an allowed script goes on to load third-party scripts, those scripts will fail to load because they won't have the required nonce or hash. Mitigate this problem by adding thestrict-dynamic directive, which gives scripts loaded by the first script the same level of trust without being explicitly given a nonce or hash.
4. Refactor patterns disallowed by the strict CSP, such as inline event handlers andeval(). For example, replace inline event handlers withaddEventListener() calls inside scripts.
5. Unless sites need the ability to include embeds, their execution should be disabled withobject-src 'none'.
6. If you are unable to remove usages ofeval(), you can add theunsafe-eval keyword to your strict CSP to allow them, although this makes the CSP significantly weaker.
7. If you are unable to remove event handler attributes, you can add theunsafe-hashes keyword to your strict CSP to allow them. This is somewhat unsafe, but much safer than allowing all inline JavaScript.

If you are unable to get a strict CSP to work, an allowlist-based CSP is much better than none, and a CSP likedefault-src https: still provides some protection, disabling unsafe inline/eval() and only allowing loading of resources (images, fonts, scripts, etc.) over HTTPS.

If you are unable to use theContent-Security-Policy header, pages can instead include a<meta http-equiv="Content-Security-Policy" content="…"> element. This should be the first<meta> element that appears inside the document<head>.

Report-only CSPs

Before implementing any actual CSP with theContent-Security-Policy header, you are advised to first test it out using theContent-Security-Policy-Report-Only HTTP header. This allows you to see if any violations would have occurred with that policy.

Sites should use thereport-to andreport-urireporting directives. These cause the browser toPOST JSON reports about CSP violations to endpoints (specified in theReporting-Endpoints header in the case ofreport-to). This allows CSP violations to be caught and repaired quickly.

See also

• Content Security Policy (CSP)
• Cross-site scripting (XSS)
• CSP evaluator