Nova-tracer

Surveillance et visibilité des agents

Surveillance de sécurité et défense contre les injections de prompts pour Claude Code utilisant le NOVA Framework.

Fonctionnalités

• Suivi de session - Capture toutes les utilisations d'outils avec horodatages et métadonnées
• Détection d'injection de prompts - Analyse à trois niveaux (mots-clés, ML sémantique, LLM) - surveillance passive avec avertissements
• Blocage de commandes dangereuses - Empêche activement les opérations destructrices avant exécution
• Traçage MCP & Skills - Suit les appels de serveur MCP et les invocations de compétences d'agent avec des analyses détaillées
• Rapports HTML interactifs - Chronologie visuelle, trace de conversation et détails d'événements extensibles
• Résumés basés sur l'IA - Résumés intelligents de session via Claude Haiku
• Configurable - Emplacements de rapports personnalisés, seuils de détection et règles

Démarrage rapide

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

# Install globally (registers hooks in ~/.claude/settings.json)
./install.sh

# Restart Claude Code to activate hooks

C'est tout ! Nova-tracer protégera désormais toutes vos sessions Claude Code.

Installation

Prérequis

• Python 3.10+
• UV - Gestionnaire de paquets Python (installer)
• jq - Processeur JSON (installer via brew install jq sur macOS)

Installer

./install.sh

L'installateur va :

1. Vérifier que tous les prérequis sont installés
2. Enregistrer quatre hooks Nova-tracer dans ~/.claude/settings.json
3. Préserver tous les hooks existants que vous avez pu configurer
4. Rendre les scripts de hook exécutables

Désinstaller

./uninstall.sh

Le désinstallateur va :

1. Supprimer uniquement les hooks Nova-tracer de settings.json
2. Préserver tous les autres hooks et paramètres
3. Optionnellement nettoyer les répertoires .nova-tracer/

Comment ça fonctionne

Nova-tracer enregistre quatre hooks Claude Code qui fonctionnent ensemble :

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code Session                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. SessionStart Hook                                        │
│     └── Creates session JSONL file                          │
│     └── Initializes tracking with session ID                │
│                                                              │
│  2. PreToolUse Hook (Bash, Write, Edit)           [ACTIVE]  │
│     └── Scans commands BEFORE execution                     │
│     └── BLOCKS dangerous operations (rm -rf, etc.)          │
│                                                              │
│  3. PostToolUse Hook (Read, Bash, WebFetch, etc.) [PASSIVE] │
│     └── Scans tool OUTPUT for prompt injection              │
│     └── WARNS Claude if threats detected                    │
│     └── Records event with NOVA verdict                     │
│                                                              │
│  4. SessionEnd Hook                                          │
│     └── Generates interactive HTML report                   │
│     └── Creates AI-powered session summary                  │
│     └── Saves to .nova-tracer/reports/                      │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Protection active vs passive

Nova-tracer offre deux modes de protection :

Mode	Hook	Comportement	Cas d'utilisation
ACTIF	PreToolUse	Bloque l'exécution avant qu'elle n'ait lieu	Commandes dangereuses (rm -rf /, sudo rm, etc.)
PASSIF	PostToolUse	Avertit Claude après la lecture du contenu	Injection de prompt dans les fichiers, pages Web, sortie de commandes

Important : La détection d'injection de prompt est passive. Lorsque Nova-tracer détecte une injection de prompt dans un fichier ou une page Web, le contenu a déjà été lu par Claude. Nova-tracer envoie un message d'avertissement à Claude lui conseillant de traiter le contenu avec suspicion, mais n'empêche pas Claude de voir le contenu malveillant.

Il s'agit d'une limitation de l'architecture du hook PostToolUse - il s'exécute après l'exécution de l'outil. Le blocage actif des injections de prompt nécessiterait de scanner le contenu avant que Claude ne le lise, ce qui impliquerait de lire les fichiers deux fois (une fois pour le scan, une fois pour Claude).

Ce qui est activement bloqué :

• Commandes destructrices : rm -rf /, sudo rm -rf, mkfs
• Opérations dangereuses : dd if=... of=/dev/, bombes fork
• Exfiltration d'identifiants : curl ... | sh, lecture de ~/.ssh/id_rsa

Ce qui est passivement averti :

• Injection de prompt dans les fichiers (outil Read)
• Injection de prompt dans les pages Web (outil WebFetch)
• Injection de prompt dans la sortie de commandes (outil Bash)
• Injection de prompt dans les réponses d'outils MCP

Détection à trois niveaux

Niveau	Méthode	Vitesse	Capture
Mots-clés	Expressions régulières	~1ms	Modèles d'attaque connus, phrases exactes
Sémantique	Similarité ML	~50ms	Attaques paraphrasées, variations
LLM	Évaluation IA	~500-2000ms	Attaques sophistiquées et nouvelles

Catégories d'attaques détectées

• Remplacement d'instructions - "Ignore toutes les instructions précédentes", faux prompts système
• Jailbreak/Jeu de rôle - Tentatives DAN, changement de persona
• Encodage/Obscurcissement - Base64, hex, Unicode, leetspeak
• Manipulation de contexte - Fausses revendications d'autorité, instructions cachées

Utilisation

Protection automatique

Une fois installé, Nova-tracer fonctionne automatiquement :

1. Démarrez n'importe quelle session Claude Code - Le hook SessionStart initialise le suivi
2. Utilisez Claude normalement - Tous les appels d'outils sont surveillés et scannés
3. Terminez votre session - Le hook SessionEnd génère un rapport HTML

Voir les rapports

Les rapports sont sauvegardés dans le répertoire .nova-tracer/reports/ de chaque projet :

# Lister les rapports pour le projet courant
ls .nova-tracer/reports/

# Ouvrir un rapport dans votre navigateur
open .nova-tracer/reports/session-abc123.html

Fonctionnalités des rapports

Le rapport HTML interactif inclut :

• Résumé de session - Durée, nombre d'outils, événements de sécurité
• Résumé IA - Description intelligente de 2-3 phrases
• Chronologie des événements - Vue chronologique visuelle de tous les appels d'outils
• Filtrage - Filtrer par type d'outil ou verdict NOVA (autorisé/averti/bloqué)
• Détails extensibles - Cliquez sur un événement pour voir l'entrée/sortie complète
• Détails du verdict Nova-tracer - Sévérité, règles correspondantes, temps d'analyse

Tests manuels

Testez la détection de Nova-tracer sans exécuter Claude Code :

# Exécuter les tests d'attaques échantillons
uv run hooks/test-nova-guard.py --samples

# Tester un texte spécifique
uv run hooks/test-nova-guard.py --text "ignore previous instructions"

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

# Mode interactif
uv run hooks/test-nova-guard.py -i

Configuration

Nova-tracer fonctionne avec des valeurs par défaut raisonnables, mais vous pouvez personnaliser le comportement.

Configuration du protecteur Nova-tracer

Modifier config/nova-tracer.yaml :