Content Security Policy report-only: test a CSP and fix what it blocks

What Content-Security-Policy-Report-Only does

A Content Security Policy can be sent in two forms. Content-Security-Policy enforces the rules: the browser refuses to load anything the policy does not allow. Content-Security-Policy-Report-Only takes exactly the same directives, but the browser blocks nothing. It only notes each resource that would have been refused, prints a warning in the Console and, if you give it an address, sends a report.

Content-Security-Policy-Report-Only: default-src 'self'; img-src 'self' data:; object-src 'none'; base-uri 'self'; report-uri /csp-reports

That makes report-only the safe way to introduce or tighten a policy on a live site. You see the full list of scripts, styles, fonts, frames and connections your pages actually use, including ones added by plugins and tag managers that nobody remembers, before a single visitor sees a broken page.

You can send both headers at once. A common pattern is to enforce a loose policy you know works while trialling a stricter one in report-only mode. The browser applies them independently.

Where a Content Security Policy is set

One of the most common questions is simply where the policy comes from, because it can be added at several layers and the browser cannot tell you which one sent it. Work through these in order until you find it.

To see what is actually delivered, request the page and look at both the headers and the HTML:

curl -sI https://example.com/ | grep -i content-security
curl -s https://example.com/ | grep -io '<meta[^>]*content-security[^>]*>'

If the header appears on the CDN address but not when you request the origin server directly, the CDN is adding it. If it appears on every site on the server, it is in a global configuration file rather than the site's own. On a Linux server you can search configuration for it:

sudo grep -ril "content-security-policy" /etc/nginx /etc/apache2 /etc/httpd /var/www/vhosts/*/conf 2>/dev/null

The platform guides for nginx, Cloudflare and WordPress show where each one stores headers.

Why default-src 'self' is not working

People often add default-src 'self', see the site break or see nothing change at all, and conclude the policy is not working. It nearly always is working; it is just doing something different from what they expected. These are the usual reasons.

A further trap is two policies. If a plugin sends one header and your server sends another, both are enforced, and a resource has to be allowed by both. Adding a host to one of them then appears to make no difference.

How to receive and read violation reports

The Console shows violations in your own browser. To see what real visitors' browsers hit, on pages and devices you never test, add a reporting directive. There are two, and it is sensible to send both for now.

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

report-uri is the older directive and is marked deprecated, but it is still widely supported. report-to names an endpoint from the Reporting-Endpoints header. Browsers that support report-to use it and ignore report-uri; others fall back to report-uri. Reporting directives are ignored in a meta tag, so this needs a real header.

What a report looks like

A report-uri report arrives as a POST with the content type application/csp-report:

{
  "csp-report": {
    "document-uri": "https://example.com/menu",
    "violated-directive": "font-src",
    "effective-directive": "font-src",
    "blocked-uri": "https://fonts.gstatic.com",
    "disposition": "report",
    "original-policy": "default-src 'self'; object-src 'none'; report-uri /csp-reports"
  }
}

Reports sent through report-to use the content type application/reports+json, arrive as an array, and use camel-case field names such as documentURL, blockedURL and effectiveDirective. A small endpoint only has to accept the POST, write the body to a log and return 204.

Reading them

• Group by effective directive and blocked address. Fifty reports about one font host are one decision, not fifty.
• A blocked value of inline means inline code, eval means string evaluation in a script, and data means a data address.
• Reports about chrome-extension, moz-extension or unknown ad domains usually come from visitors' browser extensions. Ignore them rather than allowing them.

Adding the report-only header on common servers

Use the same header name and policy whichever server you have. Only the syntax changes.

nginx

add_header Content-Security-Policy-Report-Only "default-src 'self'; img-src 'self' data:; object-src 'none'; base-uri 'self'; report-uri /csp-reports" always;

The always flag adds the header to error responses as well. Remember that any add_header in a location block replaces those set higher up.

Apache or .htaccess

<IfModule mod_headers.c>
  Header always set Content-Security-Policy-Report-Only "default-src 'self'; img-src 'self' data:; object-src 'none'; base-uri 'self'; report-uri /csp-reports"
</IfModule>

Plesk

On a Plesk server, open the domain, go to Apache and nginx Settings, and add the nginx line to the additional nginx directives, or the Apache line to the additional HTTP and HTTPS directives. Use one, not both. The Plesk security headers guide shows the screens.

Cloudflare

Create a Response Header Transform Rule that sets Content-Security-Policy-Report-Only to your policy. Check that your origin is not sending its own policy too.

After any change, run curl -sI again and confirm the header appears once, with the exact name and policy you intended.

A worked example: from report-only to enforced

Example Bakery adds default-src 'self'; object-src 'none'; base-uri 'self' as report-only on its WordPress site, with a report-uri pointing to a small logging script. After three days the log holds about 2,400 reports, which group into six lines:

They add the five decisions, leave it in report-only mode for another week, and see only extension noise. They then rename the header to Content-Security-Policy, keep report-uri, and watch the log for the first few days after the change.

The fix, step by step

Edge cases worth knowing

• Meta tags cannot be report-only. Browsers ignore Content-Security-Policy-Report-Only in a meta tag, so a report-only trial always needs a real header.
• Report volume. A busy site can send thousands of reports an hour. Sample them, rate-limit the endpoint, or use a hosted collector, and never let the endpoint slow down page delivery.
• Reports contain addresses. The document and blocked addresses can include query strings with personal data. Store reports securely and delete them when you are done.
• Cached pages. A full-page cache or CDN can serve old headers for hours. Purge it after each policy change, or the reports describe the old policy.
• Directives that never report. If a directive is missing from the policy and default-src does not cover it, as with frame-ancestors, nothing is ever reported for it. Add it explicitly.

Keeping the policy healthy

Once enforced, keep the reporting directive. It is the only way you will hear that a new marketing tag or a plugin update has started loading from a host the policy does not allow.

• Trial every tightening of the policy as a second, report-only header alongside the enforced one.
• Keep the policy in one place, with a note against each third-party host explaining what uses it.
• Check the report log weekly at first, then monthly, and after every plugin, theme or tag manager change.
• Remove hosts you no longer use. A shorter allow list is a smaller target.

The framework CSP guide covers Spring Boot, Tomcat and Angular, and the missing security headers guide covers the other headers scanners expect.