L’option --sandbox lance le CLI avec une isolation au niveau du système d’exploitation, en appliquant à ce niveau les périmètres d’autorisation de lecture et d’écriture actifs et, éventuellement, en restreignant le trafic réseau.
Lorsque le sandbox est actif :
- Les chemins accessibles en écriture sont dérivés des périmètres d’autorisation
Write(...) accordés, ainsi que du répertoire de l’espace de travail
- Les chemins accessibles en lecture sont dérivés des périmètres
Read(...) accordés (les chemins par défaut de la plateforme, comme /usr/bin, sont toujours lisibles)
- Les périmètres accordés en cours de session étendent dynamiquement le sandbox pour les commandes suivantes
Si la résolution du sandbox échoue (p. ex., si les outils de sandboxing ne sont pas disponibles sur la plateforme de l’utilisateur), le CLI refusera de démarrer plutôt que de s’exécuter sans sandbox. Ce comportement de sécurité, qui bloque le démarrage en cas d’échec, s’applique aussi bien si le sandbox a été activé par un Team Settings que si l’utilisateur a passé --sandbox directement, afin que l’objectif de sécurité ne soit jamais contourné silencieusement.Causes courantes d’échec de la résolution du sandbox :
- Windows : le sandboxing au niveau du système d’exploitation n’est actuellement pas pris en charge sous Windows. Les sessions sous Windows échoueront systématiquement lorsque
--sandbox est transmis ou lorsque l’application du sandbox est définie sur Required, y compris lorsque le CLI s’exécute en tant que serveur ACP dans un IDE (p. ex., Devin Desktop).
- Linux : le sandboxing nécessite que
bubblewrap (bwrap) et socat soient installés. Les sessions échouent immédiatement et affichent des instructions d’installation lorsqu’ils sont absents.
- Erreurs de périmètre d’autorisation : chemins non valides dans des périmètres d’autorisation qui ne peuvent pas être résolus.
Le filtrage réseau du sandbox est actuellement instable. Si vous avez besoin de cette fonctionnalité, veuillez contacter votre représentant de compte pour connaître les délais de stabilisation.
sandbox de votre fichier de configuration (configuration utilisateur uniquement). Lorsque --sandbox est actif et qu’un filtrage par domaine est configuré, un proxy réseau géré démarre sur le loopback, et le sandbox force tout le trafic des processus enfants à transiter par celui-ci.
| Option | Type | Par défaut | Description |
|---|
allowed_domains | string[] | [] | Motifs de domaine autorisés via le proxy. Lorsqu’elle n’est pas vide, seuls les domaines correspondants sont autorisés (mode liste d’autorisation) |
denied_domains | string[] | [] | Motifs de domaine toujours bloqués. Les règles de refus prévalent sur les règles d’autorisation |
network_mode | string | "full" | "full" autorise toutes les méthodes HTTP ; "limited" autorise uniquement GET/HEAD/OPTIONS |
| Motif | Correspond à |
|---|
example.com | Correspondance exacte uniquement |
*.example.com | Tout sous-domaine (hors domaine racine) |
**.example.com | Domaine racine et tout sous-domaine |
{
"sandbox": {
"allowed_domains": [
"github.com",
"**.npmjs.org",
"**.crates.io",
"**.pypi.org"
],
"denied_domains": ["evil.example.com"],
"network_mode": "full"
}
}
Le filtrage de domaine s’applique lorsque le sandbox est activé (--sandbox). Sans --sandbox, la section sandbox est ignorée.
git qui doivent accéder à des identifiants, ou des hooks bloqués par le sandbox. La section de configuration sandbox.excluded vous permet d’exclure du sandbox les commandes correspondantes à l’aide de la même syntaxe de règle Exec(...) que pour les permissions :
| Option | Type | Description |
|---|
excluded.allow | string[] | Les commandes correspondantes s’exécutent automatiquement en dehors du sandbox |
excluded.ask | string[] | Les commandes correspondantes s’exécutent en dehors du sandbox après approbation du prompt par l’utilisateur |
excluded.deny | string[] | Les commandes correspondantes ne sont jamais exclues — elles restent toujours dans le sandbox |
{
"sandbox": {
"excluded": {
"allow": ["Exec(git status *)"],
"ask": ["Exec(git push *)"],
"deny": ["Exec(git tag *)"]
}
}
}
Exec(git push *) l’emporte sur Exec(git *)), et lorsque la configuration utilisateur et les Team Settings correspondent toutes deux, c’est le verdict le plus restrictif qui l’emporte (deny > ask > allow). Les commandes sans règle correspondante — y compris lorsque sandbox.excluded n’est pas configuré du tout — s’exécutent toujours dans le sandbox.
- Seules les règles
Exec(...) sont prises en charge dans sandbox.excluded ; tout autre type de règle (p. ex., Read(...), Write(...)) est ignoré avec un avertissement.
- Les exclusions appliquent un principe de sécurité par défaut : si une commande ne peut pas être résolue de façon sûre (p. ex., si elle ne peut pas être analysée), elle reste dans le sandbox.
- Les exclusions s’appliquent au chemin d’exécution
exec par défaut pour chaque commande. Les commandes exécutées via un shell PTY persistant (sessions interactives, ou lorsque pty_for_noninteractive_exec est activé) restent toujours dans le sandbox.
Application au niveau Enterprise
Mode d’application du sandbox
--sandbox pour toute votre organisation :
- Facultatif (par défaut) — Les utilisateurs choisissent s’ils veulent passer
--sandbox. Aucune contrainte.
- Obligatoire — Le flag
--sandbox est activé de force pour tous les utilisateurs, même s’ils ne le passent pas sur la ligne de commande. Toutes les sessions CLI s’exécutent avec un sandbox du système de fichiers au niveau du système d’exploitation, qui applique les périmètres d’autorisation en lecture/écriture.
Un futur mode Strict pourrait verrouiller entièrement la configuration du sandbox, empêchant les utilisateurs de modifier les paramètres du sandbox.
Assurez-vous que toutes les machines cibles sont provisionnées avant de définir le mode d’application du sandbox sur Obligatoire pour toute votre organisation. Si certains utilisateurs sont sur Windows, ils ne pourront pas exécuter la CLI tant que le sandboxing au niveau du système d’exploitation ne sera pas pris en charge sur Windows ou que la politique n’aura pas été assouplie en Facultatif.
Filtrage des domaines Enterprise
- Liste d’autorisation de domaines — Lorsqu’elle est définie, seuls les domaines figurant dans cette liste sont accessibles via le proxy réseau du sandbox. Cette liste fait autorité : elle remplace entièrement toute valeur
allowed_domains configurée par l’utilisateur. Les utilisateurs ne peuvent pas ajouter d’autres domaines pour contourner les restrictions définies par les administrateurs.
- Liste de refus de domaines — Domaines qui sont toujours bloqués. Les domaines refusés au niveau Enterprise sont additifs : ils sont fusionnés avec le
denied_domains local de l’utilisateur, ce qui rend la liste combinée plus restrictive.
Interaction entre les listes de domaines Enterprise et utilisateur :
| Scénario | Config Enterprise | Config utilisateur | Résultat effectif |
|---|
| L’administrateur définit une liste d’autorisation | allowed_domains: ["github.com"] | allowed_domains: ["npmjs.org"] | Seul github.com est autorisé (Enterprise remplace la liste utilisateur) |
| L’administrateur définit une liste de refus | denied_domains: ["evil.com"] | denied_domains: ["risky.io"] | evil.com et risky.io sont tous deux bloqués (fusionnés) |
| Aucune liste d’autorisation définie par l’administrateur | allowed_domains: [] | allowed_domains: ["github.com"] | La liste d’autorisation de l’utilisateur est utilisée |
Comme le denied_domains local de l’utilisateur est conservé et fusionné de manière additive, un utilisateur peut refuser un domaine qui figure dans la liste d’autorisation Enterprise. C’est intentionnel : l’effet combiné est toujours plus restrictif, jamais moins. Si cela provoque des problèmes d’accès, l’utilisateur doit supprimer l’entrée en conflit de sa configuration locale.
Commandes exclues au niveau Enterprise
- Exclusions
allow / ask — règles Exec(...) pour les commandes qui peuvent s’exécuter hors du sandbox dans toute l’organisation, automatiquement ou après un prompt.
- Exclusion
deny — règles Exec(...) pour les commandes qui ne doivent jamais s’exécuter hors du sandbox. Un deny d’équipe l’emporte sur tout allow ou ask au niveau utilisateur pour les commandes correspondantes ; les utilisateurs ne peuvent donc pas exclure des commandes que leurs administrateurs ont verrouillées.
Les règles d’équipe et les règles utilisateur sont évaluées ensemble : la règle correspondante la plus spécifique l’emporte au sein de chaque source, et la décision la plus restrictive l’emporte entre les sources (deny > ask > allow).
Exemple : verrouiller toutes les exclusions sauf gh. Un deny générique avec une exception allow force toutes les commandes à rester dans le sandbox, sauf gh, quels que soient les réglages locaux des utilisateurs. Ces valeurs vont dans la configuration excluded-commands des paramètres d’équipe (et non dans le fichier de configuration utilisateur ; il n’y a donc pas de clé sandbox englobante) :
{
"excluded": {
"deny": ["Exec(**)"],
"allow": ["Exec(gh *)"]
}
}
Exec(gh *) l’emporte sur le caractère générique Exec(**), les commandes gh s’exécutent en dehors du sandbox, tandis que tout le reste reste à l’intérieur — et le caractère générique deny au niveau de l’équipe prévaut sur toute règle allow ou ask au niveau de l’utilisateur pour les autres commandes.
