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:

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

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:

# Directory di output dei report
# Vuoto = {progetto}/.nova-tracer/reports/ (predefinito)
# Percorso relativo = relativo al progetto
# Percorso assoluto = posizione esatta
report_output_dir: ""

# Riepiloghi della sessione basati su IA
# Imposta a false per usare riepiloghi solo statistici (nessuna chiamata API)
ai_summary_enabled: true

# Dimensione massima in KB per gli output degli strumenti nei report
# Output più grandi verranno troncati
output_truncation_kb: 10

# Directory per regole NOVA personalizzate
custom_rules_dir: "rules/"

Config di Scansione Nova-tracer

Modifica config/nova-config.yaml:

# Provider LLM per il rilevamento di Livello 3
llm_provider: anthropic
model: claude-3-5-haiku-20241022

# Livelli di rilevamento (abilita/disabilita)
enable_keywords: true
enable_semantics: true
enable_llm: true

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

# Filtro di gravità
min_severity: low  # low, medium o high

Variabili d'Ambiente

# Necessario per riepiloghi IA e rilevamento di livello LLM
export ANTHROPIC_API_KEY=sk-ant-...

Regole Personalizzate

Crea file .nov nella directory rules/:

rule MiaRegolaPersonalizzata
{
    meta:
        description = "Rileva il mio specifico pattern di attacco"
        author = "Il Tuo Nome"
        severity = "high"
        category = "custom"

    keywords:
        $pattern1 = /il mio pattern regex/i
        $pattern2 = "corrispondenza esatta stringa"

    semantics:
        $sem1 = "descrizione semantica dell'attacco" (0.75)

    llm:
        $llm1 = "Domanda per il LLM da valutare" (0.7)

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

Struttura dei File

nova_claude_code_protector/
├── install.sh                    # Script di installazione globale
├── uninstall.sh                  # Script di rimozione
├── config/
│   ├── nova-config.yaml          # Configurazione di scansione NOVA
├── rules/
│   ├── instruction_override.nov  # Regole per attacchi di sovrascrittura
│   ├── roleplay_jailbreak.nov    # Regole per attacchi jailbreak
│   ├── encoding_obfuscation.nov  # Regole per attacchi di codifica
│   └── context_manipulation.nov  # Regole per attacchi di contesto
├── hooks/
│   ├── session-start.py          # Hook SessionStart
│   ├── pre-tool-guard.py         # Hook PreToolUse (blocco)
│   ├── post-tool-nova-guard.py   # Hook PostToolUse (scansione)
│   ├── session-end.py            # Hook SessionEnd (report)
│   ├── test-nova-guard.py        # Utility di test
│   └── lib/
│       ├── session_manager.py    # Logica di tracciamento sessione
│       ├── report_generator.py   # Generazione report HTML
│       ├── ai_summary.py         # Generazione riepilogo IA
│       └── config.py             # Gestione configurazione
├── tests/                        # Suite di test completa (483 test)
└── test-files/                   # File di iniezione campione

Risoluzione dei Problemi

Hook non si attivano

1. Verifica installazione: cat ~/.claude/settings.json | jq '.hooks'
2. Riavvia completamente Claude Code (esci e riapri)
3. Controlla che gli script hook siano eseguibili: ls -la hooks/*.py

Report non generati

1. Controlla se c'è una sessione attiva: ls .nova-tracer/sessions/
2. Verifica i permessi di scrittura nella directory del progetto
3. Controlla stderr per errori durante la fine della sessione

Modelli ML non caricati

La prima esecuzione scarica circa 1 GB di modelli. Se ci sono problemi:

# Cancella la cache dei modelli e riprova
rm -rf ~/.cache/huggingface/
uv run hooks/test-nova-guard.py --samples

Riepiloghi IA non funzionano

1. Verifica chiave API: echo $ANTHROPIC_API_KEY
2. Controlla ai_summary_enabled: true nella configurazione
3. I riepiloghi solo statistici vengono usati come ripiego

Sviluppo

Esecuzione dei Test

# Esegui tutti i test
uv run pytest tests/ -v

# Esegui un file di test specifico
uv run pytest tests/test_report_generator.py -v

# Esegui con copertura
uv run pytest tests/ --cov=hooks/lib

Copertura dei Test

• 483 test che coprono tutte le funzionalità
• Gestione delle sessioni, generazione report, riepiloghi IA
• Caricamento configurazione, script di installazione
• Tutti i criteri di accettazione verificati

Licenza

Licenza MIT - Vedi LICENSE