Skip to content
Velloreth
Cybersecurity 5 min read

Content Security Policy: A Practical Guide

CSP restricts what a page may load, which blunts a cross-site scripting attack. Learn the directives, the nonce, and the report-only mode.

By

What CSP does

CSP is a response header that declares which sources a page may load from.

Content-Security-Policy: default-src 'self'; img-src 'self' data:; script-src 'self'

The browser enforces it. A resource from a source not in the policy is blocked, and the console shows a violation.

The main value is against cross-site scripting. An injected script is blocked unless its source is allowed, which limits the damage of an injection bug.

It is defence in depth. It does not fix the injection; it limits what the injection can do.

The directives

DirectiveControls
default-srcThe fallback for the others
script-srcJavaScript
style-srcCSS
img-srcImages
font-srcWeb fonts
connect-srcfetch, XHR, WebSocket
frame-srcIframes
object-srcPlugins
base-uriThe <base> tag
form-actionWhere a form may submit
frame-ancestorsWho may embed the page

default-src is the fallback. A directive that is not set inherits from it, which is why a policy usually starts with a strict default-src and then opens specific directives.

frame-ancestors replaces the X-Frame-Options header, and it is the modern way to prevent clickjacking.

base-uri 'none' prevents an injected <base> tag from redirecting every relative URL, which is a subtle attack.

A starter policy

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 'none';
  frame-ancestors 'none';
  form-action 'self'

This is a strict policy for a site with no third-party resource.

object-src 'none' disables a plugin, which is a legacy attack surface.

frame-ancestors 'none' prevents the page from being embedded, which stops clickjacking.

The policy breaks a site that loads a third-party script, which is why the rollout is done in report-only mode first.

The nonce

A nonce is a random value generated per response.

Content-Security-Policy: script-src 'nonce-a8f3c9d2'
<script nonce="a8f3c9d2">
  // This script runs
</script>

The browser runs a script only if its nonce matches.

This allows an inline script without allowing every inline script, which is the point. 'unsafe-inline' allows any inline script, including an injected one.

The nonce must be random per response, and it must not be reused. A static nonce is as bad as 'unsafe-inline'.

A hash is the alternative for a static inline script:

Content-Security-Policy: script-src 'sha256-abc123...'

The hash is of the script’s content, so a change to the script requires a change to the policy.

Report-Only mode

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

The browser reports a violation without blocking it.

This is how a policy is rolled out. Deploy in report-only mode, collect the violations, fix the policy, and then enforce it.

The report endpoint receives a JSON body with the violated directive and the blocked URL.

{
  "csp-report": {
    "violated-directive": "img-src",
    "blocked-uri": "https://images.example.com/photo.jpg",
    "document-uri": "https://app.example.com/page"
  }
}

report-to is the newer mechanism, and report-uri is deprecated but still widely supported.

Common mistakes

'unsafe-inline' in script-src. It allows any inline script, which removes most of the protection.

A static nonce. It is as weak as 'unsafe-inline'.

A missing img-src origin. The site’s own images are blocked, which is a common and confusing failure.

A policy that is too strict on the first deploy. The site breaks in production. Use report-only first.

No base-uri. An injected <base> tag redirects every relative URL.

No frame-ancestors. The page can be embedded in a clickjacking attack.

A wildcard in script-src. script-src * allows any script, which is no protection.

CSP and a static site

A static site has the simplest policy, because it loads only its own assets.

Content-Security-Policy:
  default-src 'self';
  img-src 'self' data:;
  style-src 'self' 'unsafe-inline';
  script-src 'self';
  font-src 'self';
  object-src 'none';
  base-uri 'none';
  frame-ancestors 'none'

style-src 'unsafe-inline' is often needed for a framework that injects a style, and it is a smaller risk than an inline script.

A self-hosted font avoids a font-src exception, which is one reason to self-host rather than use a third-party font.

A self-hosted image avoids an img-src exception, which is the fix for the common “CSP blocks my images” problem.

Rolling out a policy

The rollout is the part that determines whether CSP helps or hurts, and the sequence matters more than the policy itself. The first step is to deploy in report-only mode with a policy that is as strict as you intend to be, and to collect the violations for a week. The second is to read the reports and separate the legitimate resources from the ones that should not be there, because a report often reveals a third-party script that nobody remembered adding. The third is to fix the policy and the site together, by self-hosting a font or an image rather than adding an exception. The fourth is to enforce the policy, and to keep the report endpoint active so a new violation is visible. The fifth is to tighten the policy over time, because a policy that is enforced and never revisited drifts away from the site it protects.

Practical guidance

  • Start with a strict default-src 'self'.
  • Use a nonce rather than 'unsafe-inline'.
  • Deploy in report-only mode first.
  • Add object-src 'none'.
  • Add base-uri 'none'.
  • Add frame-ancestors 'none'.
  • Self-host a font and an image to avoid an exception.
  • Check the console for a violation.
  • Remember CSP limits the damage, it does not fix the injection.

For the related guides, see csrf-explained and cors-explained. For the broader context, encryption-at-rest-vs-transit and zero-trust-for-small-teams.

Quotable summary

CSP is a response header that tells the browser which sources a page may load from, and it limits the damage of a cross-site scripting bug rather than preventing the bug. A nonce is a random value per response included in the header and on the script tag, which is the modern way to allow an inline script without allowing every inline script, and a static nonce is as weak as unsafe-inline. Report-Only mode reports a violation without blocking, which is how a policy is rolled out safely, because a policy that is too strict breaks the site and a policy with unsafe-inline provides little protection. A missing img-src origin blocks the site’s own images, which is a common and confusing failure, and self-hosting the font and the image avoids the exception entirely.

Frequently asked questions

What is Content Security Policy?
An HTTP response header that declares which sources the browser may load a script, a style, an image, a font and a connection from, which limits the impact of an injected script.
What is a nonce?
A random value generated per response and included in the CSP header and on the script tag. The browser runs a script only if its nonce matches, which allows an inline script without allowing every inline script.
What is the difference between Content-Security-Policy and Content-Security-Policy-Report-Only?
The first enforces the policy and blocks a violation. The second reports a violation without blocking, which is how a policy is tested before it is enforced.
Why does my CSP block my own images?
The img-src directive does not include the image's origin. Add the origin, or use 'self' if the image is served from the same origin.
Is unsafe-inline safe?
No. It allows any inline script, which is exactly what an injected script is, so it removes most of the protection. Use a nonce or a hash instead.
Does CSP prevent XSS?
It limits the damage rather than preventing the bug. A strict policy stops an injected script from running, but the injection itself must still be fixed by escaping the output.