Content Security Policy (CSP) Explained

Q: What is Content Security Policy?

Content Security Policy (CSP) is an HTTP response header that tells the browser which sources of content a page is allowed to load and execute. It is defined in the W3C CSP specification. CSP is mainly used as a strong layer of defense against cross-site scripting.

Q: Does CSP stop all XSS?

No. CSP is defense-in-depth, not a complete cure for cross-site scripting. It greatly limits what an injected script can do by blocking untrusted or inline code, but it does not fix the underlying injection bug. Proper input handling and output encoding are still required alongside CSP.

Q: What is the difference between default-src and script-src?

The default-src directive is the fallback policy that applies to resource types without their own rule. The script-src directive specifically controls which sources of JavaScript are allowed. Because scripts are the main vector for cross-site scripting, script-src is usually the most important directive to get right.

Q: What is CSP report-only mode?

Report-only mode uses the Content-Security-Policy-Report-Only header so the browser reports what a policy would block without actually blocking anything. This lets you test a policy against real traffic and find legitimate resources you need to allow. It is the recommended way to roll out CSP on an existing website before enforcing it.

Q: Why is my CSP breaking my website?

The most common cause is a policy that is too strict for resources the website genuinely uses, such as third-party scripts or inline code. Deploying in enforce mode without testing in report-only first often blocks legitimate functionality. Reviewing the browser console for blocked-resource messages usually shows which sources to add.

~/sheets/content-security-policy-explained.md

What Content Security Policy is
Content Security Policy (CSP) is an HTTP response header that tells the browser exactly which sources of content a page is allowed to load and execute. It is described in the W3C CSP specification and documented in detail on MDN. CSP is one of several recommended HTTP security headers, and it is the most powerful one for limiting what malicious code can do if it ever reaches a page.
How CSP stops XSS
Cross-site scripting (XSS) works by injecting unauthorized scripts into a page so the browser runs them. CSP undermines this by defining an allowlist of trusted sources. If an injected script comes from a source that is not on the allowlist, or relies on inline code that the policy forbids, the browser refuses to execute it. CSP does not fix the underlying injection bug, but it strongly limits what an injected script can actually achieve, which is why it is treated as defense-in-depth rather than a standalone fix.
Common directives
A CSP is built from directives, each controlling a category of resource. Common ones include:
default-src — the fallback policy for any resource type that does not have its own directive.
script-src — which sources of JavaScript are allowed; the single most important directive for XSS defense.
style-src — which sources of CSS are allowed.
img-src — which sources images can load from.
connect-src — which endpoints scripts can connect to via fetch, XHR, or WebSockets.
frame-ancestors — which sites may embed your page in a frame; the modern replacement for X-Frame-Options.
Sources are often expressed as keywords such as 'self' (the page own origin) or 'none' (block everything), or as specific domains.
Report-only mode
You do not have to enforce a policy from day one. Using the Content-Security-Policy-Report-Only header, the browser checks the policy and reports what would have been blocked without actually blocking anything. This lets you test a policy against real traffic, find legitimate resources you forgot to allow, and tune the rules before switching to full enforcement. It is the recommended way to roll CSP out on an existing website.
Common pitfalls
Overusing 'unsafe-inline' — allowing inline scripts to make things work again largely defeats the XSS protection CSP is meant to provide.
Too-broad allowlists — permitting an entire wildcard host can let attacker-controlled content slip through.
Forgetting default-src — without a sensible fallback, resource types you did not explicitly list may be unrestricted.
Deploying enforce-mode blind — skipping report-only often breaks legitimate functionality and triggers a rushed rollback.
Checking your policy
Because CSP can be intricate, it helps to verify what your server is actually sending. Running your URL through a security headers checker shows whether a CSP is present and surfaces the other security headers you may be missing, so you can build a complete, layered configuration.
Frequently Asked Questions
What is Content Security Policy?
Content Security Policy (CSP) is an HTTP response header that tells the browser which sources of content a page is allowed to load and execute. It is defined in the W3C CSP specification. CSP is mainly used as a strong layer of defense against cross-site scripting.
Does CSP stop all XSS?
No. CSP is defense-in-depth, not a complete cure for cross-site scripting. It greatly limits what an injected script can do by blocking untrusted or inline code, but it does not fix the underlying injection bug. Proper input handling and output encoding are still required alongside CSP.
What is the difference between default-src and script-src?
The default-src directive is the fallback policy that applies to resource types without their own rule. The script-src directive specifically controls which sources of JavaScript are allowed. Because scripts are the main vector for cross-site scripting, script-src is usually the most important directive to get right.
What is CSP report-only mode?
Report-only mode uses the Content-Security-Policy-Report-Only header so the browser reports what a policy would block without actually blocking anything. This lets you test a policy against real traffic and find legitimate resources you need to allow. It is the recommended way to roll out CSP on an existing website before enforcing it.
Why is my CSP breaking my website?
The most common cause is a policy that is too strict for resources the website genuinely uses, such as third-party scripts or inline code. Deploying in enforce mode without testing in report-only first often blocks legitimate functionality. Reviewing the browser console for blocked-resource messages usually shows which sources to add.
Last updated: April 2026