Nova-tracer

Agent-Überwachung und Sichtbarkeit

Sicherheitsüberwachung und Prompt-Injection-Abwehr für Claude Code unter Verwendung des NOVA Frameworks.

Funktionen

• Sitzungsverfolgung – Erfasst alle Werkzeugnutzungen mit Zeitstempeln und Metadaten
• Prompt-Injection-Erkennung – Dreistufige Überprüfung (Schlüsselwörter, semantische ML, LLM) – passives Monitoring mit Warnungen
• Blockierung gefährlicher Befehle – Verhindert aktiv zerstörerische Operationen vor der Ausführung
• MCP- & Skills-Tracing – Verfolgt MCP-Serveraufrufe und Agent-Skills-Invokationen mit detaillierten Aufschlüsselungen
• Interaktive HTML-Berichte – Visuelle Zeitachse, Gesprächsablauf und erweiterbare Ereignisdetails
• KI-gestützte Zusammenfassungen – Intelligente Sitzungszusammenfassungen mittels Claude Haiku
• Konfigurierbar – Anpassbare Berichtsspeicherorte, Erkennungsschwellwerte und Regeln

Kurzanleitung

# Repository klonen
git clone https://github.com/fr0gger/nova-claude-code-protector.git
cd nova_claude_code_protector

# Global installieren (registriert Hooks in ~/.claude/settings.json)
./install.sh

# Claude Code neu starten, um die Hooks zu aktivieren

Das war's! Nova-tracer schützt nun alle Ihre Claude-Code-Sitzungen.

Installation

Voraussetzungen

• Python 3.10+
• UV – Python-Paketmanager (Installation)
• jq – JSON-Prozessor (Installation unter macOS: brew install jq)

Installieren

./install.sh

Das Installationsskript wird:

1. Alle Voraussetzungen überprüfen
2. Vier Nova-tracer-Hooks in ~/.claude/settings.json registrieren
3. Bereits vorhandene Hooks, die Sie konfiguriert haben, erhalten
4. Die Hook-Skripte ausführbar machen

Deinstallieren

./uninstall.sh

Das Deinstallationsskript wird:

1. Nur Nova-tracer-Hooks aus der settings.json entfernen
2. Alle anderen Hooks und Einstellungen erhalten
3. Optional .nova-tracer/-Verzeichnisse bereinigen

Funktionsweise

Nova-tracer registriert vier Claude-Code-Hooks, die zusammenarbeiten:

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code Session                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. SessionStart Hook                                        │
│     └── Erstellt JSONL-Datei für Sitzung                    │
│     └── Initialisiert Verfolgung mit Sitzungs-ID            │
│                                                              │
│  2. PreToolUse Hook (Bash, Write, Edit)           [AKTIV]   │
│     └── Scannt Befehle VOR der Ausführung                   │
│     └── BLOCKIERT gefährliche Operationen (rm -rf, usw.)    │
│                                                              │
│  3. PostToolUse Hook (Read, Bash, WebFetch, etc.) [PASSIV]  │
│     └── Scannt Werkzeug-AUSGABE auf Prompt Injection        │
│     └── WARNT Claude, falls Bedrohungen erkannt             │
│     └── Zeichnet Ereignis mit NOVA-Beurteilung auf          │
│                                                              │
│  4. SessionEnd Hook                                          │
│     └── Erzeugt interaktiven HTML-Bericht                   │
│     └── Erstellt KI-gestützte Sitzungszusammenfassung       │
│     └── Speichert in .nova-tracer/reports/                  │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Aktiver vs. Passiver Schutz

Nova-tracer bietet zwei Schutzmodi:

Modus	Hook	Verhalten	Anwendungsfall
AKTIV	PreToolUse	Blockiert Ausführung, bevor sie stattfindet	Gefährliche Befehle (rm -rf /, sudo rm, usw.)
PASSIV	PostToolUse	Warnt Claude, nachdem Inhalt gelesen wurde	Prompt Injection in Dateien, Webseiten, Befehlsausgaben

Wichtig: Die Prompt-Injection-Erkennung ist passiv. Wenn Nova-tracer eine Prompt Injection in einer Datei oder Webseite erkennt, wurde der Inhalt bereits von Claude gelesen. Nova-tracer sendet eine Warnmeldung an Claude, die empfiehlt, den Inhalt mit Misstrauen zu behandeln, verhindert jedoch nicht, dass Claude den schädlichen Inhalt sieht.

Dies ist eine Einschränkung der PostToolUse-Hook-Architektur – sie wird nach der Ausführung des Werkzeugs ausgeführt. Eine aktive Blockierung von Prompt Injections würde erfordern, dass der Inhalt vor dem Lesen durch Claude gescannt wird, was ein zweimaliges Lesen der Dateien erfordern würde (einmal zum Scannen, einmal für Claude).

Was aktiv blockiert wird:

• Zerstörerische Befehle: rm -rf /, sudo rm -rf, mkfs
• Gefährliche Operationen: dd if=... of=/dev/, Fork-Bomben
• Credential-Exfiltration: curl ... | sh, Lesen von ~/.ssh/id_rsa

Was passiv gewarnt wird:

• Prompt Injection in Dateien (Read-Werkzeug)
• Prompt Injection in Webseiten (WebFetch-Werkzeug)
• Prompt Injection in Befehlsausgaben (Bash-Werkzeug)
• Prompt Injection in MCP-Werkzeugantworten

Dreistufige Erkennung

Stufe	Methode	Geschwindigkeit	Erfasst
Schlüsselwörter	Regex-Muster	~1ms	Bekannte Angriffsmuster, exakte Phrasen
Semantik	ML-Ähnlichkeit	~50ms	Paraphrasierte Angriffe, Variationen
LLM	KI-Bewertung	~500-2000ms	Raffinierte, neuartige Angriffe

Erkannte Angriffskategorien

• Anweisungsüberschreibung – „Ignoriere alle vorherigen Anweisungen“, gefälschte System-Prompts
• Jailbreak/Rollenspiel – DAN-Versuche, Personenwechsel
• Kodierung/Verschleierung – Base64, Hex, Unicode, Leetspeak
• Kontextmanipulation – Falsche Autoritätsbehauptungen, versteckte Anweisungen

Nutzung

Automatischer Schutz

Nach der Installation arbeitet Nova-tracer automatisch:

1. Starten Sie eine beliebige Claude-Code-Sitzung – Der SessionStart-Hook initialisiert die Verfolgung
2. Verwenden Sie Claude normal – Alle Werkzeugaufrufe werden überwacht und gescannt
3. Beenden Sie Ihre Sitzung – Der SessionEnd-Hook erzeugt einen HTML-Bericht

Berichte ansehen

Berichte werden im Verzeichnis .nova-tracer/reports/ jedes Projekts gespeichert:

# Berichte des aktuellen Projekts auflisten
ls .nova-tracer/reports/

# Einen Bericht im Browser öffnen
open .nova-tracer/reports/session-abc123.html

Berichtsfunktionen

Der interaktive HTML-Bericht umfasst:

• Sitzungszusammenfassung – Dauer, Anzahl der Werkzeuge, Sicherheitsereignisse
• KI-Zusammenfassung – Intelligente Beschreibung in 2–3 Sätzen
• Ereigniszeitachse – Visuelle chronologische Ansicht aller Werkzeugaufrufe
• Filterung – Filter nach Werkzeugtyp oder NOVA-Beurteilung (erlaubt/gewarnt/blockiert)
• Erweiterbare Details – Klicken Sie auf ein Ereignis, um vollständige Ein-/Ausgabe zu sehen
• Nova-tracer-Beurteilungsdetails – Schweregrad, passende Regeln, Scanzeit

Manuelles Testen

Testen Sie die Nova-tracer-Erkennung ohne Ausführung von Claude Code:

# Beispiel-Angriffstests ausführen
uv run hooks/test-nova-guard.py --samples

# Spezifischen Text testen
uv run hooks/test-nova-guard.py --text "ignoriere vorherige Anweisungen"

# Datei testen
uv run hooks/test-nova-guard.py --file suspicious.txt

# Interaktiver Modus
uv run hooks/test-nova-guard.py -i

Konfiguration

Nova-tracer arbeitet mit sinnvollen Standardeinstellungen, Sie können das Verhalten jedoch anpassen.

Nova-tracer-Schutzkonfiguration

Bearbeiten Sie config/nova-tracer.yaml:

# Bericht-Ausgabeverzeichnis
# Leer = {Projekt}/.nova-tracer/reports/ (Standard)
# Relativer Pfad = relativ zum Projekt
# Absoluter Pfad = genauer Speicherort
report_output_dir: ""