Claude Code in einem Devcontainer

Eine sandbox-Entwicklungsumgebung zum sicheren Ausführen von Claude Code mit bypassPermissions. Entwickelt bei Trail of Bits für Sicherheitsaudit-Workflows.

Warum dies nutzen?

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:

• Sicherheitsaudits: Überprüfen Sie Client-Code, ohne Ihr Hostsystem zu gefährden
• Nicht vertrauenswürdige Repositories: Erkunden Sie unbekannte Codebasen sicher
• Experimentelle Arbeit: Lassen Sie Claude in Isolation Code frei modifizieren
• Multi-Repo-Engagements: Arbeiten Sie an mehreren zusammenhängenden Repositories

Voraussetzungen

• Docker-Laufzeitumgebung (eine von):

  • Docker Desktop – stellen Sie sicher, dass es läuft
  • OrbStack
  • Colima: brew install colima docker && colima start

• Für Terminal-Workflows (einmalige Installation):

  root@kitploit:~

  npm install -g @devcontainers/cli
  git clone https://github.com/trailofbits/claude-code-devcontainer ~/.claude-devcontainer
  ~/.claude-devcontainer/install.sh self-install
  

# 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

Schnellstart

Wählen Sie das Muster, das zu Ihrem Workflow passt:

Muster A: Container pro Projekt (Isoliert)

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:

1. Installieren Sie die Dev Containers-Erweiterung:

   • VS Code: ms-vscode-remote.remote-containers
   • Cursor: anysphere.remote-containers

2. Richten Sie den Devcontainer ein (wählen Sie eine Option):

   root@kitploit:~

   # Option A: Use devc (recommended)
   devc .
   
   # Option B: Clone manually
   git clone https://github.com/trailofbits/claude-code-devcontainer .devcontainer/
   

3. Öffnen Sie Ihren Projektordner in VS Code, dann:

   • Drücken Sie Cmd+Shift+P (Mac) oder Ctrl+Shift+P (Windows/Linux)
   • Geben Sie "Reopen in Container" ein und wählen Sie Dev Containers: Reopen in Container

Muster B: Gemeinsamer Workspace-Container (Gruppiert)

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

Token-basierte Authentifizierung (Headless)

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.

CLI-Hilfebefehle

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, die devc destroy nicht finden kann.

Sitzungssynchronisation für /insights

Der 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.

Dateifreigabe

VS Code / Cursor

Ziehen Sie Dateien von Ihrem Host in das VS Code Explorer-Panel – sie werden automatisch in /workspace/ kopiert. Keine Konfiguration erforderlich.

Terminal: devc mount

Um 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, --readonly ist angegeben, was die Dateisystem-Isolation untergräbt, die dieses Projekt bietet.

Netzwerkisolation

Standardmäßig haben Container vollen ausgehenden Netzwerkzugriff. Für strengere Sicherheit verwenden Sie iptables, um den Netzwerkzugriff einzuschränken.

Wann Netzwerkisolation aktivieren

• Überprüfen von Code, der bösartige Abhängigkeiten enthalten könnte
• Auditieren von Software mit Telemetrie- oder Phone-Home-Verhalten
• Maximale Isolation für hochsensible Überprüfungen

Beispiel: Claude + GitHub + Paketregistries

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

Kompromisse

• Blockiert Paketmanager, es sei denn, Sie setzen Registries auf die Whitelist
• Kann Tools beeinträchtigen, die Netzwerkzugriff benötigen
• DNS-Auflösung funktioniert weiterhin (in Erwägung ziehen, zu blockieren, wenn paranoid)

Bedrohungsmodell

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.

Sicherheitsmodell

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.

Container-Details

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.

Fehlerbehebung

"devcontainer CLI nicht gefunden"

npm install -g @devcontainers/cli

Container startet nicht

1. Überprüfen Sie, ob Docker läuft
2. Versuchen Sie neu zu erstellen: devc rebuild
3. Überprüfen Sie die Logs: docker logs $(docker ps -lq)

GitHub CLI-Authentifizierung bleibt nicht erhalten

Das gh-Volume benötigt möglicherweise eine Besitzerkorrektur:

sudo chown -R $(id -u):$(id -g) ~/.config/gh

Python/uv funktioniert nicht

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

Entwicklung

Image manuell erstellen:

devcontainer build --workspace-folder .

Container testen:

devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . zsh