Content Security Policy - Report URI Documentation (2024)

What is CSP?

Content Security Policy is a powerful security feature that allows you to take control of the resources your website is permitted to load and the actions it is allowed to take.

A Content Security Policy is delivered to the browser in a HTTP response header along with your page and the browser will then parse and enforce that policy. It can be used to mitigate serious security concerns like content-injection attacks, most notable Cross-Site Scripting (XSS), fix mixed-content and countless other benefits.

It's easy to get started with Content Security Policy and you can deploy it to your site in "report-only" mode which makes it completely safe to test.

Getting Started

If you want to get started with CSP you can deploy a policy to use the CSP Wizard with no risk and no chance of breaking anything on your site. The suggested policy for getting started with the CSP Wizard is:

Content-Security-Policy-Report-Only: default-src 'none'; form-action 'none'; frame-ancestors 'none'; report-uri https://{subdomain}.report-uri.com/r/d/csp/wizard

To deploy this header on your website you will need to update the subdomain in the example to your own subdomain, which you can find on the Setup page, and then set the header on your website. Here are some examples on how to do that depending on your platform or language of choice:

PHP

header("Content-Security-Policy-Report-Only: default-src 'none'; form-action 'none'; frame-ancestors 'none'; report-uri https://{subdomain}.report-uri.com/r/d/csp/wizard");

Nginx

add_header Content-Security-Policy-Report-Only "default-src 'none'; form-action 'none'; frame-ancestors 'none'; report-uri https://{subdomain}.report-uri.com/r/d/csp/wizard";

Apache

Header set Content-Security-Policy-Report-Only "default-src 'none'; form-action 'none'; frame-ancestors 'none'; report-uri https://{subdomain}.report-uri.com/r/d/csp/wizard"

IIS

Open IIS Manager and navigate to the level you want to manage, In Features View, double-click HTTP Response Headers. On the HTTP Response Headers page, in the Actions pane, click Add. In the Add Custom HTTP Response Header dialog box use the following name and value and then click OK.

Name: Content-Security-Policy-Report-Only

Value: default-src 'none'; form-action 'none'; frame-ancestors 'none'; report-uri https://{subdomain}.report-uri.com/r/d/csp/wizard

Tuning Your Policy

The policy above is great to get started but will generate a lot of reports so you need to fine tune your policy based on these reports. Take the following report as an example:

This report informs us that on our homepage, https://example.com/, we have a script that is being loaded from https://cdnjs.com. If you do have a script on your homepage that you want to load from this domain then you need to update your policy to allow that. The domain needs adding to the script-src directive to do that.

script-src 'self' cdnjs.com

This update to the script-src directive now includes the self keyword as we had before but it now also includes the cdnjs.com domain which lets the browser know it is allowed to load scripts from that domain. Once you update your policy you will no longer receive reports about that script as it will be allowed.

If the report highlights a problem and you do not want to allow the resource to load, do not add the value to your policy. Instead you must find the asset on the page and remove it or load it from a whitelisted location instead.

With each update you make to your policy you will receive less and less reports as you whitelist the appropriate items or remove/change resources that you don't want to be loaded. We recommend that you work through tuning your policy as quickly as possible to reduce the amount of reports you send and thus the cost incurred on your account. You can also enable/disable reporting during specific periods of monitoring to help and reduce your volume during the early stages of policy tuning.

Using `report-uri`

If you already have an existing Content Security Policy, or just want to enable reporting in either a CSP or CSPRO header without using the CSP Wizard, you can find your report-uri value on the Setup page. Below is an example of what that might look like.

report-uri https://{subdomain}.report-uri.com/r/d/csp/enforcereport-uri https://{subdomain}.report-uri.com/r/d/csp/reportOnly

This address is unique per-user and per-team, so make sure you use the correct value obtained from logging in to your account. When using report-uri it is important to use the correct path which indicates the disposition of the policy delivered to the browser by your website. You must use the /enforce path in a CSP header report-uri directive and the /reportOnly path in a CSPRO header report-uri directive.

Using `report-to`

If you'd like to use the newer report-to reporting directive in your CSP or CSPRO header, you will need to first setup the Reporting API by adding the necessary HTTP Response Header to your site. Once the Reporting API is enabled on your site, you can enable report-to in your CSP or CSPRO header.

report-to default

Using the Reporting API to send CSP reports is simpler and you do not need to indicate the disposition of the report (enforced or report only) as this is taken care of automatically. If you are concerned about older browsers that do not support the Reporting API, you can use both report-uri and report-to in your CSP or CSPRO header without any negative effect.

report-uri https://{subdomain}.report-uri.com/r/d/csp/enforce; report-to default

If the browser supports report-to then reports will be sent via the Reporting API, if not, it will use report-uri and send reports via the traditional mechanism.

Filtering Reports

You can configure filters for your inbound CSP reports in the Filters section in your account. These filters allow you to reduce the amount of noise and make it easier to find reports that matter.

We recommend keeping the default set of filters enabled to keep your report data manageable. Those are 'Remove "referrer" value', 'Remove query string', 'Filter violations caused by browser extensions' and 'Filter unactionable CSP violations'. Filtering reports with an 'about' or 'data' blocked-uri will depend on your specific needs.

The 'Sites to collect reports for' field must be filled in and informs us of the domain names you expect to receive reports from. This is a space separated list of domain names.