trailofbits/claude-code-devcontainerSandbox-Devcontainer für die sichere Ausführung von Claude Code im Bypass-Modus. Entwickelt für Sicherheitsaudits und die Überprüfung von nicht vertrauenswürdigem Code.
Eine sandbox-Entwicklungsumgebung zum sicheren Ausführen von Claude Code mit bypassPermissions. Entwickelt bei Trail of Bits für Sicherheitsaudit-Workflows.
Claude mit bypassPermissions auf Ihrem Host-Computer auszuführen ist riskant – es kann ohne Bestätigung beliebige Befehle ausführen. Dieser Devcontainer bietet Dateisystem-Isolation, sodass Sie die Produktivitätsvorteile von uneingeschränktem Claude nutzen, ohne Ihr Hostsystem zu gefährden.
Konzipiert für:
Docker-Laufzeitumgebung (eine von):
brew install colima docker && colima startFür Terminal-Workflows (einmalige Installation):
npm install -g @devcontainers/cli
git clone https://github.com/trailofbits/claude-code-devcontainer ~/.claude-devcontainer
~/.claude-devcontainer/install.sh self-install
Colimas Standardeinstellungen (QEMU + sshfs) sind konservativ. Für eine bessere Leistung:
# Stop and delete current VM (removes containers/images)
colima stop && colima delete
# Start with optimized settings
colima start \
--cpu 4 \
--memory 8 \
--disk 100 \
--vm-type vz \
--vz-rosetta \
--mount-type virtiofs
Passen Sie --cpu und --memory je nach Ihrem Mac an (z. B. 6/16 für Pro, 8/32 für Max).
| Option | Vorteil |
|---|---|
--vm-type vz | Apple Virtualization.framework (schneller als QEMU) |
--mount-type virtiofs | 5-10x schnellerer Datei-I/O als sshfs |
--vz-rosetta | x86-Container via Rosetta ausführen |
Überprüfen Sie mit colima status – es sollte "macOS Virtualization.Framework" und "virtiofs" anzeigen.
Wählen Sie das Muster, das zu Ihrem Workflow passt:
Jedes Projekt erhält einen eigenen Container mit unabhängigen Volumes. Am besten geeignet für einmalige Überprüfungen, nicht vertrauenswürdige Repos oder wenn Sie Isolation zwischen Projekten benötigen.
Terminal:
git clone <untrusted-repo>
cd untrusted-repo
devc . # Installs template + starts container
devc shell # Opens shell in container
VS Code / Cursor:
Installieren Sie die Dev Containers-Erweiterung:
ms-vscode-remote.remote-containersanysphere.remote-containersRichten Sie den Devcontainer ein (wählen Sie eine Option):
# Option A: Use devc (recommended)
devc .
# Option B: Clone manually
git clone https://github.com/trailofbits/claude-code-devcontainer .devcontainer/
Öffnen Sie Ihren Projektordner in VS Code, dann:
Cmd+Shift+P (Mac) oder Ctrl+Shift+P (Windows/Linux)Ein übergeordnetes Verzeichnis enthält die Devcontainer-Konfiguration, und Sie klonen mehrere Repos darin. Gemeinsame Volumes über alle Repos hinweg. Am besten geeignet für Kunden-Engagements, zusammenhängende Repositories oder laufende Arbeiten.
# Create workspace for a client engagement
mkdir -p ~/sandbox/client-name
cd ~/sandbox/client-name
devc . # Install template + start container
devc shell # Opens shell in container
# Inside container:
git clone <client-repo-1>
git clone <client-repo-2>
cd client-repo-1
claude # Ready to work
Für headless-Server oder zum Überspringen des interaktiven Login-Assistenten:
claude setup-token # run on host, one-time
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
devc rebuild # rebuilds with token
Das Token wird in den Container weitergeleitet. Bei jeder Containererstellung führt post_install.py einen einmaligen Authentifizierungs-Handshake durch, sodass claude ohne den Login-Assistenten startet.
Dies umgeht den interaktiven Onboarding-Assistenten von Claude Code, der in Containern immer angezeigt wird, selbst mit gültigen Anmeldeinformationen (#8938).
Wenn Sie kein Token setzen, funktioniert der interaktive Login-Ablauf wie zuvor.
devc . Vorlage installieren + Container im aktuellen Verzeichnis starten
devc up Devcontainer starten
devc rebuild Container neu erstellen (behält persistente Volumes)
devc destroy [-f] Container, Volumes und Image für aktuelles Projekt entfernen
devc down Container anhalten
devc shell zsh-Shell im Container öffnen
devc exec CMD Befehl im Container ausführen
devc upgrade Claude Code im Container aktualisieren
devc mount SRC DST Bind-Mount hinzufügen (Host → Container)
devc sync [NAME] Claude Code-Sitzungen von Devcontainern auf den Host synchronisieren
devc template DIR Devcontainer-Dateien in Verzeichnis kopieren
devc self-install devc nach ~/.local/bin installieren
Hinweis: Verwenden Sie
devc destroy, um die Docker-Ressourcen eines Projekts zu bereinigen. Das manuelle Entfernen von Containern (z. B.docker rm) hinterlässt verwaiste Volumes und Images, diedevc destroynicht finden kann.
/insightsDer Befehl /insights von Claude Code analysiert Ihren Sitzungsverlauf, liest aber nur von ~/.claude/projects/ auf dem Host. Sitzungen in Devcontainer-Volumes sind für ihn unsichtbar.
devc sync kopiert Sitzungsprotokolle von allen Devcontainern (laufende und gestoppte) auf den Host, sodass /insights sie einbeziehen kann:
devc sync # Sync all devcontainers
devc sync crypto # Filter by project name (substring match)
Devcontainer werden automatisch über Docker-Labels erkannt – es ist nicht nötig, Containernamen oder -IDs zu kennen. Die Synchronisation ist inkrementell, daher kann sie wiederholt ausgeführt werden.
Ziehen Sie Dateien von Ihrem Host in das VS Code Explorer-Panel – sie werden automatisch in /workspace/ kopiert. Keine Konfiguration erforderlich.
devc mountUm ein Host-Verzeichnis im Container verfügbar zu machen:
devc mount ~/drop /drop # Read-write
devc mount ~/secrets /secrets --readonly
Dies fügt einen Bind-Mount zu devcontainer.json hinzu und erstellt den Container neu. Vorhandene Mounts bleiben bei devc template-Aktualisierungen erhalten.
Tipp: Ein gemeinsamer "Drop-Ordner" ist nützlich, um Dateien zu übergeben, ohne Ihr gesamtes Home-Verzeichnis zu mounten.
Sicherheitshinweis: Vermeiden Sie das Mounten großer Host-Verzeichnisse (z. B.
$HOME). Jeder gemountete Pfad ist von innen schreibbar, es sei denn,--readonlyist angegeben, was die Dateisystem-Isolation untergräbt, die dieses Projekt bietet.
Standardmäßig haben Container vollen ausgehenden Netzwerkzugriff. Für strengere Sicherheit verwenden Sie iptables, um den Netzwerkzugriff einzuschränken.
sudo iptables -A OUTPUT -d api.anthropic.com -j ACCEPT
sudo iptables -A OUTPUT -d github.com -j ACCEPT
sudo iptables -A OUTPUT -d raw.githubusercontent.com -j ACCEPT
sudo iptables -A OUTPUT -d registry.npmjs.org -j ACCEPT
sudo iptables -A OUTPUT -d pypi.org -j ACCEPT
sudo iptables -A OUTPUT -d files.pythonhosted.org -j ACCEPT
sudo iptables -A OUTPUT -o lo -j ACCEPT
sudo iptables -A OUTPUT -j DROP
Die primäre Bedrohung, die dieses Projekt adressiert, ist Claude Code, das beliebige Befehle auf Ihrem Host-Computer ausführt. Wenn bypassPermissions aktiviert ist, führt Claude Shell-Befehle aus, installiert Pakete und modifiziert Dateien ohne Bestätigung. Auf einem Host-Computer bedeutet dies, dass es Ihre Shell-Konfiguration ändern, außerhalb des Projektverzeichnisses rm -rf ausführen oder lokal gespeicherte Anmeldeinformationen missbrauchen kann. Der Devcontainer schränkt all dies auf einen wegwerfbaren Container ein, in dem der Explosionsradius auf /workspace begrenzt ist.
Der Container enthält gängige Entwicklungswerkzeuge, sodass Sie die gesamte Entwicklungsarbeit darin erledigen können – nicht nur Claude ausführen. Der beabsichtigte Workflow ist: Repository klonen, Devcontainer starten und vollständig darin arbeiten. Wenn Ihr Projekt zusätzliche Laufzeiten oder Tools erfordert, die nicht enthalten sind, fügen Sie sie entweder dem Dockerfile für wiederholte Nutzung hinzu oder installieren Sie sie ad-hoc mit devc exec.
Für die spezifischen Grenzen dessen, was isoliert ist und was nicht, siehe Security Model unten. Eine Nuance, die erwähnenswert ist: Die Devcontainer-Laufzeitumgebung leitet automatisch den SSH-Agent-Socket (SSH_AUTH_SOCK) Ihres Hosts in den Container. Dadurch kann Code im Container sich über SSH als Sie authentifizieren (z. B. git push), aber das eigentliche private Schlüsselmaterial bleibt auf dem Host und wird dem Container nie ausgesetzt.
Dieser Devcontainer bietet Dateisystem-Isolation, aber kein vollständiges Sandboxing.
Sandboxed: Dateisystem (Host-Dateien nicht zugänglich), Prozesse (vom Host isoliert), Paketinstallationen (bleiben im Container)
Nicht sandboxed: Netzwerk (standardmäßig voll ausgehend – siehe Network Isolation), Git-Identität (~/.gitconfig schreibgeschützt gemountet), SSH-Agent (Socket weitergeleitet, Schlüssel bleiben auf dem Host), Docker-Socket (standardmäßig nicht gemountet)
Der Container konfiguriert automatisch den bypassPermissions-Modus – Claude führt Befehle ohne Bestätigung aus. Dies wäre auf einem Host-Computer riskant, aber der Container selbst ist die Sandbox.
| Komponente | Details |
|---|---|
| Basis | Ubuntu 24.04, Node.js 22, Python 3.13 + uv, zsh |
| Benutzer | vscode (passwortloses sudo), Arbeitsverzeichnis /workspace |
| Tools | rg, fd, tmux, fzf, delta, iptables, ipset |
| Volumes (überstehen Neuerstellungen) | Befehlsverlauf (/commandhistory), Claude-Konfiguration (~/.claude), GitHub CLI-Authentifizierung (~/.config/gh) |
| Host-Mounts | ~/.gitconfig (schreibgeschützt), .devcontainer/ (schreibgeschützt) |
| Automatisch konfiguriert | anthropics + trailofbits Fähigkeiten, git-delta |
Volumes werden außerhalb des Containers gespeichert, sodass Ihr Shell-Verlauf, Claude-Einstellungen und gh-Login auch nach devc rebuild erhalten bleiben. Das Host-~/.gitconfig ist für die Git-Identität schreibgeschützt gemountet.
npm install -g @devcontainers/cli
devc rebuilddocker logs $(docker ps -lq)Das gh-Volume benötigt möglicherweise eine Besitzerkorrektur:
sudo chown -R $(id -u):$(id -g) ~/.config/gh
Python wird über uv verwaltet:
uv run script.py # Run a script
uv add package # Add project dependency
uv run --with requests py.py # Ad-hoc dependency
Image manuell erstellen:
devcontainer build --workspace-folder .
Container testen:
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . zsh