Skip to main content
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.

​
Comment fonctionne le sandbox

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.

​
Filtrage réseau

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.
Configurez le filtrage réseau par domaine pour le sandbox dans la section 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. Syntaxe des motifs de domaine : Exemple :
Le filtrage de domaine s’applique lorsque le sandbox est activé (--sandbox). Sans --sandbox, la section sandbox est ignorée.

​
Commandes exclues

Il arrive qu’une commande spécifique doive s’exécuter en dehors du sandbox — par exemple des commandes 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 : Exemple :
Résolution des règles : pour chaque commande, la règle correspondante la plus spécifique l’emporte pour une même source (p. ex., 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

Les administrateurs Enterprise peuvent contrôler le comportement du sandbox pour toute leur organisation dans Team Settings.

​
Mode d’application du sandbox

Définissez le niveau d’application du flag --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

Les administrateurs peuvent également configurer des listes d’autorisation et de refus de domaines à l’échelle de l’organisation :
  • 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 :
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

Les administrateurs peuvent également définir, dans les paramètres de l’équipe, des règles de commandes exclues à l’échelle de l’organisation :
  • 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) :
Parce que la règle plus spécifique 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.

​
Pour aller plus loin