Content Security Policy (CSP) for Beginners

Content Security Policy is the single strongest defence a website has against cross-site scripting. It works by giving the browser an explicit list of where scripts, styles and other resources may come from — so even if an attacker injects code into your page, the browser refuses to run it.

What CSP actually does

Cross-site scripting (XSS) happens when an attacker manages to inject their own JavaScript into a page your users trust. That script can steal sessions, rewrite the page or exfiltrate data. CSP flips the model from “run anything on the page” to “only run what the site owner has approved.” The browser enforces the rules, so it protects users even against injection paths you did not know existed.

How the header is built

A policy is a series of directives separated by semicolons. Each directive names a resource type and lists the sources allowed for it.

Content-Security-Policy: default-src 'self'; script-src 'self'; img-src 'self' data:; object-src 'none'; frame-ancestors 'self'

The most common directives:

Directive	Controls
default-src	The fallback for any resource type you do not list explicitly.
script-src	Where JavaScript may load from. The most security-critical directive.
style-src	Where CSS may load from.
img-src	Where images may load from.
frame-ancestors	Who may embed your page in a frame — the modern replacement for X-Frame-Options.
object-src	Plugins such as Flash or Java. Set to 'none' on almost every site.

The keyword 'self' means “the same origin as the page.” 'none' blocks everything. You can also list specific hostnames such as https://cdn.example.com.

Inline scripts, nonces and hashes

The hard part of CSP is that a strong policy forbids inline <script> blocks and onclick= handlers, because those are exactly how injected code runs. You have two safe ways to allow the specific inline scripts you actually wrote:

<!-- Nonce: a random value regenerated on every response -->
Content-Security-Policy: script-src 'self' 'nonce-r4nd0m123'
<script nonce="r4nd0m123">/* your code */</script>

A nonce is a one-time random token you put on both the header and each trusted script tag; the browser runs only matching tags. A hash such as 'sha256-...' lets you allow a specific script by its exact content. Avoid 'unsafe-inline' — it switches the protection off. The best long-term goal is a nonce-based policy so no unapproved script can execute.

Roll it out with report-only mode

Deploying a strict policy blind will almost certainly break something. Instead, ship it in report-only mode first:

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

In this mode the browser reports what it would have blocked but does not actually block anything. You collect the violation reports, spot the legitimate resources you forgot to allow — an analytics script, a font host, an embedded video — and widen the policy until reports go quiet. Then switch the header name to Content-Security-Policy to start enforcing.

Where CSP fits

CSP’s frame-ancestors directive also supersedes the older X-Frame-Options header for clickjacking protection in modern browsers. It is one of the highest-value entries on the full security headers checklist. Once your policy is live, run a scan to confirm it is being sent correctly.

Frequently asked questions

Related guides