Monitoring CSP with Reports

In our previous article, we introduced Content Security Policies. They are clearly a powerful tool to improve securiy for your web applications. However they are not that simple to use. Let us see what can go wrong and how to prevent it.

Potential CSP issues

The core concept of CSP is to configure which resources are allowed to be loaded on a web page. As a result, it is way too easy to either allow potentially dangerous content or to block legitimate content.

Allowing resources which are not necessary for the website but can be used for nefarious goals can result in security breaches and data leaks.

Blocking legitimate content by mistake can also be a problem. Imagine that you just updated your website with a new comment system, some features using a Javascript library hosted on a CDN. If you forgot to update your policy, you could end up with these features not working in production, without any warning.

In some cases, you can even see bugs in important parts of your website without even having modified them. For example, Javascript code loaded from external servers could change and start using content from hosts which are not allowed by your policies. While this behaviour is the very reason why CSP are essential for security, you also need to be notified when this happens to prevent potentially costly bugs.

Configuring CSP reporting

Fortunately, CSP comes with a reporting feature: with the right directive, web browsers will send a report for each policy violation to a URI of your choice. Each report is a small JSON document containing information about the violation, helping you find out what went wrong.

CSP reporting

The report-uri directive

The report-uri directive is the simplest way to configure CSP reporting. When a policy sets report-uri to the URI of the reporting endpoint, web browser will send a report to this endpoint for each violation.


Content-Security-Policy: default-src 'self'; report-uri

The report-to directive

The report-to directive is a more modern way of configuring reporting. Its value is the name of a reporting endpoint. When using this method, you must configure a reporting endpoint using the Report-To HTTP header field.


Content-Security-Policy: default-src 'self'; report-to csp
Report-To: {"group": "csp", "endpoints": [{"url": ""}]}

Note that while the report-to directive is more flexible, it is currently unsupported on various web browsers, including Firefox, Opera and Safari.

Because of that, we recommend sticking to the report-uri directive.

Blocking and reporting

To help with policy writing, CSP provides two enforcement modes: the web browser can either block and report each violation, or simply report it.

This makes it possible to write policies in report-only mode to test their effects without risking blocking legitimate content. This is especially useful if you want to start using CSP on a well established website: you can incrementally improve your policies and monitor reports, then enable blocking once you are confident.

When the policy is declared with the Content-Security-Policy header field, the web browser blocks and reports violations. To switch to reporting only, simply use the Content-Security-Policy-Report-Only to declare your policy.

Even better, you can use both fields: when you do so, web browsers will enforce the policy declared with Content-Security-Policy, and report violations to the policy declared with Content-Security-Policy-Report-Only. This way, you can enforce directives you have already tested, while testing new ones without any risk.

Collecting and analyzing reports

While CSP reporting is incredibly useful, analyzing reports is hard: web browsers send very different report fields, sometimes changing from one version to another. Browser extensions can also alter web pages in strange way, producing reports which do not seem to make any sense.

As a result, a platform collecting and analyzing reports must be able to aggregate reports in a meaningful way, sorting through the noise to clearly show both potential attacks and violations resulting from policy mistakes.

The CSPWatch platform was developed precisely with that goal in mind.

In future articles, we will see how to write policies for specific use cases.