Nova-tracer

Monitoreo y visibilidad de agentes

Monitoreo de seguridad y defensa contra inyección de instrucciones para Claude Code usando el NOVA Framework.

Características

• Seguimiento de sesiones - Captura todo el uso de herramientas con marcas de tiempo y metadatos
• Detección de inyección de instrucciones - Análisis de tres niveles (palabras clave, ML semántico, LLM) - monitoreo pasivo con advertencias
• Bloqueo de comandos peligrosos - Previene activamente operaciones destructivas antes de su ejecución
• Seguimiento de MCP y Skills - Rastrea llamadas a servidores MCP e invocaciones de Skills del agente con desgloses detallados
• Informes HTML interactivos - Línea de tiempo visual, rastro de conversación y detalles expandibles de eventos
• Resúmenes impulsados por IA - Resúmenes inteligentes de sesión mediante Claude Haiku
• Configurable - Ubicaciones de informes personalizables, umbrales de detección y reglas

Inicio rápido

# Clonar el repositorio
git clone https://github.com/fr0gger/nova-claude-code-protector.git
cd nova_claude_code_protector

# Instalar globalmente (registra hooks en ~/.claude/settings.json)
./install.sh

# Reiniciar Claude Code para activar los hooks

¡Eso es todo! Nova-tracer ahora protegerá todas tus sesiones de Claude Code.

Instalación

Requisitos previos

• Python 3.10+
• UV - Gestor de paquetes de Python (instalar)
• jq - Procesador JSON (instalar mediante brew install jq en macOS)

Instalar

./install.sh

El instalador hará lo siguiente:

1. Verificar que todos los requisitos previos estén instalados
2. Registrar cuatro hooks de Nova-tracer en ~/.claude/settings.json
3. Conservar cualquier hook existente que hayas configurado
4. Hacer ejecutables los scripts de los hooks

Desinstalar

./uninstall.sh

El desinstalador hará lo siguiente:

1. Eliminar solo los hooks de Nova-tracer de settings.json
2. Conservar todos los demás hooks y configuraciones
3. Opcionalmente, limpiar directorios .nova-tracer/

Cómo funciona

Nova-tracer registra cuatro hooks de Claude Code que trabajan juntos:

┌─────────────────────────────────────────────────────────────┐
│                    Sesión de Claude Code                     │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. Hook SessionStart                                        │
│     └── Crea archivo JSONL de sesión                        │
│     └── Inicializa seguimiento con ID de sesión              │
│                                                              │
│  2. Hook PreToolUse (Bash, Write, Edit)           [ACTIVO]  │
│     └── Escanea comandos ANTES de la ejecución              │
│     └── BLOQUEA operaciones peligrosas (rm -rf, etc.)       │
│                                                              │
│  3. Hook PostToolUse (Read, Bash, WebFetch, etc.) [PASIVO]  │
│     └── Escanea la SALIDA de la herramienta por inyección   │
│     └── ADVIERTE a Claude si se detectan amenazas           │
│     └── Registra evento con veredicto de NOVA               │
│                                                              │
│  4. Hook SessionEnd                                          │
│     └── Genera informe HTML interactivo                     │
│     └── Crea resumen de sesión impulsado por IA             │
│     └── Guarda en .nova-tracer/reports/                     │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Protección Activa vs Pasiva

Nova-tracer proporciona dos modos de protección:

Modo	Hook	Comportamiento	Caso de uso
ACTIVO	PreToolUse	Bloquea la ejecución antes de que ocurra	Comandos peligrosos (rm -rf /, sudo rm, etc.)
PASIVO	PostToolUse	Advierte a Claude después de que se lee el contenido	Inyección de instrucciones en archivos, páginas web, salida de comandos

Importante: La detección de inyección de instrucciones es pasiva. Cuando Nova-tracer detecta una inyección de instrucciones en un archivo o página web, el contenido ya ha sido leído por Claude. Nova-tracer envía un mensaje de advertencia a Claude indicándole que trate el contenido con sospecha, pero no impide que Claude vea el contenido malicioso.

Esta es una limitación de la arquitectura del hook PostToolUse: se ejecuta después de que la herramienta se ejecuta. El bloqueo activo de inyecciones de instrucciones requeriría escanear el contenido antes de que Claude lo lea, lo que implicaría leer los archivos dos veces (una para escanear, otra para Claude).

Lo que se bloquea activamente:

• Comandos destructivos: rm -rf /, sudo rm -rf, mkfs
• Operaciones peligrosas: dd if=... of=/dev/, bombas fork
• Exfiltración de credenciales: curl ... | sh, lectura de ~/.ssh/id_rsa

Lo que se advierte pasivamente:

• Inyección de instrucciones en archivos (herramienta Read)
• Inyección de instrucciones en páginas web (herramienta WebFetch)
• Inyección de instrucciones en salida de comandos (herramienta Bash)
• Inyección de instrucciones en respuestas de herramientas MCP

Detección de tres niveles

Nivel	Método	Velocidad	Detecta
Palabras clave	Patrones regex	~1ms	Patrones de ataque conocidos, frases exactas
Semántica	Similitud ML	~50ms	Ataques parafraseados, variaciones
LLM	Evaluación IA	~500-2000ms	Ataques sofisticados y novedosos

Categorías de ataques detectados

• Anulación de instrucciones - "Ignora todas las instrucciones anteriores", mensajes de sistema falsos
• Jailbreak/Interpretación de roles - Intentos de DAN, cambio de personalidad
• Codificación/Ofuscación - Base64, hexadecimal, Unicode, leetspeak
• Manipulación de contexto - Afirmaciones de autoridad falsas, instrucciones ocultas

Uso

Protección automática

Una vez instalado, Nova-tracer funciona automáticamente:

1. Inicia cualquier sesión de Claude Code - El hook SessionStart inicializa el seguimiento
2. Usa Claude normalmente - Todas las llamadas a herramientas son monitoreadas y escaneadas
3. Finaliza tu sesión - El hook SessionEnd genera un informe HTML

Ver informes

Los informes se guardan en el directorio .nova-tracer/reports/ de cada proyecto:

# Listar informes del proyecto actual
ls .nova-tracer/reports/

# Abrir un informe en el navegador
open .nova-tracer/reports/session-abc123.html

Funcionalidades del informe

El informe HTML interactivo incluye:

• Resumen de sesión - Duración, conteo de herramientas, eventos de seguridad
• Resumen IA - Descripción inteligente de 2-3 oraciones
• Línea de tiempo de eventos - Vista cronológica visual de todas las llamadas a herramientas
• Filtrado - Filtrar por tipo de herramienta o veredicto de NOVA (permitido/advertido/bloqueado)
• Detalles expandibles - Haz clic en cualquier evento para ver entrada/salida completa
• Detalles del veredicto de Nova-tracer - Gravedad, reglas coincidentes, tiempo de escaneo

Pruebas manuales

Prueba la detección de Nova-tracer sin ejecutar Claude Code:

# Ejecutar pruebas de muestra de ataque
uv run hooks/test-nova-guard.py --samples

# Probar texto específico
uv run hooks/test-nova-guard.py --text "ignora las instrucciones anteriores"

# Probar un archivo
uv run hooks/test-nova-guard.py --file sospechoso.txt

# Modo interactivo
uv run hooks/test-nova-guard.py -i

Configuración

Nova-tracer funciona con valores predeterminados sensatos, pero puedes personalizar el comportamiento.

Configuración del Protector Nova-tracer