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:

Modo	Hook	Comportamento	Caso de Uso
ATIVO	PreToolUse	Bloqueia a execução antes que ocorra	Comandos perigosos (rm -rf /, sudo rm, etc.)
PASSIVO	PostToolUse	Avisa o Claude após a leitura do conteúdo	Injeção de prompt em arquivos, páginas web, saída de comandos

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

Nível	Método	Velocidade	Captura
Palavras-chave	Padrões regex	~1ms	Padrões de ataque conhecidos, frases exatas
Semântica	Similaridade ML	~50ms	Ataques parafraseados, variações
LLM	Avaliação de IA	~500-2000ms	Ataques sofisticados e novos

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: ""