Definition
- Content Security Policy (CSP) is a series of instructions from a site to the browser, which uses them to limit what the code making up the page is allowed to do. MDN says its main use is to control which resources, JavaScript above all, a document may load, as a defence against cross-site scripting (XSS).
- The policy arrives in the
Content-Security-Policyresponse header, and MDN advises setting it on every response, not only the main document. It is a list of directives separated by semicolons, each a name followed by its value.default-src 'self'asks the browser to load only what comes from the document's own origin, unless a more specific directive says otherwise. - Directives include
script-srcfor JavaScript sources,default-srcas the fallback for any resource with no directive of its own, andframe-ancestorsfor who may embed the page in a frame such as an<iframe>. - The
Content-Security-Policy-Report-Onlyheader tries a policy without enforcing it: it blocks nothing, but violations go to the reporting endpoint named in the policy. A policy can also be set in a<meta http-equiv="Content-Security-Policy">tag, though that does not support every feature.
Why it matters
- Script injection means someone slips a script into your page, through a comment or a search field for example, and the browser runs it as if it came from you. If the script comes from a source the policy does not allow, the browser does not run it.
- MDN and the W3C both describe the policy as defence in depth: it limits the damage of an injection, but does not replace sanitising input and encoding output before it is shown.
- With
default-srcorscript-srcin the policy, inline JavaScript is blocked, meaning a<script>written in the page, event handlers such asonclickandjavascript:links, unless extra measures enable it. So a page that loads scripts from other sites, or has inline scripts, needs a policy that names those sources. - MDN adds that CSP is also used to guard against the page being embedded in deceptive frames (clickjacking), and to help make sure a site's pages load over HTTPS. See also HSTS and mixed content.
- Arablyzer's
csp-missingrule checks that an enforced policy exists, not how tight it is: theContent-Security-Policy-Report-Onlyheader alone does not count.
Example
Start with a trial policy that reports violations and blocks nothing. MDN says the report-to directive is required in this header or nothing is sent, and the destination is defined in the Reporting-Endpoints header:
http
Reporting-Endpoints: csp-endpoint="https://example.com/csp-reports"
Content-Security-Policy-Report-Only: default-src 'self'; script-src 'self' https://cdn.example.com; report-to csp-endpointRead the reports that arrive, adjust the policy until it names only what your pages need, then send it enforced:
http
Content-Security-Policy: default-src 'self'; script-src 'self' https://cdn.example.com; frame-ancestors 'none'MDN advises that unless you want your page embedded in other pages, you set frame-ancestors to 'none'.
Common mistakes
- Sending only
Content-Security-Policy-Report-Onlyand assuming the page is protected: it reports, it does not block. - Putting
frame-ancestors,report-uriorsandboxin a<meta>tag: the W3C says the tag does not support them, norReport-Only. - Placing the
<meta>tag after the scripts: its policy does not cover content that comes before it, and the W3C encourages putting it early. - Adding
'unsafe-inline'to silence errors: MDN warns it defeats much of the purpose of the policy. Use a nonce or a hash instead. - A fixed or guessable nonce: it must change with every response and not be predictable (MDN).
- Treating the policy as a substitute for sanitising what visitors type.