Nova-tracer

Monitoraggio e Visibilità degli Agenti

Monitoraggio della sicurezza e difesa contro l'iniezione di prompt per Claude Code utilizzando il NOVA Framework.

Caratteristiche

• Tracciamento delle Sessioni - Cattura tutti gli utilizzi degli strumenti con timestamp e metadati
• Rilevamento di Iniezione di Prompt - Scansione a tre livelli (parole chiave, ML semantico, LLM) - monitoraggio passivo con avvisi
• Blocco dei Comandi Pericolosi - Impedisce attivamente operazioni distruttive prima dell'esecuzione
• Tracciamento MCP e Skills - Tiene traccia delle chiamate al server MCP e delle invocazioni delle Skills degli Agenti con dettagli approfonditi
• Report HTML Interattivi - Timeline visiva, traccia della conversazione e dettagli espandibili degli eventi
• Riepiloghi basati su IA - Riepiloghi intelligenti delle sessioni tramite Claude Haiku
• Configurabile - Posizioni personalizzate dei report, soglie di rilevamento e regole

Avvio Rapido

# Clona il repository
git clone https://github.com/fr0gger/nova-claude-code-protector.git
cd nova_claude_code_protector

# Installa globalmente (registra gli hook in ~/.claude/settings.json)
./install.sh

# Riavvia Claude Code per attivare gli hook

Questo è tutto! Nova-tracer proteggerà ora tutte le tue sessioni di Claude Code.

Installazione

Prerequisiti

• Python 3.10+
• UV - Gestore di pacchetti Python (installazione)
• jq - Processore JSON (installa tramite brew install jq su macOS)

Installazione

./install.sh

Il programma di installazione:

1. Verifica che tutti i prerequisiti siano installati
2. Registra quattro hook di Nova-tracer in ~/.claude/settings.json
3. Preserva eventuali hook esistenti che potresti aver configurato
4. Rende eseguibili gli script degli hook

Disinstallazione

./uninstall.sh

Il programma di disinstallazione:

1. Rimuove solo gli hook di Nova-tracer da settings.json
2. Preserva tutti gli altri hook e impostazioni
3. Opzionalmente pulisce le directory .nova-tracer/

Come Funziona

Nova-tracer registra quattro hook di Claude Code che lavorano insieme:

┌─────────────────────────────────────────────────────────────┐
│                    Sessione Claude Code                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. Hook SessionStart                                         │
│     └── Crea il file JSONL della sessione                    │
│     └── Inizializza il tracciamento con ID sessione          │
│                                                              │
│  2. Hook PreToolUse (Bash, Write, Edit)            [ATTIVO]  │
│     └── Scansiona i comandi PRIMA dell'esecuzione            │
│     └── BLOCCA operazioni pericolose (rm -rf, ecc.)          │
│                                                              │
│  3. Hook PostToolUse (Read, Bash, WebFetch, ecc.) [PASSIVO]  │
│     └── Scansiona l'OUTPUT dello strumento per iniezione di prompt │
│     └── AVVERTE Claude se vengono rilevate minacce           │
│     └── Registra l'evento con il verdetto di NOVA            │
│                                                              │
│  4. Hook SessionEnd                                          │
│     └── Genera un report HTML interattivo                    │
│     └── Crea un riepilogo della sessione basato su IA        │
│     └── Salva in .nova-tracer/reports/                       │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Protezione Attiva vs Passiva

Nova-tracer fornisce due modalità di protezione:

Modalità	Hook	Comportamento	Caso d'Uso
ATTIVA	PreToolUse	Blocca l'esecuzione prima che avvenga	Comandi pericolosi (rm -rf /, sudo rm, ecc.)
PASSIVA	PostToolUse	Avverte Claude dopo che il contenuto è stato letto	Iniezione di prompt in file, pagine web, output di comandi

Importante: Il rilevamento di iniezione di prompt è passivo. Quando Nova-tracer rileva un'iniezione di prompt in un file o una pagina web, il contenuto è già stato letto da Claude. Nova-tracer invia un messaggio di avviso a Claude consigliandogli di trattare il contenuto con sospetto, ma non impedisce a Claude di vedere il contenuto malevolo.

Questa è una limitazione dell'architettura dell'hook PostToolUse: viene eseguito dopo che lo strumento ha agito. Il blocco attivo delle iniezioni di prompt richiederebbe la scansione del contenuto prima che Claude lo legga, il che implicherebbe la lettura dei file due volte (una per la scansione, una per Claude).

Cosa viene bloccato attivamente:

• Comandi distruttivi: rm -rf /, sudo rm -rf, mkfs
• Operazioni pericolose: dd if=... of=/dev/, fork bomb
• Esfiltrazione di credenziali: curl ... | sh, lettura di ~/.ssh/id_rsa

Cosa viene avvisato passivamente:

• Iniezione di prompt in file (strumento Read)
• Iniezione di prompt in pagine web (strumento WebFetch)
• Iniezione di prompt in output di comandi (strumento Bash)
• Iniezione di prompt nelle risposte degli strumenti MCP

Rilevamento a Tre Livelli

Livello	Metodo	Velocità	Rileva
Parole Chiave	Pattern regex	~1ms	Pattern di attacco noti, frasi esatte
Semantica	Similarità ML	~50ms	Attacchi parafrasati, variazioni
LLM	Valutazione AI	~500-2000ms	Attacchi sofisticati e nuovi

Categorie di Attacco Rilevate

• Sovrascrittura delle Istruzioni - "Ignora tutte le istruzioni precedenti", falsi prompt di sistema
• Jailbreak/Gioco di Ruoli - Tentativi DAN, cambio di personalità
• Codifica/Offuscamento - Base64, hex, Unicode, leetspeak
• Manipolazione del Contesto - Affermazioni di autorità false, istruzioni nascoste

Utilizzo

Protezione Automatica

Una volta installato, Nova-tracer funziona automaticamente:

1. Avvia qualsiasi sessione di Claude Code - L'hook SessionStart inizializza il tracciamento
2. Usa Claude normalmente - Tutte le chiamate agli strumenti vengono monitorate e scansionate
3. Termina la sessione - L'hook SessionEnd genera un report HTML

Visualizzazione Report

I report vengono salvati nella directory .nova-tracer/reports/ di ogni progetto:

# Elenca i report per il progetto corrente
ls .nova-tracer/reports/

# Apri un report nel browser
open .nova-tracer/reports/session-abc123.html

Funzionalità del Report

Il report HTML interattivo include:

• Riepilogo della Sessione - Durata, conteggi degli strumenti, eventi di sicurezza
• Riepilogo IA - Descrizione intelligente di 2-3 frasi
• Timeline degli Eventi - Vista cronologica visiva di tutte le chiamate agli strumenti
• Filtraggio - Filtra per tipo di strumento o verdetto NOVA (permesso/avvisato/bloccato)
• Dettagli Espandibili - Clicca su qualsiasi evento per vedere input/output completi
• Dettagli del Verdetto Nova-tracer - Gravità, regole corrispondenti, tempo di scansione

Test Manuale

Testa il rilevamento di Nova-tracer senza eseguire Claude Code:

# Esegui test di attacco campione
uv run hooks/test-nova-guard.py --samples

# Testa un testo specifico
uv run hooks/test-nova-guard.py --text "ignore previous instructions"

# Testa un file
uv run hooks/test-nova-guard.py --file suspicious.txt

# Modalità interattiva
uv run hooks/test-nova-guard.py -i

Configurazione

Nova-tracer funziona con impostazioni predefinite sensate, ma puoi personalizzare il comportamento.

Config di Nova-tracer Protector

Modifica config/nova-tracer.yaml: