CSP Reporting with report-uri

CSP Violation Reporting

CSP reporting allows you to receive notifications when the browser blocks a resource or detects a policy violation. This is essential for deploying and maintaining a Content Security Policy in production.

report-uri Directive

The report-uri directive specifies an endpoint that receives violation reports:

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

When a violation occurs, the browser sends a JSON POST request to the specified URL:

{
  "csp-report": {
    "document-uri": "https://example.com/page",
    "referrer": "",
    "violated-directive": "script-src 'self'",
    "effective-directive": "script-src",
    "original-policy": "default-src 'self'; report-uri /csp-report",
    "blocked-uri": "https://evil.example.com/malicious.js",
    "status-code": 200,
    "source-file": "https://example.com/page",
    "line-number": 42,
    "column-number": 15
  }
}

report-to Directive (Newer Standard)

report-to is the newer replacement for report-uri. It uses the Reporting API and requires a Report-To header:

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

Report-Only Mode

Use Content-Security-Policy-Report-Only to collect violation reports without blocking resources:

Content-Security-Policy-Report-Only: default-src 'self'; script-src 'self'; report-uri /csp-report

This is the recommended way to test a new CSP before enforcing it. You can run report-only and enforced policies simultaneously:

Content-Security-Policy: default-src 'self'
Content-Security-Policy-Report-Only: default-src 'self'; script-src 'self' 'strict-dynamic'; report-uri /csp-report

Handling Report Volume

Production sites can generate thousands of CSP reports per minute. Best practices:

• Sampling — only send a percentage of reports: add server-side sampling logic
• Deduplication — group identical violations by directive + blocked URI
• Filtering — ignore reports from browser extensions (blocked-uri often contains chrome-extension://)
• Rate limiting — cap the number of reports processed per second

Third-Party Reporting Services

Several services specialize in CSP report collection and analysis:

• Report URI (report-uri.com) — dedicated CSP reporting SaaS
• Sentry — supports CSP report ingestion
• Your own endpoint — a simple Express/Flask route that logs JSON to a database

Iterative CSP Deployment

1. Start with Content-Security-Policy-Report-Only and a permissive policy
2. Collect reports for 1-2 weeks
3. Analyze violations and adjust the policy
4. Tighten the policy and repeat
5. Once stable, switch to Content-Security-Policy (enforced mode)
6. Keep report-uri active in enforced mode to catch regressions