sandbox
The CSP sandbox directive applies iframe-style restrictions to a whole page. Every allow-* token, including allow-popups-to-escape-sandbox, with examples.
Last update:
The sandbox directive applies the same set of restrictions to a document that
the sandbox attribute on an <iframe>
applies to a framed page, but it does it from a response header, so it covers the
top-level document too. With it active the browser locks down scripts, forms,
popups, plugins, and navigation, then you opt features back in with allow-*
tokens.
Unlike most CSP directives, sandbox does not take a source list. It takes
sandbox tokens, so the usual keywords like 'self' and host sources do not apply.
Sandbox a page that needs to run scripts and submit forms but nothing else:
Content-Security-Policy: sandbox allow-scripts allow-formsThe empty value, the directive name with no tokens, is the maximal form: every restriction applies.
Fallback chain
sandbox has no fallback. default-src
does not cover it, so the restrictions exist only on the document where you set
the directive.
Values
The value is a space-separated list of sandbox tokens. An empty value, the directive name with nothing after it, applies the maximal sandbox: the document gets a unique opaque origin, cannot run scripts, cannot submit forms, cannot open popups, and cannot navigate its top-level browsing context. Each token relaxes one restriction.
| Token | Status | Allows |
|---|---|---|
allow-downloads | ✅ Good | Triggering downloads. |
allow-forms | ✅ Good | Submitting forms. |
allow-modals | ✅ Good | Showing modal dialogs (alert, confirm, prompt). |
allow-orientation-lock | ✅ Good | Locking screen orientation. |
allow-pointer-lock | ✅ Good | Using the Pointer Lock API. |
allow-popups | ✅ Good | Opening new windows and tabs (window.open, target="_blank"). |
allow-popups-to-escape-sandbox | ✅ Good | Letting opened popups run without inheriting the sandbox. |
allow-presentation | ✅ Good | Starting a presentation session. |
allow-same-origin | ✅ Good | Keeping the document's real origin instead of an opaque one. |
allow-same-site-none-cookies | 🧪 Experimental | Chromium only, behind a flag: sending the site's own SameSite=None cookies from a sandboxed document. |
allow-scripts | ✅ Good | Running scripts. |
allow-storage-access-by-user-activation | ✅ Good | Requesting storage access through the Storage Access API after a user gesture. |
allow-top-navigation | ✅ Good | Navigating the top-level browsing context. |
allow-top-navigation-by-user-activation | ✅ Good | Top-level navigation only when triggered by a user gesture. |
allow-top-navigation-to-custom-protocols | ✅ Good | Top-level navigation to non-HTTP protocols the browser or the OS hands off. |
Each token is safe on its own, but one combination is not: granting
allow-scripts and allow-same-origin together lets the sandboxed document run
scripts in its own real origin. An injected script then has the origin's cookies
and storage and can script any unsandboxed same-origin page it opens or frames,
so the sandbox no longer contains anything. In an <iframe sandbox> the same
pair is worse still: the framed page can reach into its same-origin parent and
remove the sandbox attribute itself.
Examples
Lock a document down completely (no scripts, forms, popups, or navigation):
Content-Security-Policy: sandboxSecurity notes
sandbox works only as an HTTP response header. A <meta http-equiv> policy
cannot deliver it: Chrome logs
The Content Security Policy directive 'sandbox' is ignored when delivered via a <meta> element.
The specification applies the same rule to
frame-ancestors
and report-uri,
but not to report-to,
which a meta policy may carry. The directive is also ignored in a report-only
policy; see Reporting. An unknown token is skipped with
Error while parsing the 'sandbox' Content Security Policy directive: 'allow-foo' is an invalid sandbox flag.
while the rest of the directive still applies.
What it protects against: sandbox contains untrusted or partially trusted
content by stripping it of the capabilities that turn an injected payload into
real damage. A document served with an empty sandbox cannot run script, submit a
form, open a window, or navigate away, so even if markup is compromised the blast
radius stays small. It is most useful for serving user-generated HTML,
third-party embeds, or any document you do not fully control.
Known bypasses and risks
The common mistake is adding back so many tokens that the sandbox no longer
restricts anything meaningful. In particular, pairing allow-scripts with
allow-same-origin lets the document script away its own sandbox, so avoid that
combination unless you genuinely need it and trust the content.
Because sandbox is header-only, you cannot apply it through a meta tag, and you
cannot relax it per element the way the <iframe sandbox> attribute can be tuned
per frame.
A sandbox that is too tight breaks legitimate functionality (forms stop
submitting, popups stop opening), and a sandbox that is too loose provides little
protection. Test the document with the exact token set you intend to ship: the
restrictions apply immediately and send no CSP report. The only trace is a
console message such as
Blocked script execution in '<url>' because the document's frame is sandboxed and the 'allow-scripts' permission is not set.
Recommendation
Content-Security-Policy: sandboxStart from the empty value, the maximal sandbox, and add tokens one at a time,
only for the capabilities the document actually requires. Never grant
allow-scripts together with allow-same-origin on content you do not fully
control; MDN documents that combination as an escape from the sandbox.
Reporting
The browser ignores sandbox in a
Content-Security-Policy-Report-Only
header, so there is no report-only staging for this directive; test the exact
token set with the enforcing header. Violations of the rest of your policy still
arrive as csp-violation reports.
Browser support
sandbox is part of CSP Level 2 and Level 3 and is widely supported across
current browsers, mirroring the long-standing <iframe sandbox> attribute.
FAQ
What does the CSP sandbox directive do?
sandbox applies iframe-style sandbox restrictions to a document from a response header, so it covers the top-level document too. With it active the browser locks down scripts, forms, popups, plugins, and navigation, and you opt features back in with allow-* tokens. An empty value applies the maximal sandbox.
How is CSP sandbox different from the iframe sandbox attribute?
The sandbox directive applies the same restrictions, but it works only as an HTTP response header, so it can sandbox the top-level document, not just a framed page. A <meta http-equiv> policy cannot deliver it, and you cannot relax it per element the way the <iframe sandbox> attribute can.
See also
Sources
- MDN, CSP sandbox
- W3C, Content Security Policy Level 3
- W3C CSP editor's draft, the meta element
- Chromium, report-only and meta restrictions (content_security_policy.cc)
- Chromium, sandbox token parser (web_sandbox_flags.cc)
- Chromium, sandboxed script console message (local_dom_window.cc)
- Chrome Platform Status, SameSite=None cookies in sandboxed contexts
base-uri
base-uri stops an injected <base> tag from rewriting every relative script URL. Why default-src does not cover it, and the value strict CSPs use.
plugin-types
The CSP plugin-types directive once limited the MIME types of embedded plugins. It is deprecated and removed. Use object-src none instead.