AgentGuard

Zero-Trust-Sandbox für autonome KI-Agenten.

AgentGuard umhüllt jeden KI-Agenten (LangChain, CrewAI, AutoGen, benutzerdefinierte Skripte) mit Sicherheitsschienen. Nur ein Befehl ändert sich:

# Vorher (gefährlich – Agent hat vollen Systemzugriff)
python my_agent.py

# Nachher (gesandboxt)
agentguard run -- python my_agent.py

AgentGuard fängt jeden Shell-Befehl, jede Dateiänderung und jede Netzwerkanfrage ab, die der Agent ausführt. Sichere Aktionen werden automatisch erlaubt, gefährliche automatisch blockiert, und für alles andere wird der Mensch um Genehmigung gebeten.

So funktioniert es

AgentGuard hat vier Verteidigungsschichten, die zusammenwirken:

┌─────────────────────────────────────────────────────────────┐
│ Schicht 0: Dateisystem-Jail (sandbox-exec auf macOS)         │
│   Kernel-Level-Erzwingung. Schränkt Dateischreibvorgänge und │
│   Netzwerk auf Syscall-Ebene ein. Der Agent kann es nicht    │
│   aus dem Userspace umgehen. Blockiert Pythons open(),       │
│   requests.post() usw.                                       │
├─────────────────────────────────────────────────────────────┤
│ Schicht 1: Netzwerk-Proxy                                    │
│   Transparenter HTTP/HTTPS-Proxy. Jeder Netzwerkaufruf des   │
│   Agents wird gegen die Richtlinie geprüft. Pro-Ziel-        │
│   Erlauben/Verweigern mit vollständiger Sichtbarkeit im TUI. │
├─────────────────────────────────────────────────────────────┤
│ Schicht 2: PATH-Shims                                        │
│   Shell-Skript-Shims, die Befehle wie git, pip, curl, rm     │
│   abfangen. Jeder Shim fragt den Daemon um Erlaubnis, bevor  │
│   die echte Binärdatei ausgeführt wird.                      │
├─────────────────────────────────────────────────────────────┤
│ Schicht 3: Policy Engine + Genehmigungs-Daemon               │
│   YAML-basierte Regeln bewerten jede abgefangene Aktion.     │
│   Sichere Befehle automatisch erlauben, gefährliche auto-    │
│   matisch blockieren, für alles andere den Menschen fragen.  │
└─────────────────────────────────────────────────────────────┘

Keine einzelne Schicht ist die Sicherheitsgrenze. Sie arbeiten zusammen – Verteidigung in der Tiefe.

Schnellstart

Bauen

go build -o agentguard ./cmd/agentguard/
go build -o agentguard-check ./cmd/agentguard-check/

Beide Binärdateien müssen im selben Verzeichnis liegen.

Eine Richtlinie erstellen

agentguard init

Dies erzeugt .agentguard/policy.yaml im aktuellen Verzeichnis. Bearbeiten Sie sie nach Ihren Bedürfnissen.

Einen Agenten ausführen (Interaktives TUI)

agentguard run -- python my_agent.py

Das TUI übernimmt das Terminal und zeigt:

• Live-Aktivitätsstream (jede abgefangene Aktion)
• Genehmigungsaufforderungen für mehrdeutige Befehle (Drücken Sie Y/N/A/B)
• Netzwerk-Erlauben/Verweigern-Ereignisse vom Proxy
• Sandbox-Verletzungsereignisse
• Agent-Stdout/Stderr (Umschalten mit Tab)

Einen Agenten ausführen (Headless)

Für interaktive Werkzeuge wie Claude Code, die das Terminal benötigen:

agentguard run --headless -- claude

Der Agent bekommt das Terminal direkt. AgentGuard läuft leise im Hintergrund. Alle Ereignisse werden in ~/.agentguard/logs/headless.log protokolliert. Überwachen Sie in einem anderen Terminal:

tail -f ~/.agentguard/logs/headless.log

CLI-Referenz

agentguard run [flags] -- <command> [args...]
    --policy <path>     Eine bestimmte Richtliniendatei verwenden
    --headless          Kein TUI – der Agent bekommt das Terminal
    --default-allow     PROMPT-Entscheidungen im Headless-Modus automatisch erlauben (Standard: auto-deny)
    --no-sandbox        Sandbox-exec deaktivieren (Shims und Proxy bleiben aktiv)

agentguard init         Eine Standard-Richtliniendatei erstellen
agentguard version      Version anzeigen

Richtliniendatei

Richtlinien sind YAML-Dateien, die definieren, was der Agent darf und nicht darf. AgentGuard prüft drei Orte (in dieser Reihenfolge):

1. ./.agentguard/policy.yaml (projektlokal)
2. ~/.agentguard/policy.yaml (benutzerglobal)
3. Eingebaute Standardeinstellungen

Beispielrichtlinie

version: 1

deny:
  # Gefährliche Befehle blockieren
  - command: "rm"
    args: "-rf *"
    reason: "Rekursives erzwungenes Löschen ist zu gefährlich"
  - command: "sudo"
    args: "*"
    reason: "Privilegieneskalation ist nicht erlaubt"
  - command: "chmod"
    args: "777 *"
    reason: "Weltweit beschreibbare Berechtigungen sind gefährlich"

  # Lesen sensibler Dateien blockieren (durchgesetzt von sandbox-exec)
  - file:
      path: "*.env"
      action: "read"
      reason: "Agent darf .env-Dateien nicht lesen lassen"
  - file:
      path: "*.pem"
      action: "read"
      reason: "Agent darf private Schlüssel nicht lesen lassen"

allow:
  # Sichere, schreibgeschützte Befehle
  - command: "ls"
  - command: "cat"
  - command: "pwd"
  - command: "echo"
  - command: "grep"
  - command: "head"
  - command: "tail"
  - command: "wc"

  # Schreibgeschütztes Git
  - command: "git"
    args: "status"
  - command: "git"
    args: "log *"
  - command: "git"
    args: "diff *"

  # Schreibvorgänge in Arbeitsbereich erlauben
  - file:
      path: "/tmp/workspace/**"
      action: "write"

  # Bestimmte API-Endpunkte erlauben
  - network:
      destination: "api.anthropic.com:443"
  - network:
      destination: "api.github.com:443"

Reihenfolge der Regelauswertung

1. Spezifische Deny-Regeln – zuerst geprüft. Bei Übereinstimmung wird die Aktion sofort blockiert.
2. Allow-Regeln – als zweites geprüft. Bei Übereinstimmung wird die Aktion erlaubt.
3. Catch-all-Deny-Regeln (z. B. deny network *) – als drittes geprüft. Fungieren als Standard-Deny.
4. Keine Übereinstimmung – Der Mensch wird aufgefordert (TUI) oder automatisch verweigert (Headless).

Regeltypen

Befehlsregeln – gleichen Shell-Befehle nach Name und Argumentmuster ab:

- command: "git"
  args: "push *"
  reason: "Pushen erfordert Genehmigung"

Dateiregeln – gleichen Dateioperationen ab (durchgesetzt von sandbox-exec):

- file:
    path: "*.env"
    action: "read"     # "read" oder "write"
    reason: "Geheimnisse schützen"

Netzwerkregeln – gleichen Netzwerkziele ab (durchgesetzt von Proxy + sandbox-exec):

- network:
    destination: "api.anthropic.com:443"

Verwenden Sie * als Platzhalter in Befehlsargumenten, Dateipfaden und Netzwerkzielen.

TUI-Bedienelemente

Taste	Aktion	Wann
J	Ausstehende Anfrage erlauben	Genehmigungsaufforderung sichtbar
N	Ausstehende Anfrage verweigern	Genehmigungsaufforderung sichtbar
A	Erlauben + für diese Sitzung merken ("Immer erlauben")	Genehmigungsaufforderung sichtbar
B	Verweigern + für diese Sitzung merken ("Für immer blockieren")	Genehmigungsaufforderung sichtbar
Tab	Agent-Stdout/Stderr-Bereich umschalten	Immer
Hoch/Runter	Aktivitätsstream scrollen	Immer
Q	Beenden (tötet den Agenten)	Immer

Was jede Schicht abfängt

Agent-Aktion	Shims	Proxy	sandbox-exec
subprocess.run(["rm", "-rf", "/"])	Ja	-	-
subprocess.run(["git", "push"])	Ja	-	-
requests.post("https://evil.com")	-	Ja	Ja
urllib.request.urlopen("https://api.com")	-	Ja	Ja
open(".env", "r")	-	-	Ja
open("/etc/shadow", "w")	-	-	Ja
/usr/bin/curl https://evil.com (absoluter Pfad)	-	Ja	Ja

Architektur