Directive: sandbox

Overview

The sandbox directive enables a sandbox for the requested resource similar to the <iframe sandbox> attribute.

It applies restrictions to a page's actions including preventing popups, preventing the execution of plugins and scripts, and enforcing a same-origin policy.

Required reading:

• Can I use sandbox?
• MDN Web Docs reference

Usage examples

The HTML Living Specification is always in a state of flux (by design). Because of this, this library supports the <iframe sandbox> values that are documented in the MDN reference.

allow-downloads

Allows downloading files through an <a> or <area> element with the download attribute, as well as through the navigation that leads to a download of a file. This works regardless of whether the user clicked on the link, or JS code initiated it without user interaction.

allow-forms

Allows the page to submit forms. If this keyword is not used, form will be displayed as normal, but submitting it will not trigger input validation, sending data to a web server or closing a dialog.

allow-modals

Allows the page to open modal windows by Window.alert(), Window.confirm(), Window.print() and Window.prompt(), while opening a <dialog> is allowed regardless of this keyword. It also allows the page to receive BeforeUnloadEvent event.

allow-orientation-lock

Lets the resource lock the screen orientation.

allow-pointer-lock

Allows the page to use the Pointer Lock API.

allow-popups

Allows popups (like from Window.open(), target="_blank", Window.showModalDialog()). If this keyword is not used, that functionality will silently fail.

allow-popups-to-escape-sandbox

Allows a sandboxed document to open a new browsing context without forcing the sandboxing flags upon it. This will allow, for example, a third-party advertisement to be safely sandboxed without forcing the same restrictions upon the page the ad links to. If this flag is not included, a redirected page, popup window, or new tab will be subject to the same sandbox restrictions as the originating <iframe>.

allow-presentation

Allows embedders to have control over whether an iframe can start a presentation session.

allow-same-origin

If this token is not used, the resource is treated as being from a special origin that always fails the same-origin policy (potentially preventing access to data storage/cookies and some JavaScript APIs).

allow-scripts

Allows the page to run scripts (but not create pop-up windows). If this keyword is not used, this operation is not allowed.

allow-top-navigation

Lets the resource navigate the top-level browsing context (the one named _top).

allow-top-navigation-by-user-activation

Lets the resource navigate the top-level browsing context, but only if initiated by a user gesture.

allow-top-navigation-to-custom-protocols

Allows navigations to non-http protocols built into browser or registered by a website. This feature is also activated by allow-popups or allow-top-navigation keyword.

Fallbacks

❌ sandbox does not fallback to default-src.

Possible errors

• CSP-0700 — [ERROR] directive %s has an invalid value %s

For developers

ABNF (CSP3)

directive-name  = "sandbox"
directive-value = "" / token *( required-ascii-whitespace token )

See RFC 9110 § 5.6.2

Type

• token in RFC 9110 § 5.6.2

References

• CSP Level 2 reference
• CSP Level 3 reference
• MDN Web Docs reference
• Can I use sandbox?