Content-Security-Policy (CSP): what it is and how to deploy it safely

What is Content-Security-Policy?

Content-Security-Policy (CSP) is an HTTP response header that tells the browser which sources a page is allowed to load scripts, styles, images, fonts, frames and other resources from. When the page tries to load or run anything the policy does not allow, the browser blocks it and logs a violation. Its main purpose is to limit cross-site scripting (XSS): a script injected into your page does not run if it does not match the policy.

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

Content-Security-Policy: default-src 'self'; script-src 'self' https://cdn.example.com; object-src 'none'; frame-ancestors 'none'

This policy loads everything from the page’s own origin ('self'), also allows scripts from cdn.example.com, forbids plugins, and stops other sites from framing the page. Inline <script> blocks, onclick attributes and javascript: URLs are blocked because the policy does not allow 'unsafe-inline'.

CSP is a second line of defence. It does not fix the injection bug, but it decides what the injected code can do. Adoption is still low: in Scott Helme’s June 2026 crawl, 170,057 of the 819,002 top sites that responded sent a Content-Security-Policy header (about 21%), and 46.8% of those policies contained 'unsafe-inline'.

What CSP protects against

The directives that matter

Fetch directives control where each type of resource can come from. When one is missing, the browser falls back to default-src.

These directives are not covered by default-src, so set them explicitly:

Source values are matched exactly. 'self' means the page’s own scheme, host and port, not its subdomains. Keywords such as 'self', 'none' and 'unsafe-inline' keep their single quotes; host names do not.

Allowlists versus strict policies

The first instinct is to list every domain your scripts come from. That is called an allowlist policy, and it is the weakest way to use CSP.

Google researchers analysed policies from 1.68 million hosts in 2016. They found that 94.72% of distinct policies could be bypassed, and that 14 of the 15 domains most often allowed for scripts hosted endpoints an attacker could abuse, such as JSONP callbacks or old AngularJS copies. If a domain on your list serves anything an attacker can steer, they load their payload from it and your policy waves it through.

A strict policy trusts individual scripts instead of whole domains:

• Nonces. The server generates a fresh random value for each response (at least 128 bits), puts it in the header as 'nonce-<value>' and on each legitimate <script nonce="<value>">. Injected scripts cannot guess it. This suits pages rendered by an application.
• Hashes. The header lists the SHA-256, SHA-384 or SHA-512 hash of each inline script, such as 'sha256-…'. Only those exact scripts run. This suits static sites, where the content does not change per request.
• 'strict-dynamic'. Scripts that were trusted by nonce or hash may load further scripts, so you do not have to list every bundle a tag manager or framework pulls in. In browsers that support it, allowlisted hosts and 'self' in script-src are ignored.

The policy recommended by Google’s security team, and our default for applications:

Content-Security-Policy: script-src 'nonce-{RANDOM}' 'strict-dynamic'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'

You will often see https: 'unsafe-inline' appended as a fallback for old browsers. Browsers that understand nonces ignore those two values, which is every browser with CSP Level 2 support. We recommend leaving them out: WebSec0 reads 'unsafe-inline' in script-src as a weakness, nonce or not.

Since early 2026, Trusted Types work in all major browsers. Adding require-trusted-types-for 'script' to a strict policy also blocks DOM-based XSS, where your own JavaScript writes attacker-controlled strings into innerHTML and similar sinks. It needs code changes, so test it in report-only mode first.

Three policies to start from

Pick the one closest to your site, then adjust the sources to what you actually load.

A static site or documentation with no inline scripts (or with hashes for the few it has):

Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'; upgrade-insecure-requests

A server-rendered application that can add a nonce to each response. Replace {RANDOM} with a new value for every response, and never cache a page together with its nonce:

Content-Security-Policy: script-src 'nonce-{RANDOM}' 'strict-dynamic'; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'

A JSON API or anything that never renders HTML:

Content-Security-Policy: default-src 'none'; frame-ancestors 'none'

Roll it out without breaking your site

A policy that is too strict breaks scripts, fonts or analytics the moment it is enforced. Test it first:

1. Inventory what you load. Open your main pages with the browser’s network panel and note every script, style, font, image and API origin, plus any inline <script> blocks and on* attributes.

2. Ship it in report-only mode. Send the policy as Content-Security-Policy-Report-Only. The browser blocks nothing and reports every violation to the console and to your endpoint:

   Reporting-Endpoints: csp-endpoint="https://example.com/csp-reports"
   Content-Security-Policy-Report-Only: default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'; report-to csp-endpoint; report-uri https://example.com/csp-reports

   report-to works in all major browsers since 2026; report-uri covers older ones and is ignored by browsers that understand report-to.

3. Fix the violations. Move inline scripts and event handlers into files, add nonces or hashes to the inline scripts you keep, and allow the specific origins you rely on rather than broad schemes like https:.

4. Leave it running for a while. A week of real traffic catches pages, browser extensions and third-party scripts that a manual test misses. Extension noise (chrome-extension://, moz-extension://) can be ignored.

5. Enforce it. Rename the header to Content-Security-Policy. You can keep a stricter candidate running in report-only mode next to it: the browser enforces one and reports on the other.

6. Check every response. Error pages, redirects and API routes need the header too. Scan the site with WebSec0 to confirm it is served and graded.

Common mistakes

• 'unsafe-inline' in script-src. It re-allows inline scripts and onerror= handlers, the most common XSS payloads. Use nonces or hashes.
• 'unsafe-eval'. It allows eval(), new Function() and string timers. Most modern libraries no longer need it.
• Wildcards and schemes. *, https: or data: in script-src allow scripts from almost anywhere.
• Allowing a whole CDN. https://cdn.jsdelivr.net or https://unpkg.com serves any package anyone has published, including an attacker’s. Self-host the file or use a nonce.
• Forgetting the directives default-src does not cover. Without base-uri, form-action and frame-ancestors, those protections are off.
• Only setting it on the home page. Error pages, login flows and older sections are often served by a different rule or application.
• Reusing or caching nonces. A nonce that is the same on every response, or frozen in a CDN cache, gives an attacker the key.
• Relying on a <meta> tag. It cannot set frame-ancestors, cannot report, and only covers what is parsed after it.

How WebSec0 grades Content-Security-Policy

CSP is the heaviest header in the WebSec0 headers grade: 25 of the 100 points. The scanner reads the Content-Security-Policy response header of your page and scores it like this:

A few details follow from how the check works:

• Content-Security-Policy-Report-Only and <meta> policies are not graded. Report-only is a testing mode, not protection.
• When the response carries several CSP headers, the first one is graded.
• A frame-ancestors directive also makes the X-Frame-Options check pass, worth another 15 points, even if you do not send X-Frame-Options.
• The grade does not yet look at 'unsafe-eval', wildcards or bypassable allowlists. A passing grade is a floor, not proof the policy is strict: aim for the strict policy above.