Content-Security-Policy-Report-Only HTTP Header

The Content-Security-Policy-Report-Only HTTP response header is a powerful tool for testing and monitoring Content Security Policy (CSP) configurations without enforcing them. It allows you to evaluate potential CSP violations in production without risking the functionality of your website.

Understanding Report-Only Mode

Unlike the standard Content-Security-Policy header, the Content-Security-Policy-Report-Only header:

Monitors potential CSP violations
Does not block any content
Generates violation reports for analysis
Is perfect for testing new policies before enforcement

Basic Report-Only CSP configuration

Content-Security-Policy-Report-Only: 
  default-src' self';
  script-src'self' 'report-sample';
  style-src 'self';
  img-src 'self' ;
  font-src 'self';
  object-src 'none';
  base-uri 'none';
  form-action 'none';
  base-uri 'none';
  frame-ancestors 'none';
  frame-src 'self';
  connect-src 'none';
  upgrade-insecure-requests;
  report-uri https://report.centralcsp.com/<myendpoint>;

Monitor CSP violations effectively

Get comprehensive visibility into security policy violations with our centralized reporting platform.

Start monitoring with a 14 days free trial

Use Cases

1. Testing New Policies

Before enforcing a strict CSP, you can test it in report-only mode to identify potential issues:

Testing a strict CSP in report-only mode

Content-Security-Policy-Report-Only: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:;

2. Monitoring Existing Policies

Use report-only mode alongside your enforced policy to monitor for additional violations:

Monitoring with both enforced and report-only policies

Content-Security-Policy: 
  default-src 'self'; 
  script-src 'self' https://trusted.com;

Content-Security-Policy-Report-Only: 
  default-src 'self'; 
  script-src 'self';

3. Gradual Policy Implementation

Implement policies gradually by starting with report-only mode:

Gradual policy implementation

# Phase 1: Report-Only Mode
Content-Security-Policy-Report-Only: 
  default-src 'self'; 
  script-src 'self' https://trusted.com;

# Phase 2: After Analysis
Content-Security-Policy: 
  default-src 'self'; 
  script-src 'self' https://trusted.com;

Report Format

When a violation occurs, the browser sends a JSON report to the specified endpoint:

Example CSP violation report

{
"csp-report": {
      "document-uri": "https://example.com/page.html",
      "referrer": "https://google.com",
      "violated-directive": "script-src",
      "effective-directive": "script-src",
      "original-policy": "default-src 'self'; script-src 'self' https://trusted.com; report-uri https://report.centralcsp.com/<myendpoint>",
      "disposition": "report",
      "blocked-uri": "https://untrusted.com/script.js",
      "line-number": 15,
      "column-number": 10,
      "source-file": "https://example.com/page.html",
      "status-code": 0,
      "script-sample": "alert('test')"
  }
}

Best Practices

1. Start with Report-Only Mode

Implementation Strategy

Always begin with report-only mode to understand potential impacts before enforcing policies.

2. Use Multiple Report-Only Policies

You can define multiple report-only policies to test different configurations:

Multiple report-only policies

Content-Security-Policy-Report-Only: default-src 'self'; script-src 'self' https://trusted.com;
Content-Security-Policy-Report-Only: default-src 'self'; script-src 'self' https://trusted.com https://analytics.com;

3. Regular Analysis

Regular Review

Regularly analyze violation reports to identify patterns and adjust policies accordingly.

Limitations and Considerations

No Blocking: Report-only mode never blocks content, only reports violations
Multiple Policies: Can be used alongside enforced policies
Report Processing: Requires a system to collect and analyze violation reports
Browser Support: Supported in all modern browsers

Implementation Examples

Nginx Configuration

Nginx configuration for Report-Only CSP

add_header Content-Security-Policy-Report-Only "default-src 'self'; script-src 'self' https://trusted.com; report-uri https://report.centralcsp.com/<myendpoint>";

Apache Configuration

Apache configuration for Report-Only CSP

Header set Content-Security-Policy-Report-Only "default-src 'self'; script-src 'self' https://trusted.com; report-uri https://report.centralcsp.com/<myendpoint>"

Related Resources

Conclusion

The Content-Security-Policy-Report-Only header is an essential tool for testing and monitoring CSP configurations. It allows you to identify potential security issues without risking website functionality, making it perfect for gradual policy implementation and ongoing security monitoring.

Previous doc

CSP Headers

Next doc

Report-To Header