sandbox-runtime — Ein leichtgewichtiges Sandboxing-Tool zur Durchsetzung von Dateisystem- und Netzwerkbeschränkungen für beliebige Prozesse auf Betriebssystemebene, ohne dass ein Container erforderlich ist. | Kitploit

Anthropic Sandbox Runtime (srt)

Ein leichtgewichtiges Sandboxing-Tool zur Durchsetzung von Dateisystem- und Netzwerkbeschränkungen für beliebige Prozesse auf Betriebssystemebene, ohne dass ein Container erforderlich ist.

srt nutzt native OS-Sandboxing-Primitive (sandbox-exec auf macOS, bubblewrap auf Linux) sowie proxybasiertes Netzwerk-Filtering. Es kann verwendet werden, um das Verhalten von Agenten, lokalen MCP-Servern, Bash-Befehlen und beliebigen Prozessen zu sandboxen.

Beta-Forschungspreview

Die Sandbox Runtime ist eine Forschungspreview, die für Claude Code entwickelt wurde, um sicherere KI-Agenten zu ermöglichen. Sie wird als frühe Open-Source-Preview bereitgestellt, um dem breiteren Ökosystem beim Aufbau sichererer agentischer Systeme zu helfen. Da es sich um eine frühe Forschungspreview handelt, können sich APIs und Konfigurationsformate weiterentwickeln. Wir freuen uns über Feedback und Beiträge, um KI-Agenten standardmäßig sicherer zu machen!

Installation```bash

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

## Grundlegende Verwendung```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

Benutzer sollten sich der potenziellen Risiken bewusst sein, die durch das Zulassen breiter Domains wie `github.com` entstehen, die eine Datenextfiltration ermöglichen können. Außerdem ist es in einigen Fällen möglich, die Netzwerkfilterung durch [Domain Fronting](https://en.wikipedia.org/wiki/Domain_fronting) zu umgehen.

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

Jetzt wird der MCP-Server daran gehindert, in den verweigerten Pfad zu schreiben:```
> Write a file to ~/sensitive-folder
✗ Error: EPERM: operation not permitted, open '/Users/ollie/sensitive-folder/test.txt'

## Verwendung

### Als CLI-Werkzeug

Der Befehl `srt` (Anthropic Sandbox Runtime) umschließt jeden Befehl mit Sicherheitsgrenzen:```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

**Verletzungszuordnung (`commandId` / `commandText`).** Verstöße, die während der Ausführung eines umschlossenen Befehls beobachtet werden (Seatbelt-Protokollzeilen, Seccomp-Ereignisse, Proxy-Ablehnungen), werden unter einem Zuordnungsschlüssel gespeichert, und `annotateStderrWithSandboxFailures(key, stderr)` / `getViolationsForCommand(key)` suchen sie über denselben Schlüssel nach. Standardmäßig ist der Schlüssel die umschlossene Zeichenkette selbst. Übergeben Sie eine undurchsichtige, pro Aufruf vergebene `commandId` (z. B. eine Tool-Use-ID), um stattdessen danach zu schlüsseln — empfohlen: Schlüssel vergleichen ihre ersten 100 Zeichen, sodass lange Befehle mit gemeinsamem Präfix sonst falsch zugeordnet würden, und eine erneute Ausführung desselben Texts die Ereignisse des früheren Laufs erben würde. Wenn die Zeichenkette, die Sie *ausführen*, nicht der Befehl ist, den der Aufruf *repräsentiert* (z. B. wenn Sie ein zusammengesetztes `source <snapshot> && eval '<cmd>'` umschließen), übergeben Sie ebenfalls `commandText: '<cmd>'`: Es ist das, wogegen die `ignoreViolations`-Befehlsmuster abgleichen und was jeder Verstoß als seinen `command` meldet.```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)

## Konfiguration

### Speicherort der Einstellungsdatei

Standardmäßig sucht die Sandbox-Laufzeitumgebung nach der Konfiguration unter `~/.srt-settings.json`. Sie können einen benutzerdefinierten Pfad mithilfe des Flags `--settings` angeben:```bash
srt --settings /path/to/srt-settings.json <command>

### Konfigurationsoptionen

#### Netzwerkkonfiguration

Verwendet ein **Nur-Erlauben-Muster** – der gesamte Netzwerkzugriff ist standardmäßig verweigert.

- `network.allowedDomains` – Array der erlaubten Domains (unterstützt Platzhalter wie `*.example.com`). Leeres Array = kein Netzwerkzugriff. Ein optionales `:port`-Suffix (`api.example.com:443`, `*.example.com:8443`) beschränkt einen Eintrag auf diesen Zielport; Einträge ohne Port entsprechen jedem Port.
  - IPv6-Literale müssen in eckigen Klammern gesetzt werden, RFC-3986-Stil: `[::1]`, `[2001:db8::1]:443`. Ein Eintrag mit mehreren Doppelpunkten ohne Klammern wird als mehrdeutig abgelehnt (`2001:db8::1:443` ist selbst eine gültige Adresse).
- `network.deniedDomains` – Array der verweigerten Domains (wird zuerst geprüft, hat Vorrang vor `allowedDomains`). Gleiches `:port`-Suffix, und ein nacktes `*` (oder `*:22`) wird für Verweigern-alles akzeptiert.
- `network.deniedDomainReasons` – Optionale Zuordnung von einem `deniedDomains`-Eintrag (per exakter Zeichenkette abgeglichen) zu einem modellbezogenen Grund, der in der `<sandbox_violations>`-Zeile erscheint, wenn dieser Eintrag eine Verbindung verweigert – geben Sie an, was blockiert ist, und die genehmigte Alternative (z. B. `{"github.com:22": "SSH-Pushes an GitHub sind blockiert; verwenden Sie ein https://-Remote"}`). Einträge ohne Grund melden einen allgemeinen Grund. Für SSH-Ziele (Port 22) wird der Grund auch in-band übermittelt: Ein SSH-Client, der durch einen SOCKS-ProxyCommand ohne Authentifizierung getunnelt wird (z. B. BSD `nc -X 5`), erhält eine SSH-Trennung vor dem Schlüsselaustausch, deren Beschreibung der Grund ist, den OpenSSH wörtlich ausgibt – halten Sie solche Gründe unter ~400 ASCII-Zeichen, imperativ zuerst, da OpenSSH nicht-ASCII kürzt und maskiert.
- `network.allowLocalBinding` – Binden an lokale Ports erlauben (boolesch, Standard: false)

**TLS-Terminierung** (`network.tlsTerminate`, experimentell): Wenn gesetzt, werden HTTPS-CONNECTs prozessintern terminiert, sodass SRT die entschlüsselten Anfragen sehen (und über `network.filterRequest` filtern) kann. Der sandboxierte Prozess wird auf einen Vertrauensspeicher verwiesen, der die MITM-CA (`caCertPath`/`caKeyPath` oder eine flüchtige CA, falls weggelassen) sowie die regulären Roots des Hosts enthält, sodass sowohl vom Proxy ausgestellte Zertifikate als auch echte Upstream-Zertifikate verifiziert werden.

- `network.tlsTerminate.excludeDomains` – Domain-Muster (gleiche Syntax wie `allowedDomains`), die **nicht** terminiert werden. Passende CONNECTs werden stattdessen opak getunnelt: Sie unterliegen weiterhin der Domain-Allowlist, aber der Client innerhalb der Sandbox führt seinen eigenen TLS-Handshake mit dem echten Upstream durch, und `filterRequest`/Credential-Injektion gelten nicht für deren HTTPS-Verkehr. Verwenden Sie dies für die beiden Fälle, die TLS-Terminierung grundlegend bricht:
  - **mTLS-Upstreams** – nur der Client in der Sandbox hält das Client-Zertifikat, sodass der Proxy die Verbindung nicht in seinem Namen neu aufbauen kann.
  - **Zertifikat-Pinning-Clients** – Clients, die die Identität des Upstreams selbst verifizieren (benutzerdefinierte CAs, SAN-Pinning) und das MITM-Zertifikat ablehnen.
- `network.tlsTerminate.extraCaCertPaths` – Pfade zu PEM-CA-Zertifikatsdateien, die diesem Vertrauensspeicher angehängt werden, nach der MITM-CA und den regulären Roots des Hosts. Ausgeschlossene (nicht terminierte) Hosts werden vom Client in der Sandbox verifiziert, und die Vertrauens-Umgebungsvariablen, die SRT setzt (`SSL_CERT_FILE`, `GIT_SSL_CAINFO`, ...), _ersetzen_ die eigene Vertrauenskonfiguration jedes Tools, sodass eine standortlokale Root (z. B. eine interne mTLS-CA) im Speicher enthalten sein muss, sonst können diese Hosts nie verifiziert werden. Nur die `CERTIFICATE`-Blöcke jeder Datei werden in den Speicher kopiert (alles andere, z. B. ein privater Schlüssel in einem kombinierten PEM, wird der Sandbox nie ausgesetzt); Dateien, die fehlen, nicht lesbar sind oder keinen PEM-`CERTIFICATE`-Block enthalten, werden übersprungen, sodass es sicher ist, Pfade aufzulisten, die nur auf einigen Hosts existieren.```json
{
  "network": {
    "allowedDomains": ["*.example.com", "internal-mtls.example.net"],
    "deniedDomains": [],
    "tlsTerminate": {
      "excludeDomains": ["internal-mtls.example.net"],
      "extraCaCertPaths": ["/etc/internal-mtls-roots.pem"]
    }
  }
}

Einstellung	macOS	Linux
`allowUnixSockets: string[]`	Zulassungsliste von Socket-Pfaden	Ignoriert (seccomp kann nicht nach Pfad filtern)
`allowAllUnixSockets: boolean`	Alle Sockets zulassen	seccomp-Blockierung deaktivieren

**Auf bestimmte Verzeichnisse beschränken:**```json
{
  "network": {
    "allowedDomains": [],
    "deniedDomains": []
  },
  "filesystem": {
    "denyRead": ["~/.ssh"],
    "allowWrite": [".", "src/", "test/"],
    "denyWrite": [".env", "secrets/"]
  }
}

Dies verweigert das Lesen von allem unter `/Users` (oder `/home` unter Linux) und erlaubt dann wieder das aktuelle Arbeitsverzeichnis. Systempfade (`/usr`, `/lib` usw.) bleiben lesbar.

### Häufige Probleme und Tipps

**Jest ausführen:** Verwenden Sie das Flag `--no-watchman`, um Sandbox-Verstöße zu vermeiden:```bash
srt "jest --no-watchman"

oder ein AppArmor-Profil hinzufügen, das `userns` für die relevanten Binärdateien gewährt.

**Optionale Linux-Abhängigkeiten (für den Seccomp-Fallback):**

Das Paket enthält vorab generierte Seccomp-BPF-Filter für die Architekturen x86-64 und arm. Diese Abhängigkeiten werden nur benötigt, wenn Sie sich auf einer anderen Architektur befinden, für die keine vorab generierten Filter verfügbar sind:

- `gcc` oder `clang` - C-Compiler
- `libseccomp-dev` - Entwicklungsdateien der Seccomp-Bibliothek
  - Ubuntu/Debian: `apt-get install gcc libseccomp-dev`
  - Fedora: `dnf install gcc libseccomp-devel`
  - Arch: `pacman -S gcc libseccomp`

**macOS erfordert:**

- `ripgrep` - Schnelles Suchwerkzeug zur Erkennung von Deny-Pfaden
  - Installation über Homebrew: `brew install ripgrep`
  - Oder herunterladen von: https://github.com/BurntSushi/ripgrep/releases

**Windows erfordert:**

- Keine zusätzlichen Abhängigkeiten. Der `srt-win.exe`-Helfer (x64 und arm64) ist im npm-Paket enthalten. Ein einmaliger Schritt `windows-install` mit erhöhten Rechten ist erforderlich – siehe unten.

## Windows (Alpha)

Die Windows-Unterstützung ist **Alpha**. Der sandboxierte Prozess läuft unter einem dedizierten lokalen Benutzerkonto `srt-sandbox`, das durch native Windows-Sicherheitsprimitive vom aufrufenden Benutzer isoliert ist – ein Windows Filtering Platform (WFP)-Egress-Fence, der auf die SID des Sandbox-Kontos abgestimmt ist, sowie explizite ACEs pro Sitzung, die dieser SID Zugriff auf konfigurierte Dateisystempfade gewähren oder verweigern.

### Einrichtung

Einmal pro Maschine ausführen (selbst-erhöhend; eine UAC-Eingabeaufforderung):```powershell
npx @anthropic-ai/sandbox-runtime windows-install

`initialize()` vergleicht den Fingerabdruck der Sitzungs-CA mit der installierten und schlägt bei einer Abweichung mit einer verständlichen Meldung fehl, sodass eine veraltete Installations-CA TLS innerhalb der Sandbox nicht stillschweigend unterbrechen kann.

OpenSSL-basierte Clients (msys2 `curl`, `git -c http.sslBackend=openssl`, Node, Python, cargo) werden von der Vertrauensschicht über Umgebungsvariablen abgedeckt: Dasselbe Vertrauensbündel, das unter macOS/Linux verwendet wird, wird über `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `CURL_CA_BUNDLE`, `GIT_SSL_CAINFO`, `CARGO_HTTP_CAINFO` usw. in die Sandbox übergeben, und der Pfad zum Bündel wird der `allowRead`-Berechtigung der Sitzung hinzugefügt, damit das Sandbox-Konto es öffnen kann.

### Windows-spezifische Konfiguration

Die plattformübergreifenden Blöcke `filesystem` und `network` gelten wie oben beschrieben. Windows-spezifische Einstellungen befinden sich unter `windows`:

- `windows.proxyPortRange` — `[low, high]` inklusiver Portbereich, an den die JS-Proxys gebunden werden. **Muss** mit dem Bereich übereinstimmen, der an `windows-install --proxy-port-range` übergeben wird (Standard `[60080, 60089]`) — die WFP-Loopback-PERMIT-Regel deckt nur diesen Bereich ab.
- `windows.sublayerGuid` — WFP-Sublayer-GUID, unter der die Filter installiert wurden. Weglassen, um den Kompilierzeit-Standard zu verwenden; nur setzen, wenn Unternehmenswerkzeuge die Filter unter einem benutzerdefinierten Sublayer installiert haben.
- `windows.srtWin.path` — Pfad zur `srt-win`-Binärdatei. Weglassen, um die gebündelte `vendor/srt-win/<arch>/srt-win.exe` aufzulösen. Setzen, wenn die CLI von `srt-win` in eine Multical-Binärdatei eingebettet wird; Spawns übergeben dann `--srt-win` als `argv[1]`, damit der Dispatcher des Einbettenden an `srt_win::run_from_args` weiterleiten kann.

### Bekannte Einschränkungen

- **Zertifikatswiderruf unter schannel.** Der CRL/OCSP-Abruf von CryptoAPI erfolgt über WinHTTP unter dem Token des Aufrufers und ignoriert die Proxy-Umgebung, sodass er durch den WFP-Egress-Filter blockiert wird. Tools, die schannel mit standardmäßig aktivierter Widerrufsprüfung verwenden, schlagen mit `CRYPT_E_REVOCATION_OFFLINE` (`0x80092013`) fehl, sofern der Widerruf nicht pro Tool deaktiviert wird: `curl --ssl-no-revoke`, `git -c http.schannelCheckRevoke=false`, `CARGO_HTTP_CHECK_REVOKE=false`. `Invoke-WebRequest`, .NET `HttpClient` und `gh` prüfen den Widerruf standardmäßig nicht und sind nicht betroffen. Ein CRL-Ausstellungsort, der über den Loopback-Proxy bereitgestellt wird, ist geplant, um diese Problemumgehung zu entfernen.
- **Pro-benutzer-Installationen von Tools sind nicht erreichbar.** Der sandboxierte Prozess läuft als `srt-sandbox`, nicht als Sie, sodass Tools, die unter Ihrem Profil installiert sind (nvm/fnm-verwaltetes Node, Pro-benutzer-`winget`/Scoop-Pakete, `pip install --user`, `%LOCALAPPDATA%\Programs\…`), auf dem geerbten `PATH` aufgelöst, aber vom Sandbox-Konto nicht geöffnet werden können. Bevorzugen Sie maschinenweite Installationen (`Program Files`, `choco`/`winget --scope machine`) oder fügen Sie die spezifischen Profilpfade zu `filesystem.allowRead` hinzu.
- **Pro-Ausführung-Überschreibungen von `filesystem.allowRead` / `filesystem.allowWrite` werden nicht unterstützt.** Sitzungsweite `allowRead`/`allowWrite` (in der an `initialize()` übergebenen Konfiguration) funktionieren wie oben beschrieben; die Übergabe pro Befehl in `customConfig` von `wrapWithSandbox` wirft einen Fehler — Berechtigungen werden sitzungsweit über `srt-win acl grant` bei `initialize()` angewendet, und `srt-win exec` setzt nur Pro-Ausführung-Verweigerungen um.
- **`proxyAuthToken` ist in der Befehlszeile des Runners sichtbar.** Die Proxy-Umgebung (einschließlich `HTTP_PROXY=http://srt:<token>@127.0.0.1:…`) wird dem Zwei-Hop-Runner als `--env`-Argumente auf der argv von `srt-win exec` übergeben, sodass das Token von jedem lokalen Prinzipal gelesen werden kann, der den Runner-Prozess für `PROCESS_QUERY_LIMITED_INFORMATION` öffnen kann. Das Token existiert, damit der sandboxierte Prozess sich beim Loopback-Proxy authentifizieren kann, ist also kein Geheimnis gegenüber der Sandbox selbst; auf einem Einzelbenutzer-Entwicklungsrechner ist dies im Allgemeinen akzeptabel, aber auf einem gemeinsam genutzten Host behandeln Sie die Proxy-Allowlist als für andere Prinzipale derselben Sitzung erreichbar.
- **DNS-Auflösung über den System-Resolver ist nicht eingezäunt.** `getaddrinfo()` wird vom `Dnscache`-Dienst bedient, der als `NETWORK SERVICE` läuft, sodass die Namensauflösung gelingt, obwohl der anschließende `connect()` vom sandboxierten Prozess blockiert wird. Tools, die ihr eigenes UDP/53 verwenden (`nslookup`, `dig`), sind eingezäunt. Dies spiegelt das macOS-Verhalten wider.

### Deinstallation```powershell
npx @anthropic-ai/sandbox-runtime windows-uninstall

### Seccomp-Binaries erstellen

Der BPF-Filter und der `apply-seccomp`-Lader werden aus C-Quellcode in `vendor/seccomp-src/` über `npm run build:seccomp` kompiliert (nur Linux; benötigt `gcc` und `libseccomp-dev`). CI führt dies vor den Tests auf jeder Linux-Architektur aus, und der Release-Workflow erstellt beide Architekturen und bündelt sie im veröffentlichten Paket.

## Implementierungsdetails

### Architektur der Netzwerk-Isolation

Die Sandbox führt HTTP- und SOCKS5-Proxy-Server auf dem Host-Rechner aus, die alle Netzwerkanfragen basierend auf den Berechtigungsregeln filtern:

1. **HTTP/HTTPS-Datenverkehr**: Ein HTTP-Proxy-Server fängt Anfragen ab und validiert sie gegen erlaubte/gesperrte Domains
2. **Anderer Netzwerkverkehr**: Ein SOCKS5-Proxy behandelt alle anderen TCP-Verbindungen (SSH, Datenbankverbindungen usw.)
3. **Durchsetzung von Berechtigungen**: Die Proxys setzen die `permissions`-Regeln aus Ihrer Konfiguration durch

**Plattformspezifische Proxy-Kommunikation:**

- **Linux**: Anfragen werden über das Dateisystem über Unix-Domain-Sockets weitergeleitet (unter Verwendung von `socat` zur Überbrückung). Der Netzwerk-Namespace wird aus dem Bubblewrap-Container entfernt, sodass der gesamte Netzwerkverkehr über die Proxys laufen muss.

- **macOS**: Das Seatbelt-Profil erlaubt nur die Kommunikation mit bestimmten Localhost-Ports, an denen die Proxys lauschen. Der gesamte andere Netzwerkzugriff ist blockiert.

- **Windows**: Ein WFP-`ALE_AUTH_CONNECT`-Filter blockiert jeden ausgehenden Connect vom `srt-sandbox`-Konto, außer Loopback zum konfigurierten Proxy-Portbereich. Die Proxys binden innerhalb dieses Bereichs. Umgebungsvariablen (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, …) zeigen Tools auf die Proxys, aber der WFP-Filter ist die Grenze – ein Prozess, der sie ignoriert oder entfernt, ist dennoch eingezäunt.

### Dateisystem-Isolation

Dateisystemeinschränkungen werden auf Betriebssystemebene durchgesetzt:

- **macOS**: Verwendet `sandbox-exec` mit dynamisch generierten Seatbelt-Profilen, die erlaubte Lese-/Schreibpfade festlegen
- **Linux**: Verwendet `bubblewrap` mit Bind-Mounts, die Verzeichnisse basierend auf der Konfiguration als schreibgeschützt oder lesbar/schreibbar markieren
- **Windows**: Schreibt additive `(OI)(CI)`-explizite ACEs für die `srt-sandbox`-SID auf die konfigurierten Pfade (ALLOW auf `allowRead`/`allowWrite`, DENY auf `denyRead`/`denyWrite`) und entfernt sie dann bei `reset()`

**Standard-Dateisystemberechtigungen:**

- **Lesen** (Deny-dann-Allow): Standardmäßig überall erlaubt. Sie können große Bereiche sperren und dann bestimmte Pfade darin wieder erlauben. `allowRead` hat Vorrang vor `denyRead`.

  - Beispiel: `denyRead: ["~/.ssh"]`, um den Zugriff auf SSH-Schlüssel zu blockieren
  - Beispiel: `denyRead: ["/Users"], allowRead: ["."]`, um ganz `/Users` zu blockieren, außer dem Arbeitsbereich
  - Leeres `denyRead: []` = voller Lesezugriff (nichts gesperrt)

- **Schreiben** (nur-Allow): Standardmäßig überall gesperrt. Sie müssen Pfade explizit erlauben.
  - Beispiel: `allowWrite: [".", "/tmp"]`, um Schreibzugriff auf das aktuelle Verzeichnis und /tmp zu erlauben
  - Leeres `allowWrite: []` = kein Schreibzugriff (nichts erlaubt)
  - `denyWrite` erstellt Ausnahmen innerhalb erlaubter Pfade (Deny hat Vorrang)

**Die Rangfolge ist für Lesen vs. Schreiben bewusst umgekehrt:** `allowRead` überschreibt `denyRead`, während `denyWrite` `allowWrite` überschreibt. So können Sie lesbare Bereiche innerhalb gesperrter Bereiche aussparen und geschützte Bereiche innerhalb beschreibbarer Bereiche aussparen.

### Pflicht-Sperrpfade (automatisch geschützte Dateien)

Bestimmte sensible Dateien und Verzeichnisse sind **immer gegen Schreibzugriffe blockiert**, selbst wenn sie in einen erlaubten Schreibpfad fallen. Dies bietet Defense-in-Depth gegen Sandbox-Escapes und Konfigurationsmanipulation.

**Immer blockierte Dateien:**

- Shell-Konfigurationsdateien: `.bashrc`, `.bash_profile`, `.zshrc`, `.zprofile`, `.profile`
- Git-Konfigurationsdateien: `.gitconfig`, `.gitmodules`
- Andere sensible Dateien: `.ripgreprc`, `.mcp.json`

**Immer blockierte Verzeichnisse:**

- IDE-Verzeichnisse: `.vscode/`, `.idea/`
- Claude-Konfigurationsverzeichnisse: `.claude/commands/`, `.claude/agents/`
- Git-Hooks und -Konfiguration: `.git/hooks/`, `.git/config`

Diese Pfade werden automatisch blockiert – Sie müssen sie nicht zu `denyWrite` hinzufügen. Beispielsweise schlägt selbst mit `allowWrite: ["."]` das Schreiben auf `.bashrc` oder `.git/hooks/pre-commit` fehl:```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

- Standard: `3` (durchsucht bis zu 3 Ebenen tief)
- Bereich: `1` bis `10`
- Höhere Werte bieten mehr Schutz, aber langsamere Leistung
- Dateien im aktuellen Arbeitsverzeichnis (Tiefe 0) sind unabhängig von dieser Einstellung immer geschützt

### Unix-Socket-Einschränkungen (Linux)

Unter Linux verwendet die Sandbox **seccomp BPF (Berkeley Packet Filter)**, um die Erstellung von Unix-Domain-Sockets auf Syscall-Ebene zu blockieren. Dies bietet eine zusätzliche Sicherheitsebene, um zu verhindern, dass Prozesse neue Unix-Domain-Sockets für lokale IPC erstellen (sofern nicht ausdrücklich erlaubt).

**So funktioniert es:**

1. **Eingebauter BPF-Filter**: Das Paket enthält eine statische `apply-seccomp`-Binärdatei für x64 und arm64 mit dem darin kompilierten seccomp-BPF-Filter. Der Filter ist architekturspezifisch, aber libc-unabhängig, sodass die Binärdatei sowohl mit glibc als auch mit musl funktioniert.

2. **Laufzeiterkennung**: Die Sandbox erkennt automatisch die Architektur Ihres Systems und verwendet die passende `apply-seccomp`-Binärdatei.

3. **Syscall-Filterung**: Der BPF-Filter fängt den `socket()`-Syscall ab und blockiert die Erstellung von `AF_UNIX`-Sockets, indem er `EPERM` zurückgibt. Dies verhindert, dass sandboxierter Code neue Unix-Domain-Sockets erstellt.

4. **Zweistufige Anwendung mithilfe der apply-seccomp-Binärdatei**:
   - Äußeres bwrap erstellt die Sandbox mit Dateisystem-, Netzwerk- und PID-Namespace-Einschränkungen
   - Netzwerk-Bridge-Prozesse (socat) starten innerhalb der Sandbox (benötigen Unix-Sockets)
   - apply-seccomp erstellt einen verschachtelten User+PID+Mount-Namespace und mountet `/proc` neu
   - Innerhalb des verschachtelten Namespace fungiert apply-seccomp als PID 1 (nicht-dumpbarer Init/Reaper)
   - apply-seccomp forkt, wendet den seccomp-Filter über `prctl()` an und führt den Benutzerbefehl aus
   - Der Benutzerbefehl läuft mit allen Sandbox-Einschränkungen plus Blockierung der Unix-Socket-Erstellung

**PID-Namespace-Isolation**: Der verschachtelte PID-Namespace stellt sicher, dass der Benutzerbefehl keinen Prozess sehen oder adressieren kann, der ohne den seccomp-Filter läuft (bwrap-Init, der Shell-Wrapper oder die socat-Helfer). Dies hält die seccomp-Grenze unabhängig von `kernel.yama.ptrace_scope` intakt, da ungefilterte Helfer über `ptrace` oder `/proc/N/mem` nicht erreichbar sind. Das innere PID 1 setzt `PR_SET_DUMPABLE=0`, sodass es ebenfalls nicht ptracebar ist. Wenn die Erstellung des verschachtelten Namespace fehlschlägt, bricht apply-seccomp ab, anstatt ohne Isolation zu laufen.

**Sicherheitsbeschränkungen**: Der Filter blockiert `socket(AF_UNIX, ...)` sowie die Syscalls `io_uring_setup`/`io_uring_enter`/`io_uring_register` (die letzten drei, weil `IORING_OP_SOCKET` unter Linux 5.19+ andernfalls die `socket()`-Regel umgehen würde). Er verhindert keine Operationen an Unix-Socket-Dateideskriptoren, die von übergeordneten Prozessen geerbt oder über `SCM_RIGHTS` übergeben wurden. Für die meisten Sandbox-Szenarien reicht das Blockieren der Socket-Erstellung aus, um unbefugte IPC zu verhindern.

**Null Laufzeitabhängigkeiten**: Vorgefertigte statische apply-seccomp-Binärdateien und vorab generierte BPF-Filter sind für die Architekturen x64 und arm64 enthalten. Zur Laufzeit sind keine Kompilierungswerkzeuge oder externen Abhängigkeiten erforderlich.

**Architekturunterstützung**: x64 und arm64 werden mit vorgefertigten Binärdateien vollständig unterstützt. Andere Architekturen werden derzeit nicht unterstützt. Um Sandboxing ohne Unix-Socket-Blockierung auf nicht unterstützten Architekturen zu verwenden, setzen Sie `allowAllUnixSockets: true` in Ihrer Konfiguration.

### Erkennung und Überwachung von Verstößen

Wenn ein sandboxierter Prozess versucht, auf eine eingeschränkte Ressource zuzugreifen:

1. **Blockiert die Operation** auf Betriebssystemebene (gibt `EPERM`-Fehler zurück)
2. **Protokolliert den Verstoß** (plattformspezifische Mechanismen)
3. **Benachrichtigt den Benutzer** (in Claude Code wird dadurch eine Berechtigungsabfrage ausgelöst)

**macOS**: Die Sandbox-Laufzeit greift auf den System-Sandbox-Verstoßprotokollspeicher von macOS zu. Dies bietet Echtzeit-Benachrichtigungen mit detaillierten Informationen darüber, was versucht wurde und warum es blockiert wurde. Dies ist derselbe Mechanismus, den Claude Code zur Erkennung von Verstößen verwendet.```bash
# View sandbox violations in real-time
log stream --predicate 'process == "sandbox-exec"' --style syslog

### Erweitert: Eigener Proxy

Für anspruchsvollere Netzwerkfilterung können Sie die Sandbox so konfigurieren, dass sie Ihren eigenen Proxy anstelle der integrierten verwendet. Dies ermöglicht:

- **Datenverkehrsinspektion**: Verwenden Sie Tools wie [mitmproxy](https://mitmproxy.org/), um Datenverkehr zu inspizieren und zu modifizieren
- **Benutzerdefinierte Filterlogik**: Implementieren Sie komplexe Regeln, die über einfache Domain-Allowlists hinausgehen
- **Audit-Protokollierung**: Protokollieren Sie alle Netzwerkanfragen für Compliance oder Debugging

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

Privilegieneskalation über Unix-Sockets: Die Konfiguration allowUnixSockets kann versehentlich Zugriff auf leistungsstarke Systemdienste gewähren, die zu Sandbox-Umgehungen führen können. Wenn sie beispielsweise verwendet wird, um Zugriff auf /var/run/docker.sock zu gewähren, würde dies effektiv Zugriff auf das Hostsystem durch Ausnutzung des Docker-Sockets ermöglichen. Benutzer werden ermutigt, sorgfältig zu überlegen, welche Unix-Sockets sie durch die Sandbox zulassen.
Eskalation von Dateisystemberechtigungen: Übermäßig breite Schreibberechtigungen im Dateisystem können Privilegieneskalationsangriffe ermöglichen. Das Zulassen von Schreibzugriffen auf Verzeichnisse mit ausführbaren Dateien in $PATH, Systemkonfigurationsverzeichnisse oder Benutzer-Shell-Konfigurationsdateien (.bashrc, .zshrc) kann zur Codeausführung in unterschiedlichen Sicherheitskontexten führen, wenn andere Benutzer oder Systemprozesse auf diese Dateien zugreifen.
Stärke der Linux-Sandbox: Die Linux-Implementierung bietet eine starke Dateisystem- und Netzwerkisolation, enthält jedoch einen Modus enableWeakerNestedSandbox, der die Ausführung in Docker-Umgebungen ohne privilegierte Namespaces ermöglicht. Diese Option schwächt die Sicherheit erheblich und sollte nur in Fällen verwendet werden, in denen anderweitig zusätzliche Isolation durchgesetzt wird.
Schwächere Netzwerkisolation (macOS): Die Option enableWeakerNetworkIsolation aktiviert den Zugriff auf com.apple.trustd.agent wieder, der für Go-Programme erforderlich ist, um TLS-Zertifikate über das macOS-Security-Framework zu verifizieren. Dies eröffnet einen potenziellen Datenextfiltrationsvektor über den trustd-Dienst und sollte nur aktiviert werden, wenn eine Go-TLS-Verifizierung erforderlich ist (z. B. bei Verwendung von httpProxyPort mit einem MITM-Proxy und benutzerdefinierter CA).
Apple Events (macOS): Die Option allowAppleEvents aktiviert das Senden von Apple Events und Launch-Services-Öffnungsanfragen wieder ((allow appleevent-send), (allow lsopen) sowie Mach-Lookups für com.apple.coreservices.appleevents, com.apple.CoreServices.coreservicesd und com.apple.coreservices.quarantine-resolver), die open, osascript und URL-öffnende Helfer benötigen. Mit diesen erlaubten Funktionen kann ein sandboxierter Befehl beliebige Anwendungen ohne Benutzeraufforderung starten, und gestartete Anwendungen laufen vollständig außerhalb der Sandbox – diese Option entfernt also die Codeausführungsisolation, nicht nur schwächt sie sie. Das Skripten bereits laufender Anwendungen über Apple Events wird zusätzlich durch die macOS-TCC-Automatisierungseinwilligung eingeschränkt, das Starten über open jedoch nicht. Aktivieren Sie dies nur, wenn Befehle innerhalb der Sandbox tatsächlich URLs oder Anwendungen öffnen müssen.

Beliebteste

sandbox-runtime

Übersicht

Anwendungsbeispiel: Sandboxing von MCP-Servern

Funktionsweise

Duales Isolationsmodell

Architektur```

Als Bibliothek```typescript

Verfügbare Exporte```typescript

Vollständiges Konfigurationsbeispiel```json

Dateisystem-Konfiguration

Weitere Konfiguration

Allgemeine Konfigurationsrezepte

Plattformunterstützung

Plattformspezifische Abhängigkeiten

Sicherheitsmodell

TLS-Terminierung unter Windows

Entwicklung```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

Sicherheitsbeschränkungen

Bekannte Einschränkungen und zukünftige Arbeiten