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:

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

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: ""

# KI-gestützte Sitzungszusammenfassungen
# Auf false setzen, um statistikbasierte Zusammenfassungen zu verwenden (keine API-Aufrufe)
ai_summary_enabled: true

# Maximale Größe in KB für Werkzeugausgaben in Berichten
# Größere Ausgaben werden abgeschnitten
output_truncation_kb: 10

# Verzeichnis für benutzerdefinierte NOVA-Regeln
custom_rules_dir: "rules/"

Nova-tracer-Scankonfiguration

Bearbeiten Sie config/nova-config.yaml:

# LLM-Anbieter für Stufe-3-Erkennung
llm_provider: anthropic
model: claude-3-5-haiku-20241022

# Erkennungsstufen (aktivieren/deaktivieren)
enable_keywords: true
enable_semantics: true
enable_llm: true

# Schwellwerte (0.0 - 1.0)
semantic_threshold: 0.7
llm_threshold: 0.7

# Schweregradfilter
min_severity: low  # low, medium oder high

Umgebungsvariablen

# Erforderlich für KI-Zusammenfassungen und LLM-Stufenerkennung
export ANTHROPIC_API_KEY=sk-ant-...

Benutzerdefinierte Regeln

Erstellen Sie .nov-Dateien im Verzeichnis rules/:

rule MeineBenutzerdefinierteRegel
{
    meta:
        description = "Erkennt mein spezifisches Angriffsmuster"
        author = "Ihr Name"
        severity = "high"
        category = "custom"

    keywords:
        $muster1 = /mein regex muster/i
        $muster2 = "exakte Zeichenkette"

    semantics:
        $sem1 = "semantische Beschreibung des Angriffs" (0.75)

    llm:
        $llm1 = "Frage an das LLM zur Bewertung" (0.7)

    condition:
        any of ($muster*) or $sem1 or $llm1
}

Dateistruktur

nova_claude_code_protector/
├── install.sh                    # Globales Installationsskript
├── uninstall.sh                  # Deinstallationsskript
├── config/
│   ├── nova-config.yaml          # NOVA-Scankonfiguration
├── rules/
│   ├── instruction_override.nov  # Regeln für Anweisungsüberschreibungsangriffe
│   ├── roleplay_jailbreak.nov    # Regeln für Jailbreak-Angriffe
│   ├── encoding_obfuscation.nov  # Regeln für Kodierungsangriffe
│   └── context_manipulation.nov  # Regeln für Kontextangriffe
├── hooks/
│   ├── session-start.py          # SessionStart-Hook
│   ├── pre-tool-guard.py         # PreToolUse-Hook (Blockierung)
│   ├── post-tool-nova-guard.py   # PostToolUse-Hook (Scanning)
│   ├── session-end.py            # SessionEnd-Hook (Berichte)
│   ├── test-nova-guard.py        # Testwerkzeug
│   └── lib/
│       ├── session_manager.py    # Logik zur Sitzungsverfolgung
│       ├── report_generator.py   # HTML-Berichtsgenerierung
│       ├── ai_summary.py         # KI-Zusammenfassungsgenerierung
│       └── config.py             # Konfigurationsverwaltung
├── tests/                        # Umfassende Testsuite (483 Tests)
└── test-files/                   # Beispiel-Injektionsdateien

Fehlerbehebung

Hooks werden nicht aktiviert

1. Überprüfen Sie die Installation: cat ~/.claude/settings.json | jq '.hooks'
2. Starten Sie Claude Code vollständig neu (beenden und erneut öffnen)
3. Prüfen Sie, ob die Hook-Skripte ausführbar sind: ls -la hooks/*.py

Berichte werden nicht erstellt

1. Prüfen Sie auf aktive Sitzungen: ls .nova-tracer/sessions/
2. Überprüfen Sie die Schreibberechtigungen im Projektverzeichnis
3. Prüfen Sie stderr auf Fehler beim Sitzungsende

ML-Modelle werden nicht geladen

Der erste Ladevorgang lädt etwa 1 GB an Modellen herunter. Bei Problemen:

# Modell-Cache leeren und erneut versuchen
rm -rf ~/.cache/huggingface/
uv run hooks/test-nova-guard.py --samples

KI-Zusammenfassungen funktionieren nicht

1. Überprüfen Sie den API-Schlüssel: echo $ANTHROPIC_API_KEY
2. Stellen Sie sicher, dass ai_summary_enabled: true in der Konfiguration gesetzt ist
3. Als Fallback werden statistikbasierte Zusammenfassungen verwendet

Entwicklung

Tests ausführen

# Alle Tests ausführen
uv run pytest tests/ -v

# Bestimmte Testdatei ausführen
uv run pytest tests/test_report_generator.py -v

# Mit Codeabdeckung
uv run pytest tests/ --cov=hooks/lib

Testabdeckung

• 483 Tests decken alle Funktionen ab
• Sitzungsverwaltung, Berichtsgenerierung, KI-Zusammenfassungen
• Konfigurationsladen, Installationsskripte
• Alle Akzeptanzkriterien verifiziert

Lizenz

MIT-Lizenz – Siehe LICENSE