# sandbox (/fr/docs/web-security/policies/content-security-policy/directives/sandbox)



La directive `sandbox` applique à un document le même ensemble de restrictions
que l'[attribut `sandbox` d'une `<iframe>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe#sandbox)
applique à une page en frame, mais elle le fait depuis un header de réponse, donc
elle couvre aussi le document de premier niveau. Une fois active, le navigateur
verrouille les scripts, les formulaires, les popups, les plugins et la
navigation, puis vous réactivez des fonctionnalités avec des tokens `allow-*`.

Contrairement à la plupart des directives CSP, `sandbox` ne prend pas de liste de
sources. Elle prend des tokens de sandbox, donc les mots-clés habituels comme
`'self'` et les sources d'hôte ne s'appliquent pas.

Mettre en sandbox une page qui doit exécuter des scripts et soumettre des
formulaires, mais rien d'autre :

```http
Content-Security-Policy: sandbox allow-scripts allow-forms
```

La valeur vide, le nom de la directive sans tokens, est la forme maximale :
toutes les restrictions s'appliquent.

## Chaîne de repli [#chaîne-de-repli]

`sandbox` n'a pas de repli. [`default-src`](/fr/docs/web-security/policies/content-security-policy/directives/default-src)
ne la couvre pas, donc les restrictions n'existent que sur le document où vous
définissez la directive.

## Valeurs [#valeurs]

La valeur est une liste de tokens de sandbox séparés par des espaces. Une valeur
vide, le nom de la directive sans rien après, applique la sandbox maximale : le
document reçoit une origine opaque unique, ne peut pas exécuter de scripts, ne
peut pas soumettre de formulaires, ne peut pas ouvrir de popups et ne peut pas
faire naviguer son contexte de navigation de premier niveau. Chaque token relâche
une restriction.

| Token                                      | Statut | Autorise                                                                                        |
| ------------------------------------------ | ------ | ----------------------------------------------------------------------------------------------- |
| `allow-downloads`                          | ✅ Bon  | Déclencher des téléchargements.                                                                 |
| `allow-forms`                              | ✅ Bon  | Soumettre des formulaires.                                                                      |
| `allow-modals`                             | ✅ Bon  | Afficher des dialogues modaux (`alert`, `confirm`, `prompt`).                                   |
| `allow-orientation-lock`                   | ✅ Bon  | Verrouiller l'orientation de l'écran.                                                           |
| `allow-pointer-lock`                       | ✅ Bon  | Utiliser l'API Pointer Lock.                                                                    |
| `allow-popups`                             | ✅ Bon  | Ouvrir de nouvelles fenêtres et de nouveaux onglets (`window.open`, `target="_blank"`).         |
| `allow-popups-to-escape-sandbox`           | ✅ Bon  | Laisser les popups ouvertes s'exécuter sans hériter de la sandbox.                              |
| `allow-presentation`                       | ✅ Bon  | Démarrer une session de présentation.                                                           |
| `allow-same-origin`                        | ✅ Bon  | Conserver la véritable origine du document au lieu d'une origine opaque.                        |
| `allow-scripts`                            | ✅ Bon  | Exécuter des scripts.                                                                           |
| `allow-storage-access-by-user-activation`  | ✅ Bon  | Demander l'accès au stockage via l'API Storage Access après un geste utilisateur.               |
| `allow-top-navigation`                     | ✅ Bon  | Faire naviguer le contexte de navigation de premier niveau.                                     |
| `allow-top-navigation-by-user-activation`  | ✅ Bon  | Navigation de premier niveau uniquement si déclenchée par un geste utilisateur.                 |
| `allow-top-navigation-to-custom-protocols` | ✅ Bon  | Navigation de premier niveau vers des protocoles non HTTP délégués au navigateur ou au système. |

Chaque token est sûr isolément, mais une combinaison ne l'est pas : accorder
`allow-scripts` et `allow-same-origin` ensemble laisse le document sandboxé
exécuter des scripts dans sa véritable origine, ce qui signifie qu'un script du
document peut retirer l'attribut sandbox et annuler entièrement la restriction.

## Exemples [#exemples]

Verrouiller complètement un document (ni scripts, ni formulaires, ni popups, ni
navigation) :

```http
Content-Security-Policy: sandbox
```

## Notes de sécurité [#notes-de-sécurité]

`sandbox` ne fonctionne que comme header de réponse HTTP. Une politique en
`<meta http-equiv>` ne peut pas la porter, le navigateur ignore `sandbox` dans
une CSP livrée par meta. C'est la même restriction que pour
[`frame-ancestors`](/fr/docs/web-security/policies/content-security-policy/directives/frame-ancestors),
[`report-uri`](/fr/docs/web-security/policies/content-security-policy/directives/report-uri)
et [`report-to`](/fr/docs/web-security/policies/content-security-policy/directives/report-to).
La directive est aussi ignorée dans une politique report-only ; voir
[Reporting](#reporting).

Ce contre quoi elle protège : `sandbox` confine du contenu non fiable ou
partiellement fiable en le privant des capacités qui transforment une charge
injectée en dégâts réels. Un document servi avec un `sandbox` vide ne peut pas
exécuter de script, soumettre un formulaire, ouvrir une fenêtre ni naviguer
ailleurs, donc même si le balisage est compromis, le rayon d'impact reste petit.
Elle est surtout utile pour servir du HTML généré par les utilisateurs, des
intégrations tierces, ou tout document que vous ne contrôlez pas entièrement.

## Contournements et risques connus [#contournements-et-risques-connus]

L'erreur courante est de rajouter tant de tokens que la sandbox ne restreint plus
rien de significatif. En particulier, associer `allow-scripts` à
`allow-same-origin` laisse le document supprimer sa propre sandbox par script,
donc évitez cette combinaison sauf si vous en avez réellement besoin et que vous
faites confiance au contenu.

Parce que `sandbox` est réservée au header, vous ne pouvez pas l'appliquer via
une balise meta, et vous ne pouvez pas la relâcher par élément comme l'attribut
`<iframe sandbox>` peut être ajusté par frame.

Une sandbox trop stricte casse des fonctionnalités légitimes (les formulaires ne
se soumettent plus, les popups ne s'ouvrent plus), et une sandbox trop lâche
protège peu. Testez le document avec l'ensemble exact de tokens que vous comptez
déployer, car les restrictions s'appliquent immédiatement et silencieusement.

## Recommandation [#recommandation]

```http
Content-Security-Policy: sandbox
```

Partez de la valeur vide, la sandbox maximale, et ajoutez les tokens un par un,
uniquement pour les capacités dont le document a réellement besoin. N'accordez
jamais `allow-scripts` avec `allow-same-origin` sur du contenu que vous ne
contrôlez pas entièrement ; MDN documente cette combinaison comme une échappée de
la sandbox.

## Reporting [#reporting]

Le navigateur ignore `sandbox` dans un header
[`Content-Security-Policy-Report-Only`](/fr/docs/web-security/policies/content-security-policy/report-only),
donc il n'y a pas de phase report-only pour cette directive ; testez l'ensemble
exact de tokens avec le header en mode enforcement. Les violations du reste de
votre politique arrivent toujours comme
[reports `csp-violation`](/fr/docs/web-security/reporting-api/reports/csp-violation).

## Prise en charge par les navigateurs [#prise-en-charge-par-les-navigateurs]

`sandbox` fait partie de CSP niveau 2 et niveau 3 et est largement prise en
charge par les navigateurs actuels, à l'image de l'attribut `<iframe sandbox>` de
longue date.

## FAQ [#faq]

### Que fait la directive sandbox de CSP ? [#que-fait-la-directive-sandbox-de-csp-]

`sandbox` applique à un document les restrictions de type sandbox d'une iframe
depuis un header de réponse, elle couvre donc aussi le document de premier niveau.
Quand elle est active, le navigateur verrouille les scripts, les formulaires, les
popups, les plugins et la navigation, et vous réactivez des fonctionnalités avec
les tokens `allow-*`. Une valeur vide applique la sandbox maximale.

### En quoi la sandbox CSP diffère-t-elle de l'attribut sandbox des iframes ? [#en-quoi-la-sandbox-csp-diffère-t-elle-de-lattribut-sandbox-des-iframes-]

La directive `sandbox` applique les mêmes restrictions, mais elle ne fonctionne
que comme header de réponse HTTP, elle peut donc mettre en sandbox le document de
premier niveau, pas seulement une page en frame. Une politique en
`<meta http-equiv>` ne peut pas la livrer, et vous ne pouvez pas la relâcher par
élément comme le permet l'attribut `<iframe sandbox>`.

## Voir aussi [#voir-aussi]

* [default-src](/fr/docs/web-security/policies/content-security-policy/directives/default-src)
* [frame-ancestors](/fr/docs/web-security/policies/content-security-policy/directives/frame-ancestors)
* [frame-src](/fr/docs/web-security/policies/content-security-policy/directives/frame-src)
* [Header Content-Security-Policy-Report-Only](/fr/docs/web-security/policies/content-security-policy/report-only)

## Sources [#sources]

* [MDN, CSP sandbox](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/sandbox)
* [W3C, Content Security Policy Level 3](https://www.w3.org/TR/CSP3/)