sandbox-runtime — Un outil de sandboxing léger pour appliquer des restrictions de système de fichiers et de réseau à des processus arbitraires au niveau du système d'exploitation, sans nécessiter de conteneur. | Kitploit

Anthropic Sandbox Runtime (srt)

Un outil de sandboxing léger pour imposer des restrictions sur le système de fichiers et le réseau à des processus arbitraires au niveau du système d'exploitation, sans nécessiter de conteneur.

srt utilise les primitives de sandboxing natives de l'OS (sandbox-exec sur macOS, bubblewrap sur Linux) et un filtrage réseau basé sur un proxy. Il peut être utilisé pour sandboxer le comportement d'agents, de serveurs MCP locaux, de commandes bash et de processus arbitraires.

Aperçu de recherche bêta

Le Sandbox Runtime est un aperçu de recherche développé pour Claude Code afin de permettre des agents IA plus sûrs. Il est mis à disposition sous forme d'aperçu open source précoce pour aider l'écosystème au sens large à construire des systèmes agentiques plus sécurisés. Comme il s'agit d'un aperçu de recherche précoce, les API et les formats de configuration peuvent évoluer. Nous accueillons favorablement les retours et les contributions pour rendre les agents IA plus sûrs par défaut !

Installation```bash

npm install -g @anthropic-ai/sandbox-runtime

## Utilisation de base```bash
# Network restrictions
$ srt "curl anthropic.com"
Running: curl anthropic.com
<html>...</html>  # Request succeeds

$ srt "curl example.com"
Running: curl example.com
Connection blocked by network allowlist  # Request blocked

# Filesystem restrictions
$ srt "cat README.md"
Running: cat README.md
# Anthropic Sandb...  # Current directory access allowed

$ srt "cat ~/.ssh/id_rsa"
Running: cat ~/.ssh/id_rsa
cat: /Users/ollie/.ssh/id_rsa: Operation not permitted  # Specific file blocked

Les utilisateurs doivent être conscients des risques potentiels liés à l'autorisation de domaines larges comme `github.com` qui peuvent permettre l'exfiltration de données. De plus, dans certains cas, il peut être possible de contourner le filtrage réseau via le [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting).

**Avec sandboxing** (`.mcp.json`) :```json
{
  "mcpServers": {
    "filesystem": {
      "command": "srt",
      "args": ["npx", "-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

Maintenant, le serveur MCP sera bloqué pour écrire dans le chemin refusé :```
> Write a file to ~/sensitive-folder
✗ Error: EPERM: operation not permitted, open '/Users/ollie/sensitive-folder/test.txt'

## Utilisation

### En tant qu'outil CLI

La commande `srt` (Anthropic Sandbox Runtime) enveloppe n'importe quelle commande avec des limites de sécurité :```bash
# Run a command in the sandbox
srt echo "hello world"

# With debug logging
srt --debug curl https://example.com

# Specify custom settings file
srt --settings /path/to/srt-settings.json npm install

**Attribution des violations (`commandId` / `commandText`).** Les violations observées pendant l'exécution d'une commande encapsulée (lignes de journal seatbelt, événements seccomp, refus de proxy) sont stockées sous une clé d'attribution, et `annotateStderrWithSandboxFailures(key, stderr)` / `getViolationsForCommand(key)` les recherchent via cette même clé. Par défaut, la clé est la chaîne encapsulée elle-même. Passez un `commandId` opaque par invocation (par ex. un identifiant d'utilisation d'outil) pour utiliser celui-ci comme clé à la place — recommandé : les clés sont comparées sur leurs 100 premiers caractères, donc des commandes longues partageant un préfixe seraient sinon attribuées de manière croisée, et une réexécution du même texte hériterait des événements de l'exécution précédente. Si la chaîne que vous *exécutez* n'est pas la commande que l'invocation *représente* (par ex. vous encapsulez un `source <snapshot> && eval '<cmd>'` assemblé), passez également `commandText: '<cmd>'` : c'est ce que les modèles de commande `ignoreViolations` comparent et ce que chaque violation rapporte comme son `command`.```typescript
const wrapped = await SandboxManager.wrapWithSandbox(
  assembledCommand, // what actually runs
  undefined,
  undefined,
  undefined,
  { commandId: invocationId, commandText: rawCommand },
)
// ... run it ...
const annotated = SandboxManager.annotateStderrWithSandboxFailures(invocationId, stderr)

## Configuration

### Emplacement du fichier de paramètres

Par défaut, l'environnement d'exécution du sandbox recherche la configuration dans `~/.srt-settings.json`. Vous pouvez spécifier un chemin personnalisé à l'aide de l'option `--settings` :```bash
srt --settings /path/to/srt-settings.json <command>

### Options de configuration

#### Configuration réseau

Utilise un **modèle de type « autorisation uniquement »** : tout accès réseau est refusé par défaut.

- `network.allowedDomains` : tableau des domaines autorisés (prend en charge les jokers comme `*.example.com`). Un tableau vide = aucun accès réseau. Un suffixe `:port` facultatif (`api.example.com:443`, `*.example.com:8443`) restreint une entrée à ce port de destination ; les entrées sans port correspondent à n'importe quel port.
  - Les littéraux IPv6 doivent être entre crochets, au format RFC 3986 : `[::1]`, `[2001:db8::1]:443`. Une entrée multi-deux-points sans crochets est rejetée comme ambiguë (`2001:db8::1:443` est en soi une adresse valide).
- `network.deniedDomains` : tableau des domaines refusés (vérifié en premier, prioritaire sur `allowedDomains`). Même suffixe `:port`, et un `*` nu (ou `*:22`) est accepté pour tout refuser.
- `network.deniedDomainReasons` : mappage facultatif d'une entrée `deniedDomains` (correspondance par chaîne exacte) vers une raison visible par le modèle qui apparaît dans la ligne `<sandbox_violations>` lorsque cette entrée refuse une connexion — indiquez ce qui est bloqué et l'alternative autorisée (par ex. `{"github.com:22": "Les push SSH vers GitHub sont bloqués ; utilisez un remote https://"}`). Les entrées sans raison signalent une raison générique. Pour les destinations SSH (port 22), la raison est également transmise en bande : un client SSH tunnelisé via une commande ProxyCommand SOCKS sans authentification (par ex. `nc -X 5` de BSD) reçoit une déconnexion SSH avant échange de clés dont la description est la raison, qu'OpenSSH imprime textuellement — gardez ces raisons sous ~400 caractères ASCII, à l'impératif en premier, car OpenSSH tronque et échappe les caractères non ASCII.
- `network.allowLocalBinding` : autorise la liaison à des ports locaux (booléen, défaut : false)

**Terminaison TLS** (`network.tlsTerminate`, expérimental) : lorsqu'elle est définie, les CONNECT HTTPS sont terminés dans le processus afin que SRT puisse voir (et filtrer, via `network.filterRequest`) les requêtes déchiffrées. Le processus sandboxé est pointé vers un bundle de confiance contenant la CA MITM (`caCertPath`/`caKeyPath`, ou une CA éphémère si omis) ainsi que les racines habituelles de l'hôte, de sorte que les certificats émis par le proxy et les certificats réels en amont soient tous deux vérifiés.

- `network.tlsTerminate.excludeDomains` : modèles de domaines (même syntaxe que `allowedDomains`) qui ne sont **pas** terminés. Les CONNECT correspondants sont tunnelisés de manière opaque à la place : ils restent soumis à la liste blanche de domaines, mais le client dans le sandbox effectue sa propre poignée de main TLS avec le véritable amont, et `filterRequest` / l'injection d'identifiants ne s'appliquent pas à leur trafic HTTPS. Utilisez ceci pour les deux cas où la terminaison TLS échoue fondamentalement :
  - **Amonts mTLS** : seul le client dans le sandbox détient le certificat client, le proxy ne peut donc pas réinitialiser la connexion en son nom.
  - **Clients avec épinglage de certificat** : clients qui vérifient eux-mêmes l'identité de l'amont (CA personnalisées, épinglage SAN) et rejettent le certificat MITM.
- `network.tlsTerminate.extraCaCertPaths` : chemins vers des fichiers de certificats CA PEM ajoutés à ce bundle de confiance, après la CA MITM et les racines habituelles de l'hôte. Les hôtes exclus (non terminés) sont vérifiés par le client dans le sandbox, et les variables d'environnement de confiance définies par SRT (`SSL_CERT_FILE`, `GIT_SSL_CAINFO`, ...) _remplacent_ la configuration de confiance propre à chaque outil ; une racine locale au site (par ex. une CA mTLS interne) doit donc être dans le bundle, sinon ces hôtes ne pourront jamais être vérifiés. Seuls les blocs `CERTIFICATE` de chaque fichier sont copiés dans le bundle (tout le reste, par ex. une clé privée dans un PEM combiné, n'est jamais exposé au sandbox) ; les fichiers manquants, illisibles ou ne contenant aucun bloc PEM `CERTIFICATE` sont ignorés, il est donc sûr de lister des chemins qui n'existent que sur certains hôtes.```json
{
  "network": {
    "allowedDomains": ["*.example.com", "internal-mtls.example.net"],
    "deniedDomains": [],
    "tlsTerminate": {
      "excludeDomains": ["internal-mtls.example.net"],
      "extraCaCertPaths": ["/etc/internal-mtls-roots.pem"]
    }
  }
}

Paramètre	macOS	Linux
`allowUnixSockets: string[]`	Liste blanche des chemins de sockets	Ignoré (seccomp ne peut pas filtrer par chemin)
`allowAllUnixSockets: boolean`	Autoriser tous les sockets	Désactiver le blocage seccomp

**Restreindre à des répertoires spécifiques :**```json
{
  "network": {
    "allowedDomains": [],
    "deniedDomains": []
  },
  "filesystem": {
    "denyRead": ["~/.ssh"],
    "allowWrite": [".", "src/", "test/"],
    "denyWrite": [".env", "secrets/"]
  }
}

Cela refuse la lecture de tout ce qui se trouve sous `/Users` (ou `/home` sous Linux), puis réautorise le répertoire de travail actuel. Les chemins système (`/usr`, `/lib`, etc.) restent lisibles.

### Problèmes courants et conseils

**Exécution de Jest :** Utilisez l'option `--no-watchman` pour éviter les violations de sandbox :```bash
srt "jest --no-watchman"

ou ajouter un profil AppArmor qui accorde `userns` aux binaires concernés.

**Dépendances Linux facultatives (pour le repli seccomp) :**

Le paquet inclut des filtres BPF seccomp pré-générés pour les architectures x86-64 et arm. Ces dépendances ne sont nécessaires que si vous êtes sur une architecture différente où les filtres pré-générés ne sont pas disponibles :

- `gcc` ou `clang` - compilateur C
- `libseccomp-dev` - fichiers de développement de la bibliothèque Seccomp
  - Ubuntu/Debian : `apt-get install gcc libseccomp-dev`
  - Fedora : `dnf install gcc libseccomp-devel`
  - Arch : `pacman -S gcc libseccomp`

**macOS nécessite :**

- `ripgrep` - outil de recherche rapide pour la détection des chemins refusés
  - Installation via Homebrew : `brew install ripgrep`
  - Ou téléchargement depuis : https://github.com/BurntSushi/ripgrep/releases

**Windows nécessite :**

- Aucune dépendance supplémentaire. L'assistant `srt-win.exe` (x64 et arm64) est fourni avec le paquet npm. Une étape unique `windows-install` avec élévation de privilèges est requise — voir ci-dessous.

## Windows (alpha)

La prise en charge de Windows est **alpha**. Le processus sandboxé s'exécute sous un compte utilisateur local dédié `srt-sandbox`, isolé de l'utilisateur appelant par des primitives de sécurité natives de Windows — une clôture de trafic sortant Windows Filtering Platform (WFP) basée sur le SID du compte sandbox, et des ACE explicites par session qui accordent ou refusent à ce SID l'accès aux chemins de fichiers configurés.

### Configuration

À exécuter une fois par machine (auto-élévation ; une invite UAC) :```powershell
npx @anthropic-ai/sandbox-runtime windows-install

`initialize()` compare l'empreinte du CA de session à celle installée et échoue avec un message actionnable en cas de divergence, afin qu'un CA obsolète datant de l'installation ne puisse pas silencieusement casser TLS dans le sandbox.

Les clients basés sur OpenSSL (`curl` de msys2, `git -c http.sslBackend=openssl`, Node, Python, cargo) sont couverts par la couche de confiance via variables d'environnement : le même bundle de confiance utilisé sur macOS/Linux est transmis dans le sandbox via `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `CURL_CA_BUNDLE`, `GIT_SSL_CAINFO`, `CARGO_HTTP_CAINFO`, etc., et le chemin du bundle est ajouté à l'autorisation `allowRead` de la session afin que le compte sandbox puisse l'ouvrir.

### Configuration spécifique à Windows

Les blocs multiplateformes `filesystem` et `network` s'appliquent comme décrit ci-dessus. Les paramètres propres à Windows se trouvent sous `windows` :

- `windows.proxyPortRange` — plage de ports inclusive `[low, high]` à laquelle les proxys JS se lient à l'intérieur. **Doit correspondre** à la plage transmise à `windows-install --proxy-port-range` (par défaut `[60080, 60089]`) — l'autorisation PERMIT de bouclage WFP ne couvre que cette plage.
- `windows.sublayerGuid` — GUID de la sous-couche WFP sous laquelle les filtres ont été installés. À omettre pour utiliser la valeur par défaut de compilation ; à définir uniquement lorsque des outils d'entreprise ont installé les filtres sous une sous-couche personnalisée.
- `windows.srtWin.path` — chemin vers le binaire `srt-win`. À omettre pour résoudre le `vendor/srt-win/<arch>/srt-win.exe` empaqueté. À définir lors de l'intégration de la CLI de `srt-win` dans un binaire multicall ; les lancements passent alors `--srt-win` comme `argv[1]` afin que le répartiteur de l'intégrateur puisse router vers `srt_win::run_from_args`.

### Limitations connues

- **Révocation de certificat sous schannel.** La récupération CRL/OCSP de CryptoAPI passe par WinHTTP sous le jeton de l'appelant, ignorant l'environnement proxy, et est donc bloquée par la barrière de sortie WFP. Les outils qui utilisent schannel avec la vérification de révocation activée par défaut échouent avec `CRYPT_E_REVOCATION_OFFLINE` (`0x80092013`) sauf si la révocation est désactivée par outil : `curl --ssl-no-revoke`, `git -c http.schannelCheckRevoke=false`, `CARGO_HTTP_CHECK_REVOKE=false`. `Invoke-WebRequest`, `HttpClient` de .NET et `gh` ne vérifient pas la révocation par défaut et ne sont pas affectés. Un point de distribution CRL servi depuis le proxy de bouclage est prévu pour supprimer cette solution de contournement.
- **Les installations d'outils par utilisateur ne sont pas accessibles.** Le processus sandboxé s'exécute sous `srt-sandbox`, pas sous votre compte, donc les outils installés sous votre profil (Node géré par nvm/fnm, paquets `winget`/Scoop par utilisateur, `pip install --user`, `%LOCALAPPDATA%\Programs\…`) se résolvent sur le `PATH` hérité mais ne peuvent pas être ouverts par le compte sandbox. Privilégiez les installations à l'échelle de la machine (`Program Files`, `choco`/`winget --scope machine`), ou ajoutez les chemins de profil spécifiques à `filesystem.allowRead`.
- **Les remplacements `filesystem.allowRead` / `filesystem.allowWrite` par exécution ne sont pas pris en charge.** Les `allowRead`/`allowWrite` au niveau de la session (dans la configuration transmise à `initialize()`) fonctionnent comme décrit ci-dessus ; les transmettre par commande dans `customConfig` de `wrapWithSandbox` lève une exception — les autorisations sont appliquées à l'échelle de la session via `srt-win acl grant` à `initialize()`, et `srt-win exec` n'expose que des refus par exécution.
- **`proxyAuthToken` est visible dans la ligne de commande du processus d'exécution.** L'environnement proxy (y compris `HTTP_PROXY=http://srt:<token>@127.0.0.1:…`) est transmis au processus d'exécution à deux sauts comme arguments `--env` sur l'argv de `srt-win exec`, donc le jeton est lisible par tout principal local pouvant ouvrir le processus d'exécution avec `PROCESS_QUERY_LIMITED_INFORMATION`. Le jeton existe pour que le processus sandboxé puisse s'authentifier auprès du proxy de bouclage, il ne constitue donc pas un secret vis-à-vis du sandbox lui-même ; sur une machine de développement mono-utilisateur, cela est généralement acceptable, mais sur un hôte partagé, considérez la liste d'autorisation du proxy comme accessible par d'autres principaux de la même session.
- **La résolution DNS via le résolveur système n'est pas cloisonnée.** `getaddrinfo()` est pris en charge par le service `Dnscache` s'exécutant sous `NETWORK SERVICE`, donc la résolution de noms réussit même si le `connect()` ultérieur depuis le processus sandboxé est bloqué. Les outils qui font leur propre UDP/53 (`nslookup`, `dig`) sont cloisonnés. Cela reflète le comportement de macOS.

### Désinstallation```powershell
npx @anthropic-ai/sandbox-runtime windows-uninstall

### Compilation des binaires Seccomp

Le filtre BPF et le chargeur `apply-seccomp` sont compilés à partir du code source C dans `vendor/seccomp-src/` via `npm run build:seccomp` (Linux uniquement ; nécessite `gcc` et `libseccomp-dev`). CI l'exécute avant les tests sur chaque architecture Linux, et le workflow de release compile les deux architectures et les regroupe dans le package publié.

## Détails d'implémentation

### Architecture d'isolation réseau

Le sandbox exécute des serveurs proxy HTTP et SOCKS5 sur la machine hôte qui filtrent toutes les requêtes réseau en fonction des règles de permission :

1. **Trafic HTTP/HTTPS** : Un serveur proxy HTTP intercepte les requêtes et les valide par rapport aux domaines autorisés/interdits
2. **Autre trafic réseau** : Un proxy SOCKS5 gère toutes les autres connexions TCP (SSH, connexions de bases de données, etc.)
3. **Application des permissions** : Les proxys appliquent les règles `permissions` de votre configuration

**Communication proxy spécifique à la plateforme :**

- **Linux** : Les requêtes sont routées via le système de fichiers sur des sockets de domaine Unix (en utilisant `socat` pour le pontage). L'espace de noms réseau est supprimé du conteneur bubblewrap, garantissant que tout le trafic réseau doit passer par les proxys.

- **macOS** : Le profil Seatbelt autorise la communication uniquement vers des ports localhost spécifiques où les proxys écoutent. Tout autre accès réseau est bloqué.

- **Windows** : Un filtre WFP `ALE_AUTH_CONNECT` bloque chaque connexion sortante depuis le compte `srt-sandbox` sauf le loopback vers la plage de ports proxy configurée. Les proxys se lient dans cette plage. Les variables d'environnement (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, …) pointent les outils vers les proxys, mais le filtre WFP constitue la frontière — un processus qui les ignore ou les désactive reste cloisonné.

### Isolation du système de fichiers

Les restrictions du système de fichiers sont appliquées au niveau du système d'exploitation :

- **macOS** : Utilise `sandbox-exec` avec des profils Seatbelt générés dynamiquement qui spécifient les chemins de lecture/écriture autorisés
- **Linux** : Utilise `bubblewrap` avec des montages bind, marquant les répertoires comme en lecture seule ou en lecture-écriture selon la configuration
- **Windows** : Écrit des ACE explicites additifs `(OI)(CI)` pour le SID `srt-sandbox` sur les chemins configurés (ALLOW sur `allowRead`/`allowWrite`, DENY sur `denyRead`/`denyWrite`), puis les supprime lors de `reset()`

**Permissions du système de fichiers par défaut :**

- **Lecture** (refus-puis-autorisation) : Autorisée partout par défaut. Vous pouvez refuser de larges zones, puis ré-autoriser des chemins spécifiques à l'intérieur. `allowRead` a priorité sur `denyRead`.

  - Exemple : `denyRead: ["~/.ssh"]` pour bloquer l'accès aux clés SSH
  - Exemple : `denyRead: ["/Users"], allowRead: ["."]` pour bloquer tout `/Users` sauf l'espace de travail
  - `denyRead: []` vide = accès en lecture complet (rien n'est refusé)

- **Écriture** (autorisation uniquement) : Refusée partout par défaut. Vous devez explicitement autoriser des chemins.
  - Exemple : `allowWrite: [".", "/tmp"]` pour autoriser les écritures dans le répertoire courant et /tmp
  - `allowWrite: []` vide = aucun accès en écriture (rien n'est autorisé)
  - `denyWrite` crée des exceptions dans les chemins autorisés (le refus a priorité)

**La priorité est intentionnellement opposée pour les lectures vs les écritures :** `allowRead` remplace `denyRead`, tandis que `denyWrite` remplace `allowWrite`. Cela vous permet de découper des zones lisibles dans des zones refusées, et de découper des zones protégées dans des zones inscriptibles.

### Chemins de refus obligatoires (fichiers auto-protégés)

Certains fichiers et répertoires sensibles sont **toujours bloqués en écriture**, même s'ils se trouvent dans un chemin d'écriture autorisé. Cela offre une défense en profondeur contre les évasions du sandbox et la falsification de la configuration.

**Fichiers toujours bloqués :**

- Fichiers de configuration du shell : `.bashrc`, `.bash_profile`, `.zshrc`, `.zprofile`, `.profile`
- Fichiers de configuration Git : `.gitconfig`, `.gitmodules`
- Autres fichiers sensibles : `.ripgreprc`, `.mcp.json`

**Répertoires toujours bloqués :**

- Répertoires IDE : `.vscode/`, `.idea/`
- Répertoires de configuration Claude : `.claude/commands/`, `.claude/agents/`
- Hooks et configuration Git : `.git/hooks/`, `.git/config`

Ces chemins sont bloqués automatiquement — vous n'avez pas besoin de les ajouter à `denyWrite`. Par exemple, même avec `allowWrite: ["."]`, l'écriture dans `.bashrc` ou `.git/hooks/pre-commit` échouera :```bash
$ srt 'echo "malicious" >> .bashrc'
/bin/bash: .bashrc: Operation not permitted

$ srt 'echo "bad" > .git/hooks/pre-commit'
/bin/bash: .git/hooks/pre-commit: Operation not permitted

- Défaut : `3` (recherche jusqu'à 3 niveaux de profondeur)
- Plage : `1` à `10`
- Des valeurs plus élevées offrent une meilleure protection mais des performances plus lentes
- Les fichiers dans le répertoire de travail courant (profondeur 0) sont toujours protégés, quelle que soit ce paramètre

### Restrictions des sockets Unix (Linux)

Sous Linux, le sandbox utilise **seccomp BPF (Berkeley Packet Filter)** pour bloquer la création de sockets de domaine Unix au niveau des appels système. Cela fournit une couche de sécurité supplémentaire pour empêcher les processus de créer de nouveaux sockets de domaine Unix pour la communication inter-processus locale (sauf autorisation explicite).

**Comment cela fonctionne :**

1. **Filtre BPF intégré** : Le paquet inclut un binaire statique `apply-seccomp` pour x64 et arm64 avec le filtre seccomp BPF compilé dedans. Le filtre est spécifique à l'architecture mais indépendant de la libc, le binaire fonctionne donc avec glibc et musl.

2. **Détection à l'exécution** : Le sandbox détecte automatiquement l'architecture de votre système et utilise le binaire `apply-seccomp` correspondant.

3. **Filtrage des appels système** : Le filtre BPF intercepte l'appel système `socket()` et bloque la création de sockets `AF_UNIX` en renvoyant `EPERM`. Cela empêche le code sandboxé de créer de nouveaux sockets de domaine Unix.

4. **Application en deux étapes à l'aide du binaire apply-seccomp** :
   - Le bwrap externe crée le sandbox avec les restrictions de système de fichiers, de réseau et d'espace de noms PID
   - Les processus de pontage réseau (socat) démarrent à l'intérieur du sandbox (ils ont besoin de sockets Unix)
   - apply-seccomp crée un espace de noms imbriqué user+PID+mount et remonte `/proc`
   - À l'intérieur de l'espace de noms imbriqué, apply-seccomp agit comme PID 1 (init/reaper non-dumpable)
   - apply-seccomp crée un processus fils, applique le filtre seccomp via `prctl()`, puis exécute la commande utilisateur
   - La commande utilisateur s'exécute avec toutes les restrictions du sandbox plus le blocage de la création de sockets Unix

**Isolation de l'espace de noms PID** : L'espace de noms PID imbriqué garantit que la commande utilisateur ne peut pas voir ni adresser un processus qui s'exécute sans le filtre seccomp (l'init de bwrap, le script shell intermédiaire ou les assistants socat). Cela maintient la frontière seccomp intacte quel que soit `kernel.yama.ptrace_scope`, car les assistants non filtrés ne sont pas accessibles via `ptrace` ou `/proc/N/mem`. Le PID 1 interne définit `PR_SET_DUMPABLE=0` afin qu'il ne soit pas non plus traçable via ptrace. Si la création de l'espace de noms imbriqué échoue, apply-seccomp abandonne plutôt que de s'exécuter sans isolation.

**Limitations de sécurité** : Le filtre bloque `socket(AF_UNIX, ...)` et les appels système `io_uring_setup`/`io_uring_enter`/`io_uring_register` (ces trois derniers car `IORING_OP_SOCKET` sur Linux 5.19+ contournerait autrement la règle `socket()`). Il n'empêche pas les opérations sur les descripteurs de fichiers de sockets Unix hérités des processus parents ou transmis via `SCM_RIGHTS`. Pour la plupart des scénarios de sandboxing, bloquer la création de sockets est suffisant pour empêcher les communications inter-processus non autorisées.

**Zéro dépendance à l'exécution** : Les binaires statiques précompilés apply-seccomp et les filtres BPF pré-générés sont inclus pour les architectures x64 et arm64. Aucun outil de compilation ni dépendance externe n'est requis à l'exécution.

**Prise en charge des architectures** : x64 et arm64 sont entièrement pris en charge avec des binaires précompilés. Les autres architectures ne sont actuellement pas prises en charge. Pour utiliser le sandboxing sans blocage des sockets Unix sur des architectures non prises en charge, définissez `allowAllUnixSockets: true` dans votre configuration.

### Détection et surveillance des violations

Lorsqu'un processus sandboxé tente d'accéder à une ressource restreinte :

1. **Bloque l'opération** au niveau du système d'exploitation (renvoie l'erreur `EPERM`)
2. **Journalise la violation** (mécanismes spécifiques à la plateforme)
3. **Notifie l'utilisateur** (dans Claude Code, cela déclenche une invite d'autorisation)

**macOS** : L'environnement d'exécution du sandbox exploite le magasin de journaux de violations du sandbox système de macOS. Cela fournit des notifications en temps réel avec des informations détaillées sur ce qui a été tenté et pourquoi cela a été bloqué. C'est le même mécanisme que Claude Code utilise pour la détection des violations.```bash
# View sandbox violations in real-time
log stream --predicate 'process == "sandbox-exec"' --style syslog

### Avancé : Apportez votre propre proxy

Pour un filtrage réseau plus sophistiqué, vous pouvez configurer le sandbox pour utiliser votre propre proxy au lieu de ceux intégrés. Cela permet :

- **Inspection du trafic** : Utilisez des outils comme [mitmproxy](https://mitmproxy.org/) pour inspecter et modifier le trafic
- **Logique de filtrage personnalisée** : Implémentez des règles complexes au-delà de simples listes d'autorisation de domaines
- **Journalisation d'audit** : Consignez toutes les requêtes réseau pour la conformité ou le débogage

**Exemple avec mitmproxy :**```bash
# Start mitmproxy with custom filtering script
mitmproxy -s custom_filter.py --listen-port 8888

Élévation de privilèges via les sockets Unix : La configuration allowUnixSockets peut accidentellement accorder l'accès à des services système puissants qui pourraient conduire à des contournements du sandbox. Par exemple, si elle est utilisée pour autoriser l'accès à /var/run/docker.sock, cela accorderait effectivement l'accès au système hôte en exploitant le socket Docker. Les utilisateurs sont encouragés à examiner attentivement tous les sockets Unix qu'ils autorisent à travers le sandbox.
Élévation des permissions du système de fichiers : Des permissions d'écriture trop larges sur le système de fichiers peuvent permettre des attaques d'élévation de privilèges. Autoriser l'écriture dans des répertoires contenant des exécutables dans $PATH, des répertoires de configuration système ou des fichiers de configuration shell utilisateur (.bashrc, .zshrc) peut conduire à l'exécution de code dans différents contextes de sécurité lorsque d'autres utilisateurs ou processus système accèdent à ces fichiers.
Robustesse 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 dans des environnements Docker sans espaces de noms privilégiés. Cette option affaiblit considérablement la sécurité et ne doit être utilisée que dans les cas où une isolation supplémentaire est par ailleurs appliquée.
Isolation réseau plus faible (macOS) : L'option enableWeakerNetworkIsolation réactive l'accès à com.apple.trustd.agent, nécessaire aux programmes Go pour vérifier les certificats TLS via le framework de sécurité macOS. Cela ouvre un vecteur potentiel d'exfiltration de données via le service trustd et ne doit être activé que lorsque la vérification TLS Go est requise (par exemple, lors de l'utilisation de httpProxyPort avec un proxy MITM et une CA personnalisée).
Apple Events (macOS) : L'option allowAppleEvents réactive l'envoi d'Apple Events et les requêtes d'ouverture Launch Services ((allow appleevent-send), (allow lsopen) et les mach-lookups pour com.apple.coreservices.appleevents, com.apple.CoreServices.coreservicesd et com.apple.coreservices.quarantine-resolver), dont open, osascript et les assistants d'ouverture d'URL ont besoin. Avec ces autorisations, une commande sandboxée peut lancer des applications arbitraires sans invite utilisateur, et les applications lancées s'exécutent entièrement en dehors du sandbox — cette option supprime donc l'isolation de l'exécution de code, et pas seulement l'affaiblit. Le script d'applications déjà en cours d'exécution via Apple Events est en outre soumis au consentement d'automatisation TCC de macOS, mais le lancement via open ne l'est pas. N'activez cette option que lorsque les commandes dans le sandbox ont réellement besoin d'ouvrir des URL ou des applications.

sandbox-runtime

Populaires

Aperçu

Cas d'usage exemple : Mise en sandbox des serveurs MCP

Fonctionnement

Modèle d'isolation double

Architecture```

En tant que bibliothèque```typescript

Exports disponibles```typescript

Exemple de Configuration Complet```json

Configuration du système de fichiers

Autres configurations

Recettes de configuration courantes

Prise en charge des plateformes

Dépendances spécifiques à la plateforme

Modèle de sécurité

Terminaison TLS sur Windows

Développement```bash

Install dependencies

Build the project

Run tests

Type checking

Lint code

Format code

Trace all denied operations

Trace specific file operations

Trace network operations

Limites de sécurité

Limites connues et travaux futurs