Bash-Sandbox auf macOS (sandbox-exec) und Linux (bubblewrap)

[webmatze]

Priorität: 3 — ambitioniert, aber die eigentliche Antwort auf Approval-Fatigue und ein echtes Alleinstellungsmerkmal für ein lokales Harness. Setzt das Permissions-Issue voraus.

Referenz: Claude Code v2.0.24 (Sandbox-Modus für BashTool auf Linux & macOS), v2.0.30 (allowUnsandboxedCommands), v2.1.187 (sandbox.credentials), v2.1.216 (Dateisystem-Isolation abschaltbar bei erhaltener Netzkontrolle), v2.1.219 (strikte Netzwerk-Allowlist), v2.1.221 (File-Masking), v2.1.224 (Credential-Masking) — dass Anthropic hier über zehn Releases nachgeschärft hat, zeigt zugleich, wie fehleranfällig das Thema ist.

Motivation

Das Approval-Modell hat eine unangenehme Eigenschaft: Es fragt bei jedem mutierenden Call. In der Praxis führt das dazu, dass Nutzer nach kurzer Zeit --yes setzen — und damit jede Schutzwirkung aufgeben. Feinere Regeln (Permissions-Issue) mildern das, lösen es aber nicht: Sie beschreiben, was erlaubt ist, erzwingen es aber nicht auf Betriebssystemebene.

Eine Sandbox dreht das Verhältnis um: Statt bei jedem Schreibzugriff zu fragen, wird bash in einer Umgebung ausgeführt, in der ein Ausbruch aus dem Projektverzeichnis oder ein unerwarteter Netzzugriff technisch nicht möglich ist. Dann kann man die meisten Kommandos bedenkenlos ohne Nachfrage laufen lassen.

Für ein Werkzeug, das sich als „local-first" positioniert, ist das ein starkes Argument: Der Nutzer gibt einem Agenten Shell-Zugriff, ohne die Maschine preiszugeben.

Spezifikation

Plattformen

Plattform	Mechanismus
macOS	sandbox-exec mit generiertem SBPL-Profil
Linux	bubblewrap (bwrap), falls vorhanden; sonst nicht verfügbar
sonst	nicht verfügbar

Kein eigener Kernel-Kram, keine Container-Abhängigkeit. Ist der Mechanismus nicht verfügbar, bleibt es beim heutigen Approval-Verhalten — mit einem klaren Hinweis, dass die Sandbox inaktiv ist. Ein Feature, das vorgibt zu schützen, es aber nicht tut, ist gefährlicher als keines.

Konfiguration

[sandbox]
enabled = false                # Default: aus, Opt-in
filesystem = true              # Schreibzugriff auf Projekt + tmp beschränken
network = "deny"               # deny | allow | allowlist
network_allowlist = ["registry.npmjs.org", "github.com"]
writable = [".", "/tmp"]       # zusätzliche Schreibpfade
allow_unsandboxed = true       # darf ein Call die Sandbox explizit umgehen?

Verhalten

• Gilt zunächst nur für bash. write_file/edit_file laufen weiter über Permission-Regeln — dort ist der Pfad bekannt und prüfbar, eine Sandbox bringt wenig zusätzlichen Schutz.
• Bei aktiver Sandbox können Kommandos ohne Nachfrage laufen ([approval] mode = "auto" wird dadurch vertretbar). Das ist der eigentliche Gewinn und sollte im README so erklärt werden.
• Escape-Hatch: Ein Tool-Parameter sandbox: false erlaubt einem einzelnen Call den Ausbruch — immer mit Approval-Prompt, unabhängig vom Modus, und abschaltbar über allow_unsandboxed = false (CC v2.0.30).

macOS-Profil (Skizze)

(version 1)
(deny default)
(allow process-exec process-fork)
(allow file-read*)                                  ; Lesen breit erlauben
(allow file-write* (subpath "/path/to/project"))
(allow file-write* (subpath "/tmp"))
(deny file-read* (subpath "/Users/x/.ssh"))         ; Credentials trotz Lesefreigabe sperren
(deny network*)

Anmerkungen:

• Lesen breit zu erlauben ist pragmatisch — Compiler und Toolchains lesen an vielen Stellen. Der Schutz liegt auf Schreiben und Netz.
• Credential-Pfade (~/.ssh, ~/.aws, ~/.config/gh, .env) müssen trotzdem explizit gesperrt werden, sonst kann ein Kommando Secrets lesen und über einen erlaubten Netzpfad exfiltrieren. Das ist genau der Punkt, den CC in v2.1.187 und v2.1.224 nachgezogen hat.
• sandbox-exec ist von Apple als deprecated markiert, funktioniert aber weiterhin und wird von anderen Werkzeugen genutzt. Das Risiko ist zu dokumentieren.

Linux (bubblewrap)

bwrap --ro-bind / / --bind <project> <project> --bind /tmp /tmp \
      --unshare-net --dev /dev --proc /proc -- <command>

Netz-Allowlist ist mit --unshare-net nur als „ganz aus" umsetzbar. Für allowlist bräuchte es einen Proxy im Namespace — das ist eine Ausbaustufe, nicht Teil dieses Issues. Stufe 1 unterstützt deny und allow; allowlist wird auf macOS ebenfalls zunächst als deny behandelt und muss dann eine klare Warnung ausgeben statt stillschweigend etwas anderes zu tun.

Umsetzung

Neue Dateien

src/smith/sandbox.cr             # Abstraktion + Verfügbarkeitsprüfung
src/smith/sandbox/macos.cr       # SBPL-Generierung, sandbox-exec
src/smith/sandbox/linux.cr       # bwrap-Argumente

module Smith::Sandbox
  abstract class Backend
    abstract def available? : Bool
    abstract def wrap(command : String, settings : Settings) : Array(String)
  end

  def self.detect : Backend?
end

Änderungen

• src/smith/tools/bash.cr: Kommando durch das Backend wrappen; sandbox-Parameter
• src/smith/config.cr: [sandbox]-Sektion
• src/smith/cli.cr: Verfügbarkeit prüfen, Status im Banner (🔒 Sandbox: macOS (network: deny) bzw. deutlicher Hinweis bei Nichtverfügbarkeit trotz enabled = true)

Tests (spec/sandbox_spec.cr)

Die Profilgenerierung ist plattformunabhängig testbar; die tatsächliche Durchsetzung nur auf der jeweiligen Plattform (in CI entsprechend markieren/überspringen).

• SBPL enthält die konfigurierten Schreibpfade und die Credential-Deny-Regeln
• bwrap-Argumente korrekt zusammengesetzt
• Projektpfad mit Leerzeichen wird korrekt gequotet
• available? liefert auf einer Plattform ohne Backend false
• enabled = true ohne Backend → Warnung, Ausführung ungesandboxt, nicht stiller Weiterlauf
• sandbox: false erzwingt einen Approval-Prompt auch bei mode = "auto"
• allow_unsandboxed = false lehnt sandbox: false ab
• Integrationstest (nur macOS/Linux): Schreibversuch außerhalb des Projekts schlägt fehl; Schreiben im Projekt gelingt; Netzzugriff bei network = "deny" schlägt fehl

Akzeptanzkriterien

• macOS- und Linux-Backend, sauberes Fallback auf anderen Plattformen
• Nichtverfügbarkeit wird laut gemeldet, nie stillschweigend übergangen
• Credential-Pfade sind auch bei breitem Lesezugriff gesperrt
• Escape-Hatch nur mit Approval und abschaltbar
• allowlist wird nicht vorgetäuscht, solange sie nicht umgesetzt ist
• Integrationstests belegen die tatsächliche Durchsetzung auf mindestens einer Plattform
• README-Abschnitt „Sandbox" inkl. ehrlicher Grenzen und Deprecation-Hinweis zu sandbox-exec

Nicht-Ziele

• Vollständige Container-Isolation
• Sandboxing der Datei-Tools (dort greifen Permission-Regeln)
• Netz-Allowlist über einen Proxy (Ausbaustufe)

[webmatze]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: bash in einer OS-erzwungenen Sandbox ausführen — sandbox-exec auf macOS, bubblewrap auf Linux, sauberes Nichtstun sonst.

Verifiziert auf dieser Maschine (macOS 26.5.2)

sandbox-exec ist trotz Apples Deprecation vorhanden und erzwingt tatsächlich:

Test	Ergebnis
Schreiben im erlaubten Subpath	gelingt
Schreiben außerhalb	Operation not permitted, Datei entsteht nicht
curl https://example.com unter (deny network*)	HTTP-Code 000, blockiert
ls ~/.ssh unter (allow file-read*)	listet den Inhalt

Die letzte Zeile ist der Grund, warum die Credential-Regeln kein Feinschliff sind, sondern tragend: Breiter Lesezugriff legt Secrets offen. Mit (deny file-read* (subpath "<home>/.ssh")) ist der Zugriff blockiert — und zwar unabhängig von der Regelreihenfolge, vor oder nach dem breiten allow getestet. Die Profilgenerierung muss sich also nicht um Reihenfolge sorgen.

Zwei Korrekturen an der Spezifikation

1. writable = [".", "/tmp"] funktioniert auf macOS nicht. Verifiziert: mit ausschließlich (allow file-write* (subpath "/tmp")) scheitert ein Schreibversuch nach /tmp mit Operation not permitted, weil /tmp ein Symlink auf private/tmp ist und die Sandbox den aufgelösten Pfad bewertet. Mit (subpath "/private/tmp") gelingt derselbe Schreibvorgang. Jeder konfigurierte Pfad muss vor dem Einsetzen ins Profil durch eine Realpath-Auflösung gehen — auch das Projektverzeichnis selbst, das auf macOS unter /tmp oder über ein Symlink liegen kann. Ohne das liefert die Default-Konfiguration eine Sandbox, die Temp-Dateien blockiert, und das liest sich als „Sandbox kaputt", nicht als „Profil falsch". Pfade mit Leerzeichen sind unkritisch, in SBPL-Strings korrekt gequotet getestet.

2. Der Wrap gehört nicht in das bash-Tool. Das Tool startet keinen Prozess — es delegiert jedes Kommando, Vordergrund wie Hintergrund, an den Job-Manager, und dort gibt es genau eine Spawn-Stelle (/bin/bash -c <command>). Wird dort gewrappt, sind Hintergrund-Jobs und in den Hintergrund verschobene Timeout-Kommandos automatisch mit abgedeckt. Im Tool gewrappt müsste es zweimal passieren oder würde die Hintergrundfälle verlieren.

Entschieden: die Credential-Deny-Liste ist eingebaut und nicht abschaltbar

smith bringt eine feste Liste mit, die bei aktiver Sandbox immer gilt: ~/.ssh, ~/.aws, ~/.gnupg, ~/.config/gh, ~/.netrc, ~/.docker/config.json, ~/.kube sowie .env-Dateien im Projekt. Konfiguration kann Pfade hinzufügen, aber keine entfernen. Begründung: Ein Schutz, den man abschalten kann, wird abgeschaltet — und der Lesezugriff auf Secrets ist in Verbindung mit erlaubtem Netz genau der Weg, den die Sandbox schließen soll. Kein Config-Feld für Ausnahmen.

Current behavior

Jedes bash-Kommando läuft mit den vollen Rechten des Nutzers. Der Schutz liegt allein im Approval-Gate, das vor jedem mutierenden Call fragt; die Permission-Regeln beschreiben, was erlaubt ist, erzwingen es aber nicht. Wer --yes setzt, hat keinen Schutz mehr. Es gibt keine [sandbox]-Konfiguration und keine Sandbox-Abstraktion.

Desired behavior

Bei aktivierter Sandbox läuft jedes bash-Kommando in einer Umgebung, in der Schreibzugriffe außerhalb der konfigurierten Pfade und — je nach Einstellung — Netzzugriffe technisch unmöglich sind. Ist der Mechanismus der Plattform nicht verfügbar, läuft smith wie heute weiter, sagt aber laut, dass die Sandbox inaktiv ist. Ein einzelner Call kann per Tool-Parameter ausbrechen, aber nur mit Approval-Prompt, und der Ausbruch lässt sich global verbieten. Ist die Sandbox aus (Default), ändert sich nichts am heutigen Verhalten.

Key interfaces

• Eine Sandbox-Abstraktion mit einer Verfügbarkeitsprüfung und einer Methode, die ein Kommando in die Argumentliste des jeweiligen Mechanismus übersetzt, plus einer Erkennung, die das passende Backend für die laufende Plattform liefert oder nil. Backends für macOS und Linux; auf allen anderen Plattformen keins.
• macOS-Backend: generiert ein SBPL-Profil (deny default, process-exec/process-fork erlaubt, breiter Lesezugriff, Schreibzugriff nur auf die realpath-aufgelösten Pfade, die eingebaute Credential-Deny-Liste, Netzregel nach Konfiguration) und ruft sandbox-exec -f <profil> davor. Das Profil ist eine temporäre Datei pro Prozesslauf, nicht pro Call neu geschrieben.
• Linux-Backend: setzt bwrap-Argumente zusammen — Root read-only gebunden, die Schreibpfade beschreibbar gebunden, --dev/--proc, und --unshare-net bei network = "deny". Verfügbar nur, wenn bwrap im PATH liegt.
• Konfiguration als eigener Abschnitt mit den Feldern aus dem Issue-Body — ohne ein Feld zum Entfernen von Credential-Denies. Default enabled = false, also reines Opt-in.
• Der Job-Manager wrappt an seiner einzigen Spawn-Stelle. Das Kommando selbst wird nicht verändert, nur davor gesetzt.
• Der Tool-Parameter zum Ausbrechen ist ein Boolean am bash-Tool. Ein Call, der ihn setzt, erzwingt einen Approval-Prompt, auch wenn der Modus sonst nichts fragt. Ist der Ausbruch global verboten, wird der Call abgelehnt, nicht stillschweigend gesandboxt ausgeführt — sonst glaubt das Modell, es sei ausgebrochen.
• Netz-Allowlist wird nicht vorgetäuscht. network = "allowlist" verhält sich in dieser Stufe auf beiden Plattformen wie deny und gibt beim Start eine Warnung aus, die genau das sagt. Kein Proxy, keine Teilumsetzung.
• Bannerausgabe: bei aktiver Sandbox eine Zeile mit Backend und Netzmodus. Bei enabled = true ohne verfügbares Backend eine deutliche Warnung, dass ungesandboxt ausgeführt wird — nicht als Fußnote, sondern so sichtbar wie die MCP-Warnungen.

Acceptance criteria

• Auf macOS läuft ein bash-Kommando unter sandbox-exec; ein Schreibversuch außerhalb der konfigurierten Pfade scheitert, einer innerhalb gelingt
• Bei network = "deny" scheitert ein Netzzugriff aus einem bash-Kommando
• Alle Pfade im generierten Profil sind realpath-aufgelöst; ein Test belegt, dass writable = ["/tmp"] auf macOS zu einer Regel auf dem aufgelösten Pfad führt und ein Schreibvorgang nach /tmp gelingt
• Ein Lesezugriff auf jeden Pfad der eingebauten Credential-Liste scheitert bei aktiver Sandbox, obwohl Lesen sonst breit erlaubt ist
• Es gibt keinen Konfigurationsweg, einen Pfad aus der Credential-Liste zu entfernen
• Die generierten bwrap-Argumente sind plattformunabhängig testbar und enthalten die erwarteten Bindungen; der Durchsetzungstest läuft nur auf Linux
• Fehlt bwrap in der CI, wird der Linux-Durchsetzungstest mit sichtbarer Meldung übersprungen, nie stillschweigend als bestanden gewertet
• Ein Projektpfad mit Leerzeichen funktioniert auf beiden Plattformen
• enabled = true ohne verfügbares Backend führt ungesandboxt aus und warnt deutlich
• Der Ausbruchs-Parameter erzwingt einen Approval-Prompt auch in einem Modus, der sonst nichts fragt
• Ist der Ausbruch global verboten, wird ein Call, der ihn verlangt, abgelehnt
• network = "allowlist" warnt und verhält sich wie deny
• Hintergrund-Jobs und in den Hintergrund verschobene Timeout-Kommandos sind ebenso gesandboxt wie Vordergrundkommandos
• enabled = false (Default) erzeugt exakt das heutige Verhalten; die bestehenden bash-Specs bleiben unverändert grün
• crystal spec grün auf beiden CI-Plattformen, crystal tool format sauber
• README-Abschnitt „Sandbox" mit den tatsächlichen Grenzen, dem Deprecation-Hinweis zu sandbox-exec und der Aussage, dass Lesen breit erlaubt bleibt

Out of scope

• Sandboxing von write_file/edit_file — dort greifen die Permission-Regeln, der Pfad ist vorher bekannt
• Netz-Allowlist über einen Proxy im Namespace
• Vollständige Container-Isolation, eigene Kernel-Mechanismen, Docker
• Sandboxing der Hook-Kommandos und der MCP-Server-Prozesse (eigene Frage, eigene Vertrauensstellung)
• Automatische Erkennung, welche Pfade ein Build-Tool braucht
• Ein Sandbox-Default von true — das ist eine eigene Entscheidung, nachdem das hier im Alltag stand