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 :

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

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 :

# Report output directory
# Empty = {project}/.nova-tracer/reports/ (default)
# Relative path = relative to project
# Absolute path = exact location
report_output_dir: ""

# AI-powered session summaries
# Set to false to use stats-only summaries (no API calls)
ai_summary_enabled: true

# Maximum size in KB for tool outputs in reports
# Larger outputs will be truncated
output_truncation_kb: 10

# Directory for custom NOVA rules
custom_rules_dir: "rules/"

Configuration de l'analyse Nova-tracer

Modifier config/nova-config.yaml :

# LLM Provider for Tier 3 detection
llm_provider: anthropic
model: claude-3-5-haiku-20241022

# Detection tiers (enable/disable)
enable_keywords: true
enable_semantics: true
enable_llm: true

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

# Severity filter
min_severity: low  # low, medium, or high

Variables d'environnement

# Required for AI summaries and LLM-tier detection
export ANTHROPIC_API_KEY=sk-ant-...

Règles personnalisées

Créez des fichiers .nov dans le répertoire rules/ :

rule MyCustomRule
{
    meta:
        description = "Detects my specific attack pattern"
        author = "Your Name"
        severity = "high"
        category = "custom"

    keywords:
        $pattern1 = /my regex pattern/i
        $pattern2 = "exact string match"

    semantics:
        $sem1 = "semantic description of attack" (0.75)

    llm:
        $llm1 = "Question for LLM to evaluate" (0.7)

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

Structure des fichiers

nova_claude_code_protector/
├── install.sh                    # Global installation script
├── uninstall.sh                  # Removal script
├── config/
│   ├── nova-config.yaml          # NOVA scanning configuration
├── rules/
│   ├── instruction_override.nov  # Override attack rules
│   ├── roleplay_jailbreak.nov    # Jailbreak attack rules
│   ├── encoding_obfuscation.nov  # Encoding attack rules
│   └── context_manipulation.nov  # Context attack rules
├── hooks/
│   ├── session-start.py          # SessionStart hook
│   ├── pre-tool-guard.py         # PreToolUse hook (blocking)
│   ├── post-tool-nova-guard.py   # PostToolUse hook (scanning)
│   ├── session-end.py            # SessionEnd hook (reports)
│   ├── test-nova-guard.py        # Testing utility
│   └── lib/
│       ├── session_manager.py    # Session tracking logic
│       ├── report_generator.py   # HTML report generation
│       ├── ai_summary.py         # AI summary generation
│       └── config.py             # Configuration management
├── tests/                        # Comprehensive test suite (483 tests)
└── test-files/                   # Sample injection files

Dépannage

Les hooks ne s'activent pas

1. Vérifiez l'installation : cat ~/.claude/settings.json | jq '.hooks'
2. Redémarrez complètement Claude Code (quittez et rouvrez)
3. Vérifiez que les scripts de hook sont exécutables : ls -la hooks/*.py

Les rapports ne se génèrent pas

1. Vérifiez la présence d'une session active : ls .nova-tracer/sessions/
2. Vérifiez les permissions d'écriture dans le répertoire du projet
3. Consultez stderr pour les erreurs lors de la fin de session

Les modèles ML ne se chargent pas

La première exécution télécharge ~1 Go de modèles. En cas de problèmes :

# Vider le cache des modèles et réessayer
rm -rf ~/.cache/huggingface/
uv run hooks/test-nova-guard.py --samples

Les résumés IA ne fonctionnent pas

1. Vérifiez la clé API : echo $ANTHROPIC_API_KEY
2. Vérifiez ai_summary_enabled: true dans la configuration
3. Les résumés basés uniquement sur les statistiques sont utilisés comme solution de repli

Développement

Exécution des tests

# Run all tests
uv run pytest tests/ -v

# Run specific test file
uv run pytest tests/test_report_generator.py -v

# Run with coverage
uv run pytest tests/ --cov=hooks/lib

Couverture des tests

• 483 tests couvrant toutes les fonctionnalités
• Gestion de session, génération de rapports, résumés IA
• Chargement de la configuration, scripts d'installation
• Tous les critères d'acceptation vérifiés

Licence

Licence MIT - Voir LICENSE