Le sandboxing de Claude Code

Problème : Un agent IA avec un accès libre à ton disque et ton réseau, c'est un risque que tu ne peux pas ignorer. Chaque npm install télécharge du code écrit par des inconnus. Chaque script de build s'exécute avec tes droits utilisateur complets. Chaque injection de prompt qui passe obtient le même niveau d'accès que toi. Une mauvaise dépendance, sans aucune barrière en place, peut lire tes clés SSH, envoyer tes variables d'environnement ailleurs, ou modifier discrètement tes fichiers de configuration shell.

Le sandbox de Claude Code ferme cette porte. Il applique les restrictions de système de fichiers et de réseau directement au niveau du noyau, donc les règles ne dépendent plus de la confiance ni de la formulation d'un prompt.

Mise en place rapide : Une commande active le sandboxing maintenant même :

> /sandbox

Un menu apparaît pour choisir le mode sandbox. Sur macOS, la fonctionnalité est déjà disponible. Pour Linux ou WSL2, deux paquets doivent d'abord être installés, bubblewrap et socat (instructions ci-dessous).

Pourquoi les invites de permission ne suffisent pas seules

Tu passes du temps avec Claude Code et le schéma est familier. Claude veut exécuter une commande. Approuver. Claude veut écrire un fichier. Approuver. Claude veut lancer les tests. Approuver. Après trente clics, tu valides les actions sans lire une seule invite.

C'est la fatigue des approbations. C'est un problème de sécurité qui se déguise en fonctionnalité de sécurité.

Plus d'invites signifie moins d'attention sur chacune. Les recherches sur l'UX sécurité arrivent toujours à la même conclusion : les boîtes de dialogue répétitives apprennent les gens à cliquer sans réfléchir. Tu perds sur les deux tableaux. Le flux s'interrompt quand même, et la protection se dégrade quand même.

Le sandboxing renverse ce modèle. Plutôt que de demander "est-ce que cette action peut se produire ?" pour chaque étape, tu configures les clôtures une fois pour toutes. Voici où les lectures peuvent avoir lieu. Voici où les écritures peuvent avoir lieu. Voici ce que le réseau peut atteindre. À l'intérieur de ces clôtures, rien ne demande de permission. À l'extérieur, c'est l'OS qui bloque l'action, pas une boîte de dialogue.

Le résultat : moins d'interruptions, des défenses plus solides, et un agent libre de travailler de façon autonome dans des limites connues et sûres.

Comment fonctionne le sandboxing de Claude Code

Deux couches d'isolation fonctionnent en parallèle. Les deux comptent. Enlève l'une d'elles et l'autre laisse des failles béantes.

Isolation du système de fichiers

L'outil bash sandboxé limite l'accès aux fichiers à une courte liste de répertoires :

Les écritures restent dans le répertoire de travail et tout ce qui se trouve en dessous
Les lectures couvrent tout le système, sauf les chemins que tu as marqués comme refusés
Les modifications hors de l'arborescence échouent sauf si tu accordes explicitement la permission
Les chemins personnalisés ouvrent ou ferment des répertoires supplémentaires via les paramètres du sandbox

En pratique, Claude lit les fichiers du projet et modifie le code dans ton dépôt, mais ~/.bashrc, /usr/local/bin, et tout ce qui se trouve dans ~/.ssh restent hors de portée. Un paquet npm malveillant qui essaie d'écrire au-delà de ces limites est bloqué par l'OS lui-même.

Isolation réseau

Le trafic sortant est routé via un serveur proxy qui vit en dehors du sandbox :

Une liste blanche de domaines limite les hôtes que tout processus peut atteindre
Les domaines inconnus déclenchent une invite de permission, donc chaque nouvel hôte apparaît devant toi
Les limites héritées voyagent avec chaque processus enfant, donc un shell créé par un script de build ne peut pas contourner les règles
Les proxies personnalisés permettent aux entreprises d'acheminer le trafic du sandbox dans leur propre pipeline d'inspection

Les barrières du système de fichiers seules laissent une faille. Un agent compromis pourrait quand même envoyer du code source vers un hôte contrôlé par l'attaquant. Les barrières réseau seules laissent la faille opposée. Les deux couches doivent fonctionner ensemble. La conception repose sur ça.

Application au niveau du noyau

Le sandbox ne dépend pas de vérifications au niveau de l'application. Un exploit habile peut toujours les contourner. Ce qui fait le travail, c'est un ensemble de primitives de sécurité du noyau :

macOS : Seatbelt, le même framework qu'Apple utilise pour isoler les apps de l'App Store
Linux : bubblewrap (bwrap), le petit outil sandbox non privilégié sur lequel est construit Flatpak
WSL2 : bubblewrap aussi, identique à Linux natif

WSL1 n'est pas supporté. bubblewrap a besoin de fonctionnalités que le noyau n'expose que sous WSL2, à savoir les espaces de noms utilisateur et de montage. Un build Windows natif est prévu mais pas encore disponible.

Chaque processus enfant créé par une commande sandboxée hérite des mêmes limites. Lance npm install en mode sandbox, et tout hook postinstall se retrouve aussi dans la boîte.

Prérequis et installation

macOS

Rien à installer en plus. Le sandboxing fonctionne directement avec le framework Seatbelt déjà dans l'OS. Tape /sandbox et choisis un mode.

Linux et WSL2

Tu as besoin de deux paquets. bubblewrap fait l'isolation du système de fichiers et socat gère la plomberie du proxy réseau :

Ubuntu/Debian :

sudo apt-get install bubblewrap socat

Fedora :

sudo dnf install bubblewrap socat

Une fois installés, tape /sandbox dans Claude Code. Si une dépendance manque encore, le menu t'affiche les instructions d'installation pour ta plateforme.

Modes sandbox : auto-autoriser vs permissions normales

Deux modes existent. Les barrières du système de fichiers et du réseau sont identiques dans les deux. Ce qui change, c'est si une commande sandboxée a encore besoin de ton clic pour s'exécuter.

Mode auto-autoriser

Une commande bash essaie de s'exécuter dans le sandbox, et si ça convient, rien ne te demande d'abord. Si cette même commande a besoin d'un hôte qui n'est pas sur ta liste autorisée, le flux de permission habituel se déclenche. Toute règle d'approbation ou de refus déjà configurée s'applique quand même.

La plupart des développeurs veulent ce mode. L'agent a un maximum de liberté dans les clôtures, et les invites ne reviennent que quand quelque chose essaie de franchir une clôture.

Un détail vaut la peine d'être connu. L'auto-autorisation fonctionne indépendamment du mode de permission. Même avec "accepter les modifications" désactivé, une commande bash sandboxée s'exécute sans invite quand l'auto-autorisation est activée. Les modifications de fichiers via l'outil Edit continuent d'obéir à tes règles de permission normales. Seul le bash dans le sandbox passe par ce chemin.

Mode permissions normales

Chaque commande bash, sandboxée ou non, passe encore par la boîte de dialogue de permission normale. Les barrières restent en place, et chaque commande te demande aussi d'abord.

Choisis ça quand tu veux la protection du sandbox sans abandonner la revue commande par commande. Un bon choix pour les environnements stricts, ou pour les premiers jours de configuration d'un nouveau sandbox.

Configurer ton sandbox

Le comportement du sandbox se règle dans ton settings.json. Un exemple fonctionnel ressemble à ça :

{
  "sandbox": {
    "mode": "auto-allow",
    "allowedDomains": ["registry.npmjs.org", "api.github.com", "pypi.org"],
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

Paramètres clés

mode : Mets-le à "auto-allow" ou "regular". Ce flag décide si les commandes sandboxées s'exécutent seules ou attendent un clic.

allowedDomains : Les hôtes que bash peut atteindre sans demander. Les nouveaux domaines que tu touches affichent une invite, et accepter écrit le domaine dans cette liste pour la prochaine fois.

allowUnixSockets : Contrôle l'accès aux sockets. Attention ici. Autoriser /var/run/docker.sock donne en pratique un accès à l'hôte via l'API Docker, ce qui contourne les barrières du sandbox.

allowUnsandboxedCommands : Par défaut à true. Quand une règle sandbox bloque une commande, Claude peut relancer cette commande hors sandbox après confirmation. Passe à false pour supprimer ce chemin de réessai.

excludedCommands : Une liste de commandes qui contournent toujours le sandbox. Utile pour les outils qui refusent simplement de coopérer, comme docker.

enableWeakerNestedSandbox : Un réglage Linux uniquement pour les configurations Docker non privilégiées. Il affaiblit les barrières, donc ne l'utilise que quand le conteneur externe fait sa propre isolation.

Comment le sandboxing s'articule avec les permissions

Les permissions et le sandbox sont deux couches de sécurité indépendantes qui se renforcent mutuellement :

Les permissions décident quels outils sont accessibles à Claude Code. Elles s'exécutent avant tout appel d'outil, et elles s'appliquent à tous les outils : Bash, Read, Edit, WebFetch, les outils MCP, tout l'ensemble.

Le sandboxing est appliqué par l'OS, et il façonne uniquement ce qu'une commande Bash (ou ses sous-processus) peut faire avec le système de fichiers et le réseau.

Pense défense en profondeur. Première porte : est-ce que cet outil est même autorisé ? Deuxième porte : une fois qu'il s'exécute, jusqu'où peut-il aller ?

Avantages en termes de sécurité

Protection contre l'injection de prompt

L'injection de prompt est le plus grand risque actif pour un agent IA. Un attaquant cache des instructions dans un fichier, un README, ou une page web. Claude les lit comme si tu les avais écrites, et commence à exécuter des commandes d'attaquant.

Avec le sandbox activé, même une injection réussie se heurte à des murs solides :

Protection du système de fichiers :

Les fichiers rc shell comme ~/.bashrc et ~/.zshrc sont hors limites
Les binaires système sous /bin/ ou /usr/local/bin/ ne peuvent pas être touchés
Tout chemin marqué refusé dans tes règles de permission est illisible

Protection réseau :

Les serveurs contrôlés par les attaquants ne peuvent pas être utilisés pour l'exfiltration de données
Les scripts malveillants provenant de domaines inconnus ne peuvent pas être téléchargés
Les appels API vers des services que tu n'as pas approuvés ne passeront pas
Tout domaine absent de la liste autorisée est inaccessible

Une surface d'attaque réduite

Au-delà de l'injection, le sandbox réduit aussi les dégâts des risques ordinaires :

Mauvaises dépendances : tout paquet npm, pip ou autre bibliothèque qui cache de la logique malveillante dans les scripts postinstall
Outils de build cassés : utilitaires de build transportant leurs propres vulnérabilités
Ingénierie sociale : commandes dangereuses qu'un utilisateur a été trompé pour exécuter
Attaques de la chaîne d'approvisionnement : paquets en amont falsifiés, transformant le moment de l'installation en injection de code

Limites à connaître

Aucun sandbox n'est parfait. Être clair sur les lacunes des murs, c'est comme tu choisis un modèle de menace réaliste.

Domain fronting

Le filtre réseau sélectionne les domaines, mais ne fait pas d'inspection approfondie des paquets. Le domain fronting, où le trafic semble se diriger vers un hôte mais atterrit en fait chez un autre, peut contourner le filtre de domaine dans certains cas.

Escalade via Unix sockets

allowUnixSockets peut silencieusement accorder un accès puissant. Autorise /var/run/docker.sock et le processus sandboxé dispose maintenant de l'API Docker complète, ce qui signifie en pratique un accès à l'hôte.

Escalade des permissions du système de fichiers

Des autorisations d'écriture trop larges créent des chemins d'escalade. Laisse le sandbox écrire dans un dossier avec des binaires dans $PATH, des répertoires de configuration système, ou des fichiers rc shell utilisateur, et du code peut finir par s'exécuter dans un contexte de sécurité différent.

Conseils pratiques et compatibilité

Docker ne coopère pas

Les commandes Docker ne fonctionneront pas sous le sandbox. Elles ont besoin d'un accès direct au démon Docker. Mets docker dans excludedCommands pour qu'il s'exécute toujours en dehors.

Watchman non plus

Le surveillant de fichiers watchman de Facebook ne coopère pas avec un processus sandboxé. Tu lances Jest ? Ajoute le flag --no-watchman.

La sortie de secours

De temps en temps, une commande sandboxée échoue à cause des barrières elles-mêmes. Claude peut regarder l'échec et proposer de réessayer avec dangerouslyDisableSandbox. Ce réessai s'exécute hors du sandbox, et il attend quand même ton approbation via le flux de permission habituel.

Configuration de proxy personnalisé pour les entreprises

Les organisations ayant des besoins de sécurité réseau plus poussés peuvent acheminer le trafic du sandbox via leur propre proxy pour l'inspection, la journalisation, et l'intégration avec le reste de leur infrastructure de sécurité.

L'avantage, c'est la possibilité de :

Terminer et inspecter le trafic HTTPS
Appliquer des règles qui vont plus loin qu'un simple blocage de domaine
Écrire chaque requête sortante dans un journal d'audit
Connecter le sandbox à un SIEM ou une stack sécurité existante
Diffuser des règles à l'échelle de l'organisation via la portée des paramètres gérés

Runtime sandbox open source

Le runtime est livré comme son propre paquet npm, open source. Intègre-le dans n'importe quel projet agent que tu veux. Pas besoin de Claude Code :

npx @anthropic-ai/sandbox-runtime <command-to-sandbox>

Le code source est hébergé sur github.com/anthropic-experimental/sandbox-runtime.

Configurer ton premier sandbox

Un chemin pratique de zéro à une configuration fonctionnelle :

Dépendances d'abord (Linux/WSL2 uniquement) : sudo apt-get install bubblewrap socat
Tape /sandbox dans Claude Code et choisis un mode dans le menu
Choisis auto-autoriser si tu veux l'équilibre idéal entre sécurité et vitesse
Utilise Claude normalement et approuve les nouveaux domaines que les invites te demandent
Revois la configuration après une ou deux sessions, et vérifie la liste de domaines
Taille ce que tu n'utilises pas en retirant les domaines obsolètes

Commence serré. N'ouvre les choses que quand le besoin est réel. Assouplir une règle est moins cher que nettoyer après une règle qui n'aurait jamais dû exister.

Le sandboxing de Claude Code

On this page