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:

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

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

Editar config/nova-tracer.yaml:

# Directorio de salida de informes
# Vacío = {proyecto}/.nova-tracer/reports/ (predeterminado)
# Ruta relativa = relativa al proyecto
# Ruta absoluta = ubicación exacta
report_output_dir: ""

# Resúmenes de sesión impulsados por IA
# Establecer en false para usar resúmenes solo de estadísticas (sin llamadas API)
ai_summary_enabled: true

# Tamaño máximo en KB para salidas de herramientas en informes
# Salidas más grandes se truncarán
output_truncation_kb: 10

# Directorio para reglas NOVA personalizadas
custom_rules_dir: "rules/"

Configuración de escaneo de Nova-tracer

Editar config/nova-config.yaml:

# Proveedor de LLM para detección de Nivel 3
llm_provider: anthropic
model: claude-3-5-haiku-20241022

# Niveles de detección (habilitar/deshabilitar)
enable_keywords: true
enable_semantics: true
enable_llm: true

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

# Filtro de gravedad
min_severity: low  # low, medium, o high

Variables de entorno

# Requerido para resúmenes IA y detección de nivel LLM
export ANTHROPIC_API_KEY=sk-ant-...

Reglas personalizadas

Crea archivos .nov en el directorio rules/:

rule MiReglaPersonalizada
{
    meta:
        description = "Detecta mi patrón de ataque específico"
        author = "Tu nombre"
        severity = "high"
        category = "custom"

    keywords:
        $pattern1 = /mi patrón regex/i
        $pattern2 = "coincidencia exacta de cadena"

    semantics:
        $sem1 = "descripción semántica del ataque" (0.75)

    llm:
        $llm1 = "Pregunta para que el LLM evalúe" (0.7)

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

Estructura de archivos

nova_claude_code_protector/
├── install.sh                    # Script de instalación global
├── uninstall.sh                  # Script de eliminación
├── config/
│   ├── nova-config.yaml          # Configuración de escaneo NOVA
├── rules/
│   ├── instruction_override.nov  # Reglas de ataque de anulación
│   ├── roleplay_jailbreak.nov    # Reglas de ataque de jailbreak
│   ├── encoding_obfuscation.nov  # Reglas de ataque de codificación
│   └── context_manipulation.nov  # Reglas de ataque de contexto
├── hooks/
│   ├── session-start.py          # Hook SessionStart
│   ├── pre-tool-guard.py         # Hook PreToolUse (bloqueo)
│   ├── post-tool-nova-guard.py   # Hook PostToolUse (escaneo)
│   ├── session-end.py            # Hook SessionEnd (informes)
│   ├── test-nova-guard.py        # Utilidad de prueba
│   └── lib/
│       ├── session_manager.py    # Lógica de seguimiento de sesión
│       ├── report_generator.py   # Generación de informes HTML
│       ├── ai_summary.py         # Generación de resúmenes IA
│       └── config.py             # Gestión de configuración
├── tests/                        # Suite de pruebas completa (483 pruebas)
└── test-files/                   # Archivos de inyección de muestra

Solución de problemas

Los hooks no se activan

1. Verificar instalación: cat ~/.claude/settings.json | jq '.hooks'
2. Reiniciar Claude Code completamente (cerrar y reabrir)
3. Verificar que los scripts de hooks sean ejecutables: ls -la hooks/*.py

Los informes no se generan

1. Verificar sesión activa: ls .nova-tracer/sessions/
2. Verificar permisos de escritura en el directorio del proyecto
3. Revisar stderr para errores durante el fin de sesión

Los modelos ML no cargan

La primera ejecución descarga ~1GB de modelos. Si ocurren problemas:

# Limpiar caché de modelos y reintentar
rm -rf ~/.cache/huggingface/
uv run hooks/test-nova-guard.py --samples

Los resúmenes IA no funcionan

1. Verificar clave API: echo $ANTHROPIC_API_KEY
2. Revisar ai_summary_enabled: true en la configuración
3. Los resúmenes solo de estadísticas se usan como respaldo

Desarrollo

Ejecutar pruebas

# Ejecutar todas las pruebas
uv run pytest tests/ -v

# Ejecutar archivo de prueba específico
uv run pytest tests/test_report_generator.py -v

# Ejecutar con cobertura
uv run pytest tests/ --cov=hooks/lib

Cobertura de pruebas

• 483 pruebas que cubren toda la funcionalidad
• Gestión de sesiones, generación de informes, resúmenes IA
• Carga de configuración, scripts de instalación
• Todos los criterios de aceptación verificados

Licencia

Licencia MIT - Ver LICENCIA