Guards: Das Immunsystem deiner KI-Agenten

Warum KI-Agenten ein Immunsystem brauchen

Die teuerste Lektion aus dem ersten Jahr mit KI-Agenten gegen Produktionssysteme lässt sich in einen Satz fassen: Erkennung schützt nicht.

Du kannst alles loggen, alles reviewen, auf alles Alerting setzen. Der Fehler war trotzdem schon passiert, als du ihn gesehen hast. Ein nachträgliches Review erkennt Schaden. Es verhindert ihn nicht.

Die gesamte Philosophie hinter der Guard-Schicht folgt daraus: Blockiere vor dem Schaden, nicht erkenne danach.

Warum "den Pull Request prüfen" keine Strategie ist

Wenn Leute fragen, wie man einen KI-Agenten davon abhält, etwas Destruktives zu tun, erwarten sie als Antwort "sorgfältige Codeprüfung". Dieses Modell bricht in dem Moment, in dem ein Agent Code schreiben, einen Shell-Befehl ausführen und ein Deployment anstoßen kann, innerhalb derselben Session, in derselben Minute.

Bis ein Pull Request zur Prüfung existiert, hat der Agent möglicherweise bereits eine Datenbankmigration ausgeführt, einen Container neu gestartet oder eine E-Mail gesendet. Der Pull Request liegt dem Risiko nachgelagert. Nicht vorgelagert.

Die Zahlen aus der Praxis

• 177 Guard-Regeln in Produktion, verteilt über 4 Dispatcher
• 96% Enforcement-Rate (83 von 86 Regeln automatisch durchgesetzt)
• 86 Docker-Container geschützt auf einem Server
• 24 PostgreSQL-Datenbanken mit eigenem Schutz
• ~1.400 Blocks pro Woche im Normalbetrieb

Drei Vorfälle, die das System verändert haben

Das Guard-System entstand nicht als Plan, sondern als Reaktion auf drei echte Vorfälle. Jeder hat eine neue Kategorie von Schutz erzwungen.

Vorfall 1: Die Backup-Wiederherstellung

Ein Agent sollte ein Backup wiederherstellen und hat dabei die aktuelle Produktionsdatenbank überschrieben, anstatt eine Testdatenbank zu verwenden. Der Fehler: keine Prüfung, ob das Ziel eine Produktions- oder Testdatenbank ist.

Daraus entstand: Der Database-Destruction-Guard, der jedes DROP, DELETE und TRUNCATE gegen eine Liste geschützter Datenbanken prüft.

Vorfall 2: Das Follow-Up, das zu früh rausging

Ein automatisiertes Follow-Up ging an 871 E-Mail-Adressen, weil eine RLS-Policy deaktiviert war. Jeder Empfänger bekam Daten, die nicht für ihn bestimmt waren.

Daraus entstand: Der RLS-Guard und der E-Mail-Gate, die prüfen ob Row-Level-Security aktiv ist, bevor Massenoperationen laufen.

Vorfall 3: Der Server, der nicht zurückkam

Ein Passwort-Sync-Script überschrieb eine .env-Datei mit dem falschen Passwort. Totalausfall für 5 Stunden, weil keine App mehr die Datenbank erreichen konnte.

Daraus entstand: Das Tabu-Gate, der Secret-Guard und der Pre-Exec-File-Scanner.

Die Hook-Architektur: Pre-Bash, Post-Bash, Stop-Dispatcher

Jede Aktion, die ein Agent ausführt, durchläuft eine Dispatch-Schicht. Vier Phasen, vier Zeitpunkte, vier Möglichkeiten zum Eingreifen.

Die vier Dispatcher

• pre-bash-dispatcher.sh feuert VOR jedem Shell-Befehl. Hier passiert der Großteil des Blockierens. Der meiste Schaden entsteht durch die Shell: git push --force, DROP TABLE, rm -rf, docker rm.
• post-bash-dispatcher.sh feuert NACH einem Shell-Befehl. Erkennt, was man erst danach wissen kann: Enthält die Ausgabe ein Secret? Ist der Befehl still fehlgeschlagen?
• post-edit-dispatcher.sh feuert nach jeder Dateiänderung. Wurde ein Credential hartkodiert? Wurde ein erforderlicher Badge entfernt?
• stop-dispatcher.sh feuert beim Session-Ende. Fängt ab, was hätte erledigt sein sollen: uncommittete Arbeit, ungelöste Gate-Dateien.

Das Profiling-System

Nicht jeder Guard feuert bei jedem Befehl. Ein Profiling-System klassifiziert jeden Befehl in ein Profil (git, docker, npm, database, deploy, comms, remote, system, minimal) und lädt nur relevante Guards. Ein git-Befehl aktiviert git-Guards. Ein database-Befehl aktiviert SQL-Guards.

Die 8 Always-On Security Gates

Acht Gates feuern bei JEDEM Befehl, in JEDEM Profil. Keine Ausnahmen:

1. Tabu-Gate: Feste Liste verbotener Aktionen
2. PII-Gate: Erkennt personenbezogene Daten
3. API-Key-Guard: Scannt auf Credential-Muster
4. Secret-Guard: Blockiert bekannte Secret-Quellen
5. Pre-Exec-File-Scanner: Inspiziert Dateien vor Ausführung
6. Gate-File-Guard: Schützt das Guard-System vor dem Agenten selbst
7. Agent-Control-Policy-Guard: Setzt Agenten-Grenzen durch
8. Main-Push-Guard: Blockiert direkte Pushes auf geschützte Branches

#!/bin/bash
# pre-bash-dispatcher.sh

CMD="$1"
PROFILE=$(classify_command "$CMD")

# Always-on Gates (IMMER laden)
source guards/security/tabu-gate.sh
source guards/security/pii-gate.sh
source guards/security/api-key-guard.sh
source guards/security/secret-guard.sh

# Profil-spezifische Guards
case "$PROFILE" in
  database) source guards/database/*.sh ;;
  docker)   source guards/docker/*.sh ;;
  git)      source guards/git/*.sh ;;
  *)        ;; # minimal profile
esac

# Guards ausführen
for guard in "${LOADED_GUARDS[@]}"; do
  result=$($guard "$CMD")
  if [ "$result" = "DENY" ]; then
    echo "BLOCKED: $guard_reason"
    exit 1
  fi
done

Tag 1: Deine ersten drei Guards (Hands-on)

Du brauchst am ersten Tag keine hundert Guards. Die meisten existieren, weil ein spezifischer Fehlschlag eine spezifische Lücke demonstriert hat. Am ersten Tag brauchst du drei Guards und die Gewohnheit, bei jedem Durchrutscher einen weiteren hinzuzufügen.

Guard 1: Der Destruktive-SQL-Guard

#!/bin/bash
hook_destructive_sql_guard() {
  local cmd="$CMD"
  if echo "$cmd" | grep -qiE '(DELETE|DROP|TRUNCATE)\s' && \
     ! echo "$cmd" | grep -qiE 'WHERE\s'; then
    deny "BLOCKED: Destruktive SQL-Operation ohne WHERE-Klausel."
  fi
}

Dieser Guard verhindert das häufigste Datenbankproblem: ein DELETE FROM users ohne WHERE-Klausel, das alle Zeilen löscht.

Guard 2: Der Docker-Destruction-Guard

#!/bin/bash
hook_docker_destruction_guard() {
  local cmd="$CMD"
  if echo "$cmd" | grep -qiE 'docker\s+(rm|remove)\s+-f'; then
    deny "BLOCKED: Force-Remove eines Containers. Nutze docker stop + docker rm."
  fi
  if echo "$cmd" | grep -qiE 'docker\s+system\s+prune'; then
    deny "BLOCKED: Docker System Prune entfernt alle ungenutzten Ressourcen."
  fi
}

Guard 3: Der Secret-Exposure-Guard

#!/bin/bash
hook_secret_exposure_guard() {
  local cmd="$CMD"
  if echo "$cmd" | grep -qiE '(cat|echo|head|tail|less|more)\s+.*\.(env|pem|key|credentials)'; then
    deny "BLOCKED: Zugriff auf Datei mit potenziellen Credentials."
  fi
  if echo "$cmd" | grep -qiE 'echo\s+\$\{?(DATABASE_URL|API_KEY|SECRET|PASSWORD|TOKEN)'; then
    deny "BLOCKED: Credential-Variable wird in die Ausgabe geschrieben."
  fi
}

#!/bin/bash
# Datei: ~/.claude/hooks/guardrail/guards/custom/my_guard.sh
#
# Jeder Guard folgt dem gleichen Muster:
# 1. Befehl empfangen ($CMD)
# 2. Muster prüfen (grep/regex)
# 3. deny() aufrufen wenn blockiert

hook_my_custom_guard() {
  local cmd="$CMD"

  if echo "$cmd" | grep -qiE 'DEIN_MUSTER'; then
    deny "BLOCKED: Grund warum das gefährlich ist."
  fi
}

# Guard wird automatisch geladen. Kein Restart nötig.

Defense in Depth und Profiling-System

20 Core Guards stoppen in der Praxis die überwältigende Mehrheit der Vorfälle. Alles darüber hinaus ist Defense in Depth: Guards für engere, seltenere, domänenspezifischere Fehlermodi.

Die Guard-Kategorien (in Aufbaureihenfolge)

1. Security: PII, Secrets, API-Keys, Prompt Injection, Dependency-Lizenz-Compliance
2. Quality: Pre-Commit Quality-Gate, Pre-Mortem, Mindest-Testabdeckung, UI-Verifikation
3. Deployment: Branch-Schutz, Docker-Build-Validierung, Post-Deploy-Prüfung, HTTPS/TLS
4. Git: Main-Push-Guard, Worktree-Isolation, PR-Review, Merge-Verifikation
5. Ticket/Support: Status-Übergänge, Completion-Guards
6. Content/Stil: Markenstimme, regulatorische Offenlegung
7. Domänenspezifisch: Guards für spezifische Infrastruktur, geschrieben am Tag des Vorfalls

Profiling: Nicht jeder Guard für jeden Befehl

Das Profiling-System klassifiziert jeden eingehenden Befehl und lädt nur relevante Guards. Ergebnis: Sub-Millisekunde pro Guard, unter 20ms für die gesamte Pipeline. Das System bleibt im Normalbetrieb unsichtbar.

# guardrail.config.sh
# Jedes Profil definiert, welche Guard-Gruppen laden

PROFILE_DATABASE="security quality database"
PROFILE_DOCKER="security deployment docker"
PROFILE_GIT="security quality git"
PROFILE_NPM="security quality"
PROFILE_DEPLOY="security deployment docker git"
PROFILE_MINIMAL="security"

# Security lädt IMMER (8 Always-On Gates)
# Andere Gruppen nur wenn relevant

Fehlalarme: Die richtige Balance

~1.400 Blocks pro Woche klingt nach viel. Die meisten sind korrekte Blocks: der Agent versucht etwas, das tatsächlich riskant ist, und korrigiert seinen Ansatz nach dem Block. Ein Guard sollte lieber einmal zu viel feuern als einmal zu wenig. Der Agent bekommt die Block-Nachricht und kann seinen Ansatz anpassen.