Content Security Policy Explained for Developers

A Content security policy (CSP) is a set of rules your server sends that tells the browser what it’s allowed to load or run.

One header line changes how attackers play. Bad scripts stop slipping through quietly, the browser blocks them and tells you it did.

What is Content Security Policy?

In practice, the policy is sent through the Content-Security-Policy HTTP response header or, in limited cases, as a <meta> element.

The header lists allowed sources for scripts, styles, images, frames, fonts, and similar resources. When a browser sees the header, it checks each attempted load against those rules and blocks loads that don’t match. That blocking happens on the client; blocked attempts can also be reported to a server you control.

A policy is a sequence of directives such as script-src, img-src, connect-src, and frame-ancestors. Each directive names allowed origins, schemes, or special tokens ('self', 'nonce-...', 'sha256-...', or 'unsafe-inline').

For example, script-src 'self' https://cdn.example.com allows scripts from the same origin and that CDN; anything else is refused. That refusal is the key: a browser won’t run injected JavaScript that comes from a disallowed origin. The W3C specification defines the full directive set and the algorithms browsers use to decide what to block.

Why this Header Cuts off Most Browser-Side Attacks

Think of CSP as a gatekeeper. It doesn’t fix a vulnerable function in your code, but it prevents an attacker from turning that vulnerability into a live arbitrary-script execution on users’ browsers unless they can also load code from an allowed source. That makes exploitation harder and more visible.

Two technical knobs deserve attention because they shape how developers adopt CSP:

• Nonces and hashes. A nonce is a random token generated per HTTP response and embedded in the header and inline <script> tags that you want to allow. A hash allows a specific static inline script by its cryptographic digest. Both let you permit required inline code without opening unsafe-inline.
• strict-dynamic. When used with nonces or hashes, strict-dynamic tells modern browsers to trust scripts created by a trusted, nonce-bearing script instead of enumerating every upstream host. That can simplify policies for complex frontends but transfers trust to scripts you already allowed. Use it only when you control the primary, nonce-bearing scripts and when you audit any libraries they pull in.

On an engagement I saw a marketing tool inject an inline tracker into every page. Without a policy, that tracker could be hijacked and become an attack vector.

After adding a nonce-based policy and moving the tracker to an external, SRI-protected file, the injected inline code failed to execute.

The site’s client-side logs showed the rejected attempts, which we used to push the marketing vendor to a safer integration. That visibility turned a recurring blind spot into a clear remediation path.

Deploying a Content Security Policy Without Breaking Users

Start with a tiered approach such as collecting data, removing fragile inline code, then enforcing.

1. Start with report-only. Let it warn you instead of blocking things, watch what would have broken.
2. Pay off inline code. Move inline scripts and styles into external files when feasible. If you must keep inline actions (templated markup, fast bootstrapping scripts), consider nonces or hashes. Nonces work well for server-rendered pages where you can inject a fresh token per response; hashes suit static sites rebuilt from a CI pipeline. Both options keep inline code allowed without granting global permissions via unsafe-inline.
3. Tighten hosts. Restrict script-src, connect-src, img-src, and other directives to the smallest set of origins you need. Avoid wide allowances like https: or * unless you have a clear, unavoidable case.
4. Move to enforcement. When reports show no surprising rejections and your app runs cleanly with the header applied, switch the header name to Content-Security-Policy to enable blocking.

Tuning Content Security Policy: Nonces, Hashes, and Third-Party Code

Nonces require generation of a cryptographically strong random value per response and injection both in the header and the script tags you trust.

If the nonce is predictable or reused, the protection collapses.

Hashes avoid per-response state by allowing a specific block of script text, but they don’t work for dynamically generated content.

For third-party libraries hosted on CDNs, use Subresource Integrity (SRI) when you can; SRI ensures that a fetched script matches an expected hash, preventing supply-chain tampering for static files.

SRI checks that a file hasn’t been tampered with. The policy just decides which places your scripts can come from. They cover different holes.

strict-dynamic reduces the maintenance burden for modern apps that load dependency graphs at runtime. When combined with nonces, the browser allows scripts derived from a nonce-bearing script even if those sub-resources come from other hosts.

That’s convenient for single-page apps, but it puts heavy trust in the initial script. If that initial script ever becomes compromised, strict-dynamic amplifies the impact. Balance convenience against the privilege you grant.

For broader guidance on directive choices and strict-dynamic trade-offs, consult the specification and practical implementation guides.

Reporting: Where Rejections Go and How to Treat Them

You can collect CSP violation reports using report-uri or the newer report-to with the Reporting API. Browser support for report-to varies; many sites include both directives during transition.

Reports arrive as JSON payloads describing the blocked resource, the violating directive, and the page URL.

Treat these reports as operational telemetry: store them, deduplicate repetitive entries, and use them as inputs for remediation. Be cautious when ingesting reports, an attacker can flood your endpoint with fake reports, so apply rate limits and minimal parsing.

Operational runbook example:

• Send Content-Security-Policy-Report-Only for two weeks.
• Review top 20 violators; classify whether each is benign, requires a nonce/hash, or indicates upstream compromise.
• Migrate inline code to external files or use nonces/hashes as needed.
• Switch to enforcement and monitor for new violations.

Common Mistakes and How to Avoid Them

Many developers adopt CSP but leave safety holes that reduce effectiveness. Here are persistent errors I’ve seen during audits and how to fix them.

• Using unsafe-inline. This token defeats the main benefit of CSP. If you find unsafe-inline in a policy, treat it as a teardown item: replace with nonces or hashes.
• Broad host allowances. Wildcards, https:, or overly large CDNs open the door to supply-chain or CDN misconfiguration problems. Pin origins where possible.
• Predictable nonces. Nonces must be cryptographically random per response. Reuse or predictability is equivalent to unsafe-inline.
• Relying on CSP alone. CSP is defense in depth. Continue secure coding practices, output encoding, and server-side input validation. CSP reduces exploitability; it does not remove the need for fixes in application code.
• Ignoring reports. The value of a Content security policy often comes from the visibility it provides. Treat reports as high-quality signals, not noise. OWASP and browser vendors share testing guides and examples you can follow.

Real-world considerations for modern stacks

What works for a static blog won’t work for a React app. You’ll end up tuning it differently depending on how your pages load scripts.

• Server-rendered sites (templating engines): Nonces work well because you can generate a per-response token and insert it into rendered script tags. Use strict CSP settings and test with report-only first.
• Static sites and CDNs: Use hashes for inline content generated at build time and prefer external files with SRI for third-party scripts. If you host content on a CDN where you cannot control headers, a <meta http-equiv> tag is an option but has limits.
• SPAs and module loaders: Consider strict-dynamic with nonces for the minimal trusted boot bundle, then rely on careful controls for any runtime module fetching.

If your app uses many third-party integrations such as A/B testing, widgets, tag managers, inventory them before locking down the policy.

Move as much as you can into well-known external files with SRI and avoid inline injections from vendors.

For tag managers that require dynamic content, a controlled pattern using a single, audited bootstrap script plus strict-dynamic is often more maintainable than allowlisting dozens of hosts.

No single header replaces careful coding. But a well-designed Content security policy turns invisible attacks into visible signals and forces the supply chain to be explicit. For developers that ship web features, that explicitness is the point: you trade silent risk for manageable, auditable constraints.