Content Security Policy (CSP) implementation

The Content-Security-Policy HTTP header provides fine-grained control over the locations from which resources on a site can be loaded.

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:

• Preventing clickjacking by stopping your site being embedded into elements. This is done using the CSP frame-ancestors directive.
• Preventing manipulator-in-the-middle (MiTM) attacks by upgrading any HTTP connections to HTTPS. This is helped by the CSP upgrade-insecure-requests directive. See HSTS implementation for more details.

Solution

Implementing a robust CSP is the best way to prevent XSS vulnerabilities.

The primary benefit of CSP comes from disabling the use of unsafe inline JavaScript. Inline JavaScript, whether reflected or stored, enables improperly-escaped user inputs to generate code that is interpreted by the web browser as JavaScript. By using CSP to disable inline JavaScript, you can eliminate almost all XSS attacks against your site.

Disabling inline JavaScript means that all JavaScript must be loaded from external files via elements with src attributes. Inline event handler attributes, such as onclick , and JavaScript inserted directly inside tags will fail to work. Furthermore, CSP can also disable internal stylesheets (inside tags) and inline styles (using the style attribute).

Therefore, design websites carefully to ensure that CSP causes less problems and becomes easier to implement.

CSP can also be used to provide granular control over:

• Loading other resources such as images, video, and audio (fetch directives control resource loading).
• Web workers (via document directives).
• Embedded (i.e., ) content.
• Navigation / form submission destinations (via navigation directives).

Steps for implementing CSP

Note: Before implementing any actual CSP with the Content-Security-Policy header, you are advised to first test it out using the Content-Security-Policy-Report-Only HTTP header. This allows you to see if any violations would have occurred with that policy. This test requires the use of report-to (or the deprecated report-uri ), as explained below.

1. Begin by trying out a policy of default-src https: . This is a great first goal because it disables inline code and requires browsers to use HTTPS when loading resources. It will also allow you to start to pinpoint the resources that are failing to load as a result of the policy. default-src serves as a fallback for the other CSP fetch directives.
2. Next, start to make the policy more specific, to allow the items you need, while blocking any unwanted items. You could first widen the policy remit with a reasonably locked-down policy such as default-src 'none'; form-action 'self'; img-src 'self'; object-src 'none'; script-src 'self'; style-src 'self'; .
3. You can then go on to add specific sources as highlighted during testing; for example, style-src 'self' https://example.com/ .
4. API endpoints should use a policy that disables resource loading and embedding; for example, Content-Security-Policy: default-src 'none'; frame-ancestors 'none' .
5. For existing websites with large codebases that would require too much work to disable inline scripts, you can use some of the CSP features designed to ease adoption on legacy sites. For example, the nonce-* directive requires that a specifies the same nonce in its nonce attribute for loading to succeed, whereas the script-dynamic directive extends the trust due to an accompanying nonce to other scripts that the top-level script loads.

Keep the following points in mind:

Note: > report-to is preferred over the deprecated report-uri ; however, both are still needed because report-to does not yet have full cross-browser support.

svg> use href="/images/icons.svg#icon"/> svg> 

Examples

Disable unsafe inline/eval and only allow loading of resources (images, fonts, scripts, etc.) over HTTPS:

Content-Security-Policy: default-src https: 

Do the same thing, but with a element:

meta http-equiv="Content-Security-Policy" content="default-src https:" /> 

Disable the use of unsafe inline/eval and allow everything else except plugin execution:

Content-Security-Policy: default-src *; object-src 'none' 

Disable unsafe inline/eval and only load resources from same-origin with the exception of images, which can be loaded from https://i.imgur.com . This also disables the execution of plugins:

Content-Security-Policy: default-src 'self'; img-src 'self' https://i.imgur.com; object-src 'none' 

Disable unsafe inline/eval scripts and plugins, load only scripts and stylesheets from same-origin, allow fonts to be loaded from https://fonts.gstatic.com , and allow image loading from same-origin and https://i.imgur.com . Sites should aim for policies like this:

Content-Security-Policy: default-src 'none'; font-src https://fonts.gstatic.com; img-src 'self' https://i.imgur.com; object-src 'none'; script-src 'self'; style-src 'self' 

Allow legacy sites to load scripts safely, with an increase level of trust provided by a nonce:

script nonce="2726c7f26c"> const inline = 1; // … script> 

Content-Security-Policy: script-src 'strict-dynamic' 'nonce-2726c7f26c' 

Don't implement the policy yet; only report the violations that would have occurred:

Reporting-Endpoints: csp-endpoint="https://example.com/csp-reports" Content-Security-Policy-Report-Only: default-src https:; report-uri /csp-violation-report-endpoint/; report-to csp-endpoint; 

Disable resource loading and embedding. APIs should use a policy like this:

Content-Security-Policy: default-src 'none'; frame-ancestors 'none' 

See also

• Content Security Policy (CSP)
• CSP evaluator