sandbox directive, apply sandbox restrictions in CSP

The CSP sandbox directive applies sandbox restrictions to a document and accepts allow-* tokens rather than a source list.

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-forms

The 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-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, which means a script in the document can reach out and remove the sandbox attribute, defeating the restriction entirely.

Examples

Lock a document down completely (no scripts, forms, popups, or navigation):

Content-Security-Policy: sandbox

Security notes

sandbox works only as an HTTP response header. A <meta http-equiv> policy cannot deliver it, the browser ignores sandbox in a meta-delivered CSP. This is the same restriction that applies to frame-ancestors, report-uri, and report-to. The directive is also ignored in a report-only policy; see Reporting.

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, since the restrictions apply immediately and silently.

Recommendation

Content-Security-Policy: sandbox

Start 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.

sandbox