Content-Security-Policy (CSP)

Content-Security-Policy is an HTTP response header that tells the browser exactly which sources of content are permitted on a page. It is the most effective browser-side defense against cross-site scripting (XSS) and data injection attacks.

How CSP Works

When the browser receives a Content-Security-Policy header, it parses the directives and enforces them for every resource the page attempts to load. If a script, stylesheet, image, or other resource does not match the policy, the browser blocks it and logs a violation. The page still loads, but the blocked resource does not execute or render.

CSP operates on an allowlist model. By default, everything is blocked unless explicitly permitted by a directive. If you do not specify a directive for a particular resource type, the browser falls back to default-src.

Key Directives

• default-src - fallback for any resource type that does not have its own directive. Setting default-src 'none' and then explicitly allowing each type is the most secure approach.
• script-src - controls JavaScript sources. The most important directive for XSS prevention.
• style-src - controls CSS sources, including inline styles.
• img-src - controls image sources.
• connect-src - controls targets for fetch, XMLHttpRequest, WebSocket, and EventSource connections.
• frame-src - controls which origins can be loaded in iframes.
• font-src - controls web font sources.
• object-src - controls plugins (Flash, Java applets). Set to 'none' unless you have a specific need.
• report-uri / report-to - specifies where the browser should send violation reports.

Example Policies

Basic policy

Content-Security-Policy: default-src 'self'; img-src 'self' https://cdn.example.com; style-src 'self' 'unsafe-inline'

This allows scripts, fonts, and connections only from the same origin. Images can come from the same origin or cdn.example.com. Inline styles are permitted (not ideal, but sometimes necessary during migration).

Strict policy with nonces

Content-Security-Policy: default-src 'none'; script-src 'nonce-abc123'; style-src 'nonce-abc123'; img-src 'self'; connect-src 'self'; font-src 'self'; base-uri 'none'; form-action 'self'

Nonces are random values generated per-request by the server. Only <script> and <style> tags with a matching nonce attribute will execute. This is the strongest approach because it does not require maintaining a list of trusted domains and blocks all injected scripts regardless of source.

Source values reference

• 'self' - same origin (scheme + host + port).
• 'none' - block everything for this directive.
• 'unsafe-inline' - allow inline scripts and styles. Largely defeats the purpose of CSP for XSS prevention.
• 'unsafe-eval' - allow eval() and similar dynamic code execution. Avoid if possible.
• 'nonce-{value}' - allow elements with a matching nonce attribute. Preferred over 'unsafe-inline'.
• 'strict-dynamic' - trust scripts loaded by already-trusted scripts. Useful for applications that dynamically load modules.

Report-Only Mode

Use the Content-Security-Policy-Report-Only header to test a policy without enforcing it. The browser evaluates the policy and sends violation reports, but does not block any resources. This lets you identify what would break before going live.

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

Deploy in report-only mode first, review the violation reports, adjust the policy, and then switch to the enforcing Content-Security-Policy header.

Common Mistakes

• Using 'unsafe-inline' for script-src - this allows any inline script to execute, which is exactly what XSS exploits inject. If you need inline scripts, use nonces or hashes instead.
• Overly permissive wildcards - a policy like script-src * or script-src https: allows scripts from any HTTPS origin, including attacker-controlled domains.
• Not testing in report-only first - deploying a strict policy directly can break your site. Always test with Content-Security-Policy-Report-Only before enforcing.
• Ignoring object-src - if you do not set object-src 'none', plugins can be loaded and used as an XSS vector.
• Allowing data: URIs in script-src - data: URIs can contain executable JavaScript and should not be permitted in script sources.

Grade your CSP with the security headers tool →