Enterprise AI Agent Sandbox

Ein Sicherheitsframework zum Einbinden von Sandbox-Ausführung in agentische KI-Workflows. Legen Sie den Connector in einen beliebigen Ordner, in dem Claude Code, Codex, Cursor oder andere KI-Agenten ausgeführt werden – alle privilegierten Befehle werden an einen menschlichen Genehmiger eskaliert, außerhalb des Agentenkontexts ausgeführt, und die Ausgabe wird an das Modell zurückgegeben, damit es fortfahren kann.

Architektur

Der Ordner-Connector verbindet die Sandbox mit Ihrem Projekt:

• Claude Code-Hooks fangen Tool-Aufrufe ab, eskalieren privilegierte Operationen an einen menschlichen Genehmiger und geben die erfasste Ausgabe in einer deny-Entscheidung zurück, sodass das Tool nie mit Agentenrechten ausgeführt wird.

• MCP-Server (run_privileged, check_request, sandbox_status) bietet dieselbe Schleife über das Model Context Protocol – funktioniert mit Claude Code, Codex, Cursor, Windsurf

• Ordner-Warteschlange (.sandbox/escalations/) ist der Bus: atomare Dateioperationen (os.replace, os.rename) koordinieren die Genehmigung über vier unabhängige Prozesse (Hook-Subprozess, MCP-Server, Genehmiger-Terminal, Dashboard)

• Policy-Engine klassifiziert Shell-Befehle, Dateischreibvorgänge, Netzwerkanfragen und Lesevorgänge – vier Eskalationsauslöser mit Human-in-the-Loop als oberster Stufe

Related MCP server: Approval Gate

Schnellstart

# Install the connector
python -m pip install -e ".[dev]"

# Initialize a folder
sandbox init . --claude --mcp

# In one terminal: watch for escalations
sandbox watch .

# In another: use Claude Code or the MCP tools as normal
# Privileged commands will appear in the `watch` terminal for approval

So funktioniert es

1. Agent versucht, einen Befehl auszuführen – Claude Codes PreToolUse-Hook fängt ihn ab

2. Hook klassifiziert und eskaliert – Shell-Befehle, die nicht in der Zulassungsliste stehen, gehen in die Ordner-Warteschlange

3. Mensch genehmigt in sandbox watch – der Genehmiger führt den Befehl außerhalb des Agenten aus

4. Ausgabe kehrt zum Modell zurück – verpackt in permissionDecision:"deny" mit stdout in der Begründungszeichenfolge

5. Agent fährt fort – er hat das Ergebnis erhalten, hatte selbst nie Privilegien

Der MCP-Kanal funktioniert identisch: run_privileged gibt ein Tool-Ergebnis mit erfasster Ausgabe zurück.

Meilensteine

• ✅ Meilenstein 0 – Grundlagen (Fehlerbehebungen, Pfadbegrenzung, Audit-Rehydrierung)

• ✅ Meilenstein 1 – Die Schleife (PreToolUse-Hook, Ordner-Warteschlange, CLI-Genehmigung)

• ✅ Meilenstein 2 – MCP-Kanal (run_privileged, check_request, sandbox_status)

• ✅ Meilenstein 3 – Ordnerdatensatz (wiederherstellbare Originale, verkettetes Audit, PostToolUse)

• ✅ Meilenstein 4 – Weitere Auslöser (vollständiger Klassifikator, gespeicherte Entscheidungen, SessionStart-Kontext)

• ✅ Meilenstein 5 – Oberflächen (REST-Routen, Deinstallation, Dokumentation)

Alle Meilensteine abgeschlossen. Siehe docs/CONNECTOR.md für die vollständige technische Referenz.

Testen

# Run all tests (117 passing)
python -m pytest -q

# Test the loop with a real hook subprocess and background approver
python -m pytest tests/integration/test_connector_loop.py -v

# Test the MCP channel
python -m pytest tests/integration/test_mcp_tools.py -v

Projektstruktur

src/sandbox/
├── connector/           # Folder connector (queue, hooks, policy, MCP)
├── launcher/            # M1 jailed launcher (job objects, jail, shims)
├── audit/               # Chained audit log with tamper detection
├── broker/              # Non-AI privilege executor
├── fs/                  # Path containment and validation
├── agents/              # Multi-agent sandbox orchestrator
├── api/                 # FastAPI routes and WebSocket
└── ...

Wichtige Designentscheidungen

• Der Ordner ist der Bus: Atomare Dateioperationen auf NTFS koordinieren vier unabhängige Prozesse (kein In-Memory-Zustand, keine offenen Ports, übersteht Neustarts)

• deny trägt die Ausgabe: Das Tool wird nie im Agenten ausgeführt; die Ausgabe wird in die Begründungszeichenfolge eingefügt

• CLI-first-Genehmigung: Headless, funktioniert über SSH, keine Browser-Abhängigkeit

• Fail-closed: Interne Fehler blockieren, anstatt stillschweigend zuzulassen

• Nicht entfernbarer Selbstschutz: .sandbox/** in Schreibverweigerungen und \.sandbox in Shell-Verweigerungen werden bei jedem Laden der Policy erneut injiziert – der Agent kann seine eigenen Einschränkungen nicht entfernen

Lizenz

[Noch zu bestimmen]