Configurer l'outil Bash en sandbox

​

Démarrage

/sandbox

​

Configurer Linux et WSL2

• bubblewrap : l’outil de sandboxing sans privilèges qui applique l’isolation du système de fichiers
• socat : le relais utilisé pour acheminer le trafic réseau via le proxy sandbox

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF

sudo systemctl reload apparmor

​

Modes sandbox

• Les règles de refus explicites sont toujours respectées
• Les commandes rm ou rmdir qui ciblent /, votre répertoire personnel ou d’autres chemins système critiques déclenchent toujours une invite de permission
• Les règles ask s’appliquant au contenu comme Bash(git push *) forcent toujours une invite même pour les commandes sandboxées
• Une règle ask Bash simple, ou la forme équivalente Bash(*), est ignorée pour les commandes qui s’exécutent sandboxées ; elle s’applique toujours aux commandes qui reviennent au flux de permission régulier

​

Configurer le sandboxing

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

​

Protéger les identifiants

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

​

Comment fonctionne le sandboxing

​

Isolation du système de fichiers

• Comportement d’écriture par défaut : accès en lecture et écriture au répertoire de travail actuel et à ses sous-répertoires, plus le répertoire temporaire de session vers lequel $TMPDIR pointe
• Comportement de lecture par défaut : accès en lecture à l’ensemble de l’ordinateur, sauf certains répertoires refusés. Notez que ce comportement par défaut permet toujours de lire les fichiers d’identifiants tels que ~/.aws/credentials et ~/.ssh/. Utilisez sandbox.credentials pour bloquer les lectures de ces fichiers et désactiver les variables d’environnement secrètes, ou ajoutez les chemins à denyRead.
• Accès bloqué : impossible de modifier les fichiers en dehors du répertoire de travail actuel et du répertoire temporaire de session sans permission explicite, y compris les fichiers de configuration shell tels que ~/.bashrc et les binaires système dans /bin/
• Git worktrees : lorsque le répertoire de travail est un linked git worktree, le sandbox permet également les écritures dans le répertoire .git partagé du référentiel principal afin que les commandes telles que git commit puissent mettre à jour les références et l’index. Les écritures dans hooks/ et config à l’intérieur de ce répertoire restent refusées.
• Configurable : définissez des chemins autorisés et refusés personnalisés via les paramètres

​

Isolation réseau

• Restrictions de domaine : aucun domaine n’est pré-autorisé. La première fois qu’une commande a besoin d’un nouveau domaine, Claude Code demande une approbation. À partir de la v2.1.191, choisir Oui autorise l’hôte pour le reste de la session actuelle, de sorte que les connexions ultérieures au même hôte ne demandent plus. Pré-autorisez les domaines avec allowedDomains pour éviter l’invite entièrement.
• Verrouillage géré : si allowManagedDomainsOnly est défini dans les paramètres gérés, les domaines non autorisés sont bloqués automatiquement au lieu de demander, et seuls les allowedDomains des paramètres gérés sont honorés.
• Support de proxy personnalisé : les utilisateurs avancés peuvent implémenter des règles personnalisées sur le trafic sortant
• Couverture complète : les restrictions s’appliquent à tous les scripts, programmes et sous-processus générés par les commandes

​

Application au niveau du système d’exploitation

• macOS : utilise Seatbelt pour l’application du sandbox
• Linux : utilise bubblewrap pour l’isolation
• WSL2 : utilise bubblewrap, comme Linux

​

Comment le sandboxing se rapporte aux permissions et aux modes de permission

​

Règles de permission

• Les règles de permission contrôlent quels outils Claude Code peut utiliser et sont évaluées avant l’exécution de tout outil. Elles s’appliquent à tous les outils : Bash, Read, Edit, WebFetch, MCP et autres.
• Le sandboxing fournit une application au niveau du système d’exploitation qui restreint ce que les commandes Bash peuvent accéder au niveau du système de fichiers et du réseau. Il s’applique uniquement aux commandes Bash et à leurs processus enfants.

​

Modes de permission

​

Configurer le sandbox pour votre organisation

​

Appliquer le sandboxing avec les paramètres gérés

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

• failIfUnavailable : une dépendance manquante telle que bubblewrap sur Linux empêche Claude Code de démarrer plutôt que d’afficher un avertissement et de revenir à une exécution non sandboxée
• allowUnsandboxedCommands: false : la trappe d’échappement dangerouslyDisableSandbox est ignorée, les commandes qui échouent sous le sandbox ne peuvent donc pas être réessayées en dehors de celui-ci

​

Empêcher les développeurs d’élargir la politique

​

Configuration de proxy personnalisée

• Déchiffrer et inspecter le trafic HTTPS
• Appliquer des règles de filtrage personnalisées
• Enregistrer toutes les demandes réseau
• Intégrer avec l’infrastructure de sécurité existante

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

​

Dépannage

• Les commandes échouent avec une erreur host-not-allowed : de nombreux outils CLI doivent atteindre des hôtes spécifiques. Accorder la permission lorsque vous y êtes invité ajoute l’hôte à votre liste autorisée pour que l’outil s’exécute à l’intérieur du sandbox à l’avenir.
• jest se bloque ou échoue : watchman est incompatible avec le sandbox. Exécutez jest --no-watchman à la place.
• Les CLI basés sur Go échouent la vérification TLS sur macOS : les outils tels que gh, gcloud et terraform peuvent échouer la vérification TLS sous Seatbelt. Listez ces outils dans excludedCommands pour les exécuter en dehors du sandbox. Si vous utilisez httpProxyPort avec un proxy MITM et une CA personnalisée, définissez enableWeakerNetworkIsolation sur true à la place.
• Les commandes open, osascript ou les flux d’authentification basés sur un navigateur échouent avec l’erreur -600 sur macOS : le sandbox bloque les Apple Events par défaut. Définissez allowAppleEvents sur true dans vos paramètres utilisateur, gérés ou CLI pour les autoriser. Les paramètres du projet sont ignorés pour cette clé. L’activation supprime l’isolation de l’exécution du code, car les commandes sandboxées peuvent alors lancer d’autres applications non sandboxées sans invite utilisateur et envoyer des commandes AppleScript aux applications en cours d’exécution, sous réserve de l’invite de consentement à l’automatisation macOS (TCC). Vous pouvez également ajouter la commande à excludedCommands pour l’exécuter en dehors du sandbox.
• Les commandes docker échouent : docker est incompatible avec le sandbox. Ajoutez docker * à excludedCommands pour l’exécuter en dehors du sandbox.
• Bubblewrap échoue à démarrer à l’intérieur d’un conteneur : dans un conteneur sans privilèges, bubblewrap ne peut pas monter un système de fichiers /proc frais. Définissez enableWeakerNestedSandbox sur true pour que le sandbox interne bind-monte le /proc existant du conteneur à la place. Utilisez ce paramètre uniquement lorsque le conteneur externe fournit déjà la limite d’isolation dont vous avez besoin, car il expose les informations de processus aux commandes sandboxées qu’un montage /proc frais cacherait.
• Filtre seccomp sur Linux : le filtre seccomp est requis pour bloquer les sockets de domaine Unix. L’onglet Dependencies dans /sandbox montre s’il est disponible. S’il manque, exécutez npm install -g @anthropic-ai/sandbox-runtime pour installer l’assistant.
• --dangerously-skip-permissions échoue en tant que root : cet indicateur est bloqué lors de l’exécution en tant que root ou via sudo sur Linux et macOS, car l’accès root combiné à aucune invite de permission peut modifier n’importe quel fichier ou service sur le système. La vérification est ignorée automatiquement à l’intérieur d’un sandbox reconnu. Pour exécuter de manière autonome dans un conteneur, utilisez la configuration dev container, qui exécute Claude Code en tant qu’utilisateur non-root.

​

Limitations

​

Limitations de sécurité

• Filtrage réseau : le système de filtrage réseau fonctionne en restreignant les domaines auxquels les processus sont autorisés à se connecter. Le proxy intégré ne termine pas ou n’effectue pas l’inspection TLS sur le trafic sortant, le contenu des connexions chiffrées n’est donc pas examiné. Vous êtes responsable de vous assurer que seuls les domaines de confiance sont autorisés dans votre politique.

• Escalade de privilèges via les sockets de domaine Unix : la configuration allowUnixSockets peut accorder involontairement l’accès à des services système puissants qui pourraient entraîner des contournements du sandbox. Par exemple, autoriser l’accès à /var/run/docker.sock accorde effectivement l’accès au système hôte via le socket Docker. Considérez attentivement tous les sockets Unix que vous autorisez via le sandbox.
• Escalade de permissions du système de fichiers : les permissions d’écriture du système de fichiers trop larges peuvent permettre des attaques d’escalade de privilèges. Autoriser les écritures dans les répertoires contenant des exécutables dans $PATH, les répertoires de configuration système ou les fichiers de configuration shell utilisateur tels que .bashrc ou .zshrc peut entraîner l’exécution de code dans différents contextes de sécurité lorsque d’autres utilisateurs ou processus système accèdent à ces fichiers.
• Force du sandbox Linux : l’implémentation Linux fournit une isolation forte du système de fichiers et du réseau mais inclut un mode enableWeakerNestedSandbox qui lui permet de fonctionner à l’intérieur des environnements Docker sans espaces de noms privilégiés, ou sur les hôtes Linux où les espaces de noms utilisateur sans privilèges sont désactivés par sysctl. Cette option affaiblit considérablement la sécurité et ne doit être utilisée que lorsqu’une isolation supplémentaire est autrement appliquée.
• Apple Events sur macOS : le sandbox macOS bloque les Apple Events par défaut. Le paramètre allowAppleEvents lève cette restriction afin que les outils tels que open et osascript fonctionnent, mais il supprime l’isolation de l’exécution du code : les commandes sandboxées peuvent lancer d’autres applications sans sandbox sans invite utilisateur, et peuvent envoyer des commandes AppleScript aux applications en cours d’exécution, sous réserve de l’invite de consentement à l’automatisation macOS par application (TCC). Il n’est honoré que par les paramètres utilisateur, gérés ou CLI. Les paramètres de projet ne peuvent pas l’activer.
• Fichiers de paramètres protégés : le sandbox refuse automatiquement l’accès en écriture aux fichiers settings.json de Claude Code à chaque portée et au répertoire des paramètres gérés, une commande sandboxée ne peut donc pas modifier sa propre politique.

​

Compatibilité de plateforme et d’outil

• Support de plateforme : supporte macOS, Linux et WSL2. WSL1 et Windows natif ne sont pas supportés.
• Surcharge de performance : minimale, mais certaines opérations du système de fichiers peuvent être légèrement plus lentes.
• Compatibilité d’outil : certains outils qui nécessitent des modèles d’accès système spécifiques peuvent nécessiter des ajustements de configuration, ou peuvent avoir besoin d’être exécutés en dehors du sandbox.

​

Portée

• Outils de fichiers intégrés : Read, Edit et Write utilisent le système de permissions directement plutôt que de s’exécuter via le sandbox. Consultez permissions.
• Utilisation de l’ordinateur : lorsque Claude ouvre des applications et contrôle votre écran, il s’exécute sur votre bureau réel plutôt que dans un environnement isolé. Les invites de permission par application contrôlent chaque application. Consultez utilisation de l’ordinateur dans la CLI ou utilisation de l’ordinateur dans Desktop.
• Variables d’environnement : les commandes Bash sandboxées héritent de l’environnement du processus parent par défaut, y compris les identifiants définis là-bas. Utilisez sandbox.credentials pour supprimer les variables spécifiques pour les commandes sandboxées, ou définissez CLAUDE_CODE_SUBPROCESS_ENV_SCRUB pour supprimer les identifiants Anthropic et du fournisseur cloud de tous les sous-processus.
• Sous-agents : les sous-agents s’exécutent dans le même processus que la session parent et utilisent la même configuration de sandbox. Les commandes Bash à l’intérieur d’un sous-agent sont sandboxées lorsque le sandboxing est activé dans la session parent.

​

Voir aussi

• Environnements sandbox : comparez le sandbox intégré avec les dev containers, les conteneurs et les machines virtuelles
• Sécurité : fonctionnalités de sécurité complètes et meilleures pratiques
• Permissions : configuration des permissions et contrôle d’accès
• Paramètres : référence de configuration complète
• Référence CLI : options de ligne de commande