Nova-tracer

Monitoramento e Visibilidade de Agentes

Monitoramento de segurança e defesa contra injeção de prompt para Claude Code usando o NOVA Framework.

Funcionalidades

• Rastreamento de Sessão - Captura todo o uso de ferramentas com timestamps e metadados
• Detecção de Injeção de Prompt - Varredura em três níveis (palavras-chave, ML semântico, LLM) - monitoramento passivo com avisos
• Bloqueio de Comandos Perigosos - Previne ativamente operações destrutivas antes da execução
• Rastreamento MCP e Skills - Rastreia chamadas de servidor MCP e invocações de Skills do Agente com detalhamentos
• Relatórios HTML Interativos - Linha do tempo visual, rastreamento de conversa e detalhes expansíveis de eventos
• Resumos Impulsionados por IA - Resumos inteligentes de sessão via Claude Haiku
• Configurável - Locais de relatório personalizados, limites de detecção e regras

Início Rápido

# Clone o repositório
git clone https://github.com/fr0gger/nova-claude-code-protector.git
cd nova_claude_code_protector

# Instale globalmente (registra hooks em ~/.claude/settings.json)
./install.sh

# Reinicie o Claude Code para ativar os hooks

É isso! O Nova-tracer agora protegerá todas as suas sessões do Claude Code.

Instalação

Pré-requisitos

• Python 3.10+
• UV - Gerenciador de pacotes Python (instalar)
• jq - Processador JSON (instale via brew install jq no macOS)

Instalar

./install.sh

O instalador irá:

1. Verificar se todos os pré-requisitos estão instalados
2. Registrar quatro hooks do Nova-tracer em ~/.claude/settings.json
3. Preservar quaisquer hooks existentes que você possa ter configurado
4. Tornar os scripts de hook executáveis

Desinstalar

./uninstall.sh

O desinstalador irá:

1. Remover apenas os hooks do Nova-tracer do settings.json
2. Preservar todos os outros hooks e configurações
3. Opcionalmente limpar diretórios .nova-tracer/

Como Funciona

O Nova-tracer registra quatro hooks do Claude Code que funcionam juntos:

┌─────────────────────────────────────────────────────────────┐
│                    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/                      │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Proteção Ativa vs Passiva

O Nova-tracer fornece dois modos de proteção:

Importante: A detecção de injeção de prompt é passiva. Quando o Nova-tracer detecta uma injeção de prompt em um arquivo ou página web, o conteúdo já foi lido pelo Claude. O Nova-tracer envia uma mensagem de aviso ao Claude aconselhando-o a tratar o conteúdo com suspeita, mas não impede que Claude veja o conteúdo malicioso.

Esta é uma limitação da arquitetura do hook PostToolUse - ele é executado após a ferramenta ser usada. O bloqueio ativo de injeções de prompt exigiria a varredura do conteúdo antes que Claude o lesse, o que envolveria ler os arquivos duas vezes (uma para varredura, outra para Claude).

O que é bloqueado ativamente:

• Comandos destrutivos: rm -rf /, sudo rm -rf, mkfs
• Operações perigosas: dd if=... of=/dev/, fork bombs
• Exfiltração de credenciais: curl ... | sh, leitura de ~/.ssh/id_rsa

O que é avisado passivamente:

• Injeção de prompt em arquivos (ferramenta Read)
• Injeção de prompt em páginas web (ferramenta WebFetch)
• Injeção de prompt na saída de comandos (ferramenta Bash)
• Injeção de prompt em respostas de ferramentas MCP

Detecção em Três Níveis

Categorias de Ataque Detectadas

• Sobrescrita de Instrução - "Ignore todas as instruções anteriores", prompts de sistema falsos
• Jailbreak/Interpretação de Papéis - Tentativas DAN, troca de persona
• Codificação/Ofuscação - Base64, hex, Unicode, leetspeak
• Manipulação de Contexto - Alegações falsas de autoridade, instruções ocultas

Uso

Proteção Automática

Uma vez instalado, o Nova-tracer funciona automaticamente:

1. Inicie qualquer sessão do Claude Code - O hook SessionStart inicializa o rastreamento
2. Use o Claude normalmente - Todas as chamadas de ferramentas são monitoradas e varridas
3. Encerre sua sessão - O hook SessionEnd gera um relatório HTML

Visualizar Relatórios

Os relatórios são salvos no diretório .nova-tracer/reports/ de cada projeto:

# Liste os relatórios do projeto atual
ls .nova-tracer/reports/

# Abra um relatório no seu navegador
open .nova-tracer/reports/session-abc123.html

Recursos do Relatório

O relatório HTML interativo inclui:

• Resumo da Sessão - Duração, contagens de ferramentas, eventos de segurança
• Resumo com IA - Descrição inteligente de 2-3 frases
• Linha do Tempo de Eventos - Vista cronológica visual de todas as chamadas de ferramentas
• Filtragem - Filtrar por tipo de ferramenta ou veredito NOVA (permitido/avisado/bloqueado)
• Detalhes Expansíveis - Clique em qualquer evento para ver entrada/saída completos
• Detalhes do Veredito Nova-tracer - Severidade, regras correspondidas, tempo de varredura

Teste Manual

Teste a detecção do Nova-tracer sem executar o Claude Code:

# Execute testes de ataque de exemplo
uv run hooks/test-nova-guard.py --samples

# Teste texto específico
uv run hooks/test-nova-guard.py --text "ignore previous instructions"

# Teste um arquivo
uv run hooks/test-nova-guard.py --file suspicious.txt

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

Configuração

O Nova-tracer funciona com padrões sensatos, mas você pode personalizar o comportamento.

Configuração do Protetor Nova-tracer

Edite config/nova-tracer.yaml:

# Diretório de saída do relatório
# Vazio = {projeto}/.nova-tracer/reports/ (padrão)
# Caminho relativo = relativo ao projeto
# Caminho absoluto = local exato
report_output_dir: ""

# Resumos de sessão com IA
# Defina como false para usar resumos apenas com estatísticas (sem chamadas de API)
ai_summary_enabled: true

# Tamanho máximo em KB para saídas de ferramentas nos relatórios
# Saídas maiores serão truncadas
output_truncation_kb: 10

# Diretório para regras NOVA personalizadas
custom_rules_dir: "rules/"

Configuração de Varredura do Nova-tracer

Edite config/nova-config.yaml:

# Provedor LLM para detecção de Nível 3
llm_provider: anthropic
model: claude-3-5-haiku-20241022

# Níveis de detecção (ativar/desativar)
enable_keywords: true
enable_semantics: true
enable_llm: true

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

# Filtro de severidade
min_severity: low  # low, medium, ou high

Variáveis de Ambiente

# Necessário para resumos com IA e detecção de nível LLM
export ANTHROPIC_API_KEY=sk-ant-...

Regras Personalizadas

Crie arquivos .nov no diretório 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
}

Estrutura de Arquivos

nova_claude_code_protector/
├── install.sh                    # Script de instalação global
├── uninstall.sh                  # Script de remoção
├── config/
│   ├── nova-config.yaml          # Configuração de varredura NOVA
├── rules/
│   ├── instruction_override.nov  # Regras de ataque de sobrescrita
│   ├── roleplay_jailbreak.nov    # Regras de ataque de jailbreak
│   ├── encoding_obfuscation.nov  # Regras de ataque de codificação
│   └── context_manipulation.nov  # Regras de ataque de contexto
├── hooks/
│   ├── session-start.py          # Hook SessionStart
│   ├── pre-tool-guard.py         # Hook PreToolUse (bloqueio)
│   ├── post-tool-nova-guard.py   # Hook PostToolUse (varredura)
│   ├── session-end.py            # Hook SessionEnd (relatórios)
│   ├── test-nova-guard.py        # Utilitário de teste
│   └── lib/
│       ├── session_manager.py    # Lógica de rastreamento de sessão
│       ├── report_generator.py   # Geração de relatório HTML
│       ├── ai_summary.py         # Geração de resumo com IA
│       └── config.py             # Gerenciamento de configuração
├── tests/                        # Suíte de testes abrangente (483 testes)
└── test-files/                   # Arquivos de injeção de exemplo

Solução de Problemas

Hooks não ativando

1. Verifique a instalação: cat ~/.claude/settings.json | jq '.hooks'
2. Reinicie o Claude Code completamente (sair e reabrir)
3. Verifique se os scripts de hook são executáveis: ls -la hooks/*.py

Relatórios não gerando

1. Verifique se há sessão ativa: ls .nova-tracer/sessions/
2. Verifique permissões de gravação no diretório do projeto
3. Verifique stderr para erros durante o fim da sessão

Modelos ML não carregando

A primeira execução baixa ~1GB de modelos. Se ocorrerem problemas:

# Limpe o cache do modelo e tente novamente
rm -rf ~/.cache/huggingface/
uv run hooks/test-nova-guard.py --samples

Resumos de IA não funcionando

1. Verifique a chave API: echo $ANTHROPIC_API_KEY
2. Verifique ai_summary_enabled: true na configuração
3. Resumos apenas com estatísticas são usados como fallback

Desenvolvimento

Executando Testes

# Execute todos os testes
uv run pytest tests/ -v

# Execute um arquivo de teste específico
uv run pytest tests/test_report_generator.py -v

# Execute com cobertura
uv run pytest tests/ --cov=hooks/lib

Cobertura de Testes

• 483 testes cobrindo toda a funcionalidade
• Gerenciamento de sessão, geração de relatórios, resumos de IA
• Carregamento de configuração, scripts de instalação
• Todos os critérios de aceitação verificados

Licença

Licença MIT - Veja LICENSE