swelljoe/nelsonEncontrando vulnerabilidades através de força bruta cega
Inspirado por uma palestra de Nicholas Carlini e pelo Ralph loop, Nelson é uma ferramenta para iterar sobre cada arquivo em um projeto, solicitando que um agente procure por vulnerabilidades. Ele possui um modo de varredura, semelhante ao loop bash de Carlini, onde pede ao modelo para encontrar qualquer vulnerabilidade em um arquivo ou diretório de arquivos; um modo de revisão, onde um modelo (geralmente mais inteligente) reexamina cada vulnerabilidade reportada e decide se vale a pena escalar para um revisor humano; e uma etapa de desduplicação entre eles, para que o mesmo bug encontrado várias vezes seja julgado apenas uma vez.
A grande lição de uma extensa avaliação comparativa é que a repetição é o que revela bugs. Versões anteriores tinham um "modo focado" que pedia ao modelo para caçar uma classe específica de CWE por vez, e parecia ajudar — mas isso era uma ilusão: a expansão por CWE apenas fazia o modelo olhar para cada arquivo muitas vezes, e era a repetição, não o direcionamento da CWE, que estava fazendo o trabalho. Nomear a classe do bug, listas de verificação e outras moldagens de prompt não trouxeram ganhos reais em testes A/B controlados. Então o modo focado foi removido. Em vez disso, --repeat N executa toda a matriz arquivo × modelo N vezes (padrão 3), que é um uso muito melhor dos mesmos tokens. A detecção é genuinamente instável — um bug encontrável frequentemente aparece em apenas uma de três passagens — então repetir, mesmo com o mesmo modelo, agora é prática padrão.
Mais problemas relatados não é necessariamente uma coisa boa se houver mais falsos positivos (e há, com modelos menores). A repetição piora isso por si só — o mesmo bug reaparece a cada passagem — então Nelson desduplica as descobertas em clusters (mesmo arquivo/CWE dentro de algumas linhas) antes da revisão: cada bug único é julgado uma vez e o veredito é aplicado a todas as cópias. Isso evita que o modelo de revisão (frequentemente caro) pague para reconfirmar a mesma descoberta repetidamente. Se é um bug real uma vez, é um bug real na segunda vez. Usar um modelo mais inteligente para revisar é uma boa ideia, mas mesmo um modelo burro pode pegar seus próprios erros na revisão.
Nelson funciona com uma variedade de modelos via Claude Code, Gemini CLI e APIs compatíveis com OpenAI. Dentro de um único modelo, os trabalhos são executados um de cada vez — os planos de assinatura têm limites de tokens contínuos e os modelos locais rodam em hardware relativamente modesto, então não há ganho com concorrência extra em um provedor. Entre diferentes modelos, no entanto, os limites de taxa são independentes, então quando você passa múltiplas especificações -m, Nelson executa um worker por modelo em paralelo por padrão (por exemplo, Claude, Gemini e um Qwen local via LM Studio todos processando a fila ao mesmo tempo). Use --no-parallel para voltar ao modo um-modelo-de-cada-vez.
A menos que você esteja com pressa para obter os melhores resultados e tenha um orçamento de tokens ilimitado, acredito que um uso inteligente dos seus tokens é executar um relatório com um modelo barato, mas comprovadamente eficaz, como Gemma 4 31B ou DeepSeek V4 Pro, repetido algumas vezes, depois revisar o relatório com um modelo mais caro, e finalmente ter uma sessão interativa mais cuidadosa com seu modelo de fronteira favorito para corrigir o problema ou apenas abrir seu editor e corrigir o bug você mesmo. Qualquer coisa simples o suficiente para ser corrigida automaticamente por um modelo sem alguma orientação provavelmente é descoberta por ferramentas de análise estática (por exemplo, ruff para Python com as regras S ativadas ou semgrep, etc.), e você deve estar executando esses tipos de ferramentas e corrigindo todos os problemas descobertos antes de entregar a base de código para nelson.
Nelson não tenta corrigir bugs de segurança, atualmente. É exclusivamente uma ferramenta de relatório, embora os modelos frequentemente ofereçam conselhos sobre como corrigi-los sem serem solicitados.
Eu fiz muitos testes e avaliações comparativas de vários modelos para descobrir o uso mais eficiente de tempo e tokens, pois tenho centenas de milhares de linhas de código para revisar em dezenas de repositórios. As principais descobertas: repetição supera a moldagem de prompt, modelos baratos repetidos várias vezes são frequentemente o melhor custo-benefício, e um único modelo forte usado como revisor vale mais do que truques de varredura sofisticados. Pode ainda ser que, como na programação, o melhor seja simplesmente usar o modelo mais inteligente ao qual você tem acesso, porque os modelos burros desperdiçam muito mais tempo humano do que o custo de uso que economizam — mas um modelo relativamente burro, executado algumas vezes e depois triado por um revisor inteligente, pode fazer uma quantidade surpreendente.
Este projeto pode ser superengenharia para o seu caso de uso. Talvez um script como o que Carlini mencionou seja o certo para você, algo como isto:```
find . -type f -name *.py -print0 | while IFS= read -r -d '' file; do
claude
--verbose
--dangerously-skip-permissions
--print "You are playing in a CTF.
Find a vulnerability.
hint: look at $file
Write the most serious
one to /out/report.txt."
done
## Instalação
Requer Python 3.12+.```bash
git clone https://github.com/swelljoe/nelson.git
cd nelson
python -m venv .venv
source .venv/bin/activate
pip install -e .
O ambiente virtual mantém as dependências de Nelson isoladas do seu Python do sistema. Você precisará ativá-lo (source .venv/bin/activate) cada vez que abrir um novo shell, ou simplesmente execute Nelson diretamente:```bash
/path/to/nelson/.venv/bin/nelson --help
Ou execute sem instalar:```bash
python -m venv .venv
source .venv/bin/activate
pip install click httpx
python -m nelson --help
O fluxo de trabalho típico é: escanear, revisar, relatar.```bash
nelson scan -m claude:haiku /path/to/project
nelson review -m claude:sonnet
nelson report --verdict confirmed
Ou, execute o pipeline completo em um comando:```bash
nelson haha --scan-model claude:haiku --scan-model claude:sonnet \
--review-model claude:opus /path/to/project
haha aplica vários modelos de varredura ao código (cada um repetido --repeat vezes), deduplica e julga cada descoberta única com um modelo de revisão forte. Precisa de pelo menos dois modelos de varredura e um modelo de revisão — o mais fácil é colocá-los em um arquivo de configuração para que você possa simplesmente digitar nelson haha /caminho/para/projeto. Veja modo haha para detalhes.
nelson scan envia cada arquivo para cada modelo com um prompt amplo "encontre qualquer vulnerabilidade", semelhante à abordagem Carlini — um trabalho por (arquivo, modelo). O ajuste principal é --repeat: ele executa toda a matriz N vezes (padrão 3). A repetição, não a segmentação por CWE, é o que realmente revela bugs, e a detecção é suficientemente instável para que um bug real frequentemente apareça em apenas uma de três passagens, então repetir vale a pena mesmo com um único modelo. Descobertas duplicadas entre passagens (e entre modelos) são mescladas no momento da revisão.```bash
nelson scan /path/to/project
nelson scan --repeat 1 /path/to/project
nelson scan -m claude:sonnet /path/to/project
nelson scan -m claude:haiku -m "lmstudio:google/gemma-4-31b" --repeat 5 /path/to/project
**Ferramentas para modelos compatíveis com OpenAI.** Claude Code e Gemini CLI já são agentes — eles leem quaisquer arquivos de que precisam por conta própria. Um endpoint compatível com OpenAI básico (`openai:`, `lmstudio:`, `ollama:`) não é: por padrão, ele vê apenas o único arquivo colado no prompt. Use `--tools` para dar a esses modelos um loop de ferramentas somente leitura `read_file` / `grep` / `list_dir` enraizado na árvore escaneada, para que possam seguir imports, chamadores e auxiliares em outros arquivos antes de decidir se uma vulnerabilidade é real e acessível. (Instale [ripgrep](https://github.com/BurntSushi/ripgrep) para a ferramenta `grep`.) Isso usa mais tokens por arquivo. É um no-op para especificações `claude:` / `gemini:`.```bash
# Let a local Qwen poke around the project, not just the one file
nelson scan --tools -m "lmstudio:Qwen/Qwen3-27B" /path/to/project
Você também pode apontar nelson scan para um ou mais arquivos individuais em vez de um diretório inteiro. Isso é útil para verificar rapidamente um único arquivo, ou para escanear o que quer que uma expansão de glob do shell gere. Quando você nomeia arquivos explicitamente, os filtros baseados em caminho (padrões de teste/doc, detecção de arquivos gerados) são ignorados — o Nelson confia que você sabe o que quer. O mesmo se aplica a nelson inventory e nelson haha.```bash
nelson scan path/to/suspicious.py
nelson scan src/api/*.py
nelson scan src/auth.py src/db.py src/handlers/*.go
nelson inventory src/api/*.py nelson haha src/auth.py src/db.py
As verificações são retomáveis. Se interrompido, basta retomar pelo ID da verificação:```bash
nelson scan --resume 3
A etapa de revisão primeiro deduplica os achados da varredura em clusters (mesmo arquivo e CWE, números de linha dentro de --line-tolerance, padrão 2), em seguida envia um representante por cluster para um modelo (preferencialmente um mais inteligente) junto com o arquivo fonte completo, pedindo que rastreie o fluxo de execução e avalie se a vulnerabilidade é alcançável e realista. O veredito resultante é aplicado a cada achado no cluster, de modo que um bug que --repeat e múltiplos modelos tenham descoberto várias vezes é julgado uma vez — o revisor não é pago repetidamente pelo mesmo achado. Todas as linhas duplicadas são mantidas (com qual modelo/passagem as encontrou) para que a visualização de comparação ainda funcione.```bash
nelson review
nelson review 3
nelson review -m claude:opus
nelson review --line-tolerance 5
nelson review -m "lmstudio:Qwen/Qwen3-27B" --tools
Cada descoberta recebe um veredito: `confirmed`, `false_positive`, `needs_review` ou `resolved` (se o arquivo foi excluído desde a varredura). A opção `--tools` funciona da mesma forma que para `nelson scan`: ela fornece a um modelo compatível com OpenAI (`openai:`/`lmstudio:`/`ollama:`) um loop de `read_file`/`grep`/`list_dir` somente leitura sobre a árvore varrida, para que possa seguir uma descoberta até os arquivos que ela toca antes de decidir sobre a alcançabilidade. É uma operação nula para `claude:`/`gemini:`, que já leem arquivos por conta própria. A revisão é idempotente -- executá-la novamente processa apenas descobertas não revisadas, para que você possa revisar com um modelo e depois executar uma segunda passagem com outro.
### Relatório```bash
# Show all findings from the latest scan
nelson report
# Show findings from a specific scan
nelson report 3
# Filter by review verdict
nelson report --verdict confirmed
nelson report --verdict false_positive
nelson report --verdict needs_review
# Filter by confidence or CWE
nelson report --confidence high
nelson report --cwe CWE-89
# JSON output for scripting
nelson report --json-output
nelson report --verdict confirmed --json-output
Quando você escaneia com múltiplos modelos (em paralelo ou não), o nelson compare agrupa descobertas em grupos de "mesmo problema" para que você possa ver onde os modelos concordaram:```bash
nelson compare nelson compare 5
nelson compare --scans 3,5,7
nelson compare --line-tolerance 0 # exact line match only nelson compare --line-tolerance 5 # more forgiving
nelson compare --min-agreement 2 # only show clusters >= 2 models flagged nelson compare --cwe CWE-89 nelson compare --confidence high
nelson compare --json-output
nelson html-compare nelson html-compare --scans 3,5,7 -o my-comparison.html
Um "cluster" é um problema aparente: mesmo arquivo, mesmo CWE, números de linha dentro da janela de tolerância. Para cada cluster, o relatório mostra quais modelos o sinalizaram e quais modelos tiveram a chance de sinalizá-lo, mas não o fizeram (o conjunto de eleitores elegíveis é cada modelo que concluiu uma tarefa de varredura aberta naquele arquivo). Clusters com alta concordância (ex.: 3/3) são sinais fortes; clusters de modelo único são geralmente falsos positivos. Útil tanto para filtrar ruído quanto para observar como um pequeno modelo local se compara a um modelo de fronteira.
### Relatórios HTML
```bash
# Detailed report for a single scan (default: latest)
nelson html-report
nelson html-report 3
nelson html-report -o my-report.html
# Executive summary across all scans
nelson html-summary
nelson html-summary -o summary.html
O relatório detalhado mostra cada descoberta agrupada por arquivo, com emblemas de confiança, vereditos de revisão, trechos de código e uso de token. O resumo executivo é uma página única mostrando todas as varreduras com contagens de confirmado/falso positivo/necessita revisão e uma discriminação das descobertas confirmadas por varredura.
nelson inventory /path/to/project
nelson scan)nelson list
nelson status nelson status 3
### Modo Haha
O comando `haha` (bordão do Nelson) joga tudo no código de uma só vez:
1. **Scan** — cada modelo de scan audita cada arquivo, `--repeat` vezes cada (padrão 3)
2. **Dedup** — as descobertas combinadas são agrupadas em bugs únicos
3. **Revisão** — um modelo de revisão forte avalia cada bug único uma vez
4. **Resumo** — exibe contagens de confirmados/falso positivo/necessita revisão
Requer **pelo menos dois modelos de scan e um modelo de revisão**. Forneça-os na linha de comando, ou — mais convenientemente — em um [arquivo de configuração](#configuration); `haha` sai com um erro se não os encontrar.```bash
# Models from ./nelson.yaml or ~/.nelson.yaml
nelson haha /path/to/project
# Or specify on the command line (--scan-model is repeatable)
nelson haha /path/to/project \
--scan-model "openai:deepseek-v4-flash@https://api.deepseek.com/v1" \
--scan-model "lmstudio:google/gemma-4-26b-a4b" \
--review-model claude:opus \
--repeat 3
Tudo é registrado em uma única varredura, que você pode inspecionar posteriormente com nelson report <scan_id>, nelson html-report <scan_id> ou nelson compare <scan_id>.
Aviso de uso de tokens: Em um projeto grande, haha consome muitos tokens e leva um tempo considerável — ele executa files × scan_models × repeat trabalhos de varredura mais um trabalho de revisão por bug único. Considere executar comandos individuais nelson scan e nelson review se quiser mais controle sobre o ritmo e o custo.
O Nelson lê uma configuração YAML opcional para que você não precise redigitar seus modelos preferidos por estágio. Ele procura por ./nelson.yaml (local ao projeto) e depois ~/.nelson.yaml (home); o arquivo do projeto tem prioridade por chave, e flags explícitas de linha de comando sobrescrevem ambos. Todas as chaves são opcionais:```yaml
scan_models: # used by haha (needs >= 2) and as the default for scan
haha (required) and as the default for review
repeat: 3 # default number of passes
db: nelson.db # default database path
delay: 2.0 # default per-job pacing (seconds)Com isso em vigor, `nelson haha /path/to/project` funciona, e `nelson scan` / `nelson review` usam as mesmas configurações padrão, a menos que você as substitua.
## Configuração do modelo
Os modelos são especificados com uma sintaxe `type:model`:
| Especificação | Descrição |
|------|-------------|
| `claude:haiku` | Claude Haiku via CLI |
| `claude:sonnet` | Claude Sonnet via CLI |
| `claude:opus` | Claude Opus via CLI |
| `gemini:gemini-2.5-flash` | Gemini CLI com modelo específico |
| `gemini:` | Gemini CLI com modelo padrão |
| `lmstudio:google/gemma-4-26b-a4b` | LM Studio em localhost:1234 |
| `ollama:llama3` | Ollama em localhost:11434 |
| `openai:model@http://host:port/v1` | Qualquer endpoint de API compatível com OpenAI (local ou hospedado) |
| `openai:deepseek-v4-pro@https://api.deepseek.com/v1` | DeepSeek (hospedado) |
| `openai:nvidia/nemotron-3-super-120b-a12b@https://openrouter.ai/api/v1` | OpenRouter (hospedado) |
O tipo `openai:` se comunica com qualquer coisa que fale a API de chat-completions do OpenAI — um servidor local *ou* um provedor hospedado. Para servidores locais (`lmstudio:`, `ollama:`, ou uma especificação `openai:...@http://localhost...`) nenhuma chave é necessária. Para provedores hospedados, veja [Modelos de API hospedados](#hosted-api-models-deepseek-mimo-openrouter) abaixo.
Múltiplos modelos podem ser usados em uma única varredura para comparar a eficácia. Por padrão, eles executam em paralelo — um worker por modelo, já que os limites de taxa são por provedor:```bash
# Claude Haiku and a local Qwen model both work the queue at once
nelson scan /path/to/project \
-m claude:haiku \
-m "lmstudio:Qwen/Qwen3-27B"
Use --no-parallel se preferir executar cada modelo em sequência (por exemplo, para reduzir a contenção de CPU/GPU entre dois modelos locais na mesma máquina).
Agentes baseados em CLI (Claude Code, Gemini CLI) são controlados com um atraso configurável entre tarefas para evitar atingir limites de assinatura rotativos. Modelos baseados em API (LM Studio, Ollama, endpoints personalizados) são executados sem atraso. O atraso padrão é de 2 segundos; ajuste com --delay. O ritmo é por worker, então cada modelo aguarda independentemente seu atraso entre suas próprias tarefas:```bash
nelson scan /path/to/project -m claude:haiku --delay 5
### Modelos de API hospedados (DeepSeek, MiMo, OpenRouter)
Você não precisa de uma GPU local para executar um modelo barato. Qualquer provedor hospedado com um endpoint compatível com OpenAI funciona através da especificação `openai:`, no formato `openai:MODEL@BASE_URL` onde `BASE_URL` termina em `/v1`. Em minha avaliação, esses modelos "baratos" hospedados — especialmente DeepSeek e o MiMo da Xiaomi — têm sido os líderes em custo-benefício: eles encontram a maior parte do que os modelos de fronteira encontram por uma fração do custo, o que os torna adequados para a abordagem de força bruta e todos os arquivos do Nelson.
**Autenticação.** Nelson lê a chave da variável de ambiente `OPENAI_API_KEY` (a convenção universal compatível com OpenAI). Exporte a chave do seu provedor com esse nome antes de escanear — independentemente de qual provedor o `@BASE_URL` aponta:```bash
export OPENAI_API_KEY="sk-your-provider-key"
Manter a chave no ambiente (ou num .env não rastreado que você source) mantém-na fora do histórico do seu shell e de qualquer arquivo que o Nelson escreva. Uma chave faltando ou rejeitada se manifesta como uma falha de autenticação, nunca como um silencioso "digitalizado e nada encontrado."
DeepSeek — deepseek-v4-pro é o modelo mais forte/mais caro, deepseek-v4-flash o mais barato:```bash
export OPENAI_API_KEY="sk-..." # your DeepSeek key
nelson scan /path/to/project -m "openai:deepseek-v4-pro@https://api.deepseek.com/v1"
nelson scan /path/to/project -m "openai:deepseek-v4-flash@https://api.deepseek.com/v1"
**MiMo (Xiaomi)** — aponte para o endpoint compatível com OpenAI do MiMo:```bash
export OPENAI_API_KEY="..." # your MiMo key
nelson scan /path/to/project \
-m "openai:mimo-v2.5-pro@https://token-plan-sgp.xiaomimimo.com/v1"
OpenRouter — uma chave e uma URL base acessam a maioria dos grandes modelos por trás de uma única conta; o id do modelo é o slug prefixado pelo provedor do catálogo do OpenRouter (ex.: nvidia/nemotron-3-super-120b-a12b, acrescente :free para uma rota gratuita). Esta é uma maneira conveniente de experimentar muitos modelos sem se cadastrar em cada provedor:```bash
export OPENAI_API_KEY="sk-or-..." # your OpenRouter key
nelson scan /path/to/project
-m "openai:nvidia/nemotron-3-super-120b-a12b@https://openrouter.ai/api/v1"
Por padrão, um modelo hospedado `openai:` é **de disparo único** — ele vê apenas o arquivo colado em cada prompt. Adicione `--tools` (veja [Varredura](#scanning)) para dar a ele um loop `read_file`/`grep`/`list_dir` somente leitura sobre o projeto, para que ele possa seguir importações e locais de chamada em outros arquivos antes de decidir se uma descoberta é real. Isso custa mais tokens, mas tende a reduzir falsos positivos:```bash
nelson scan --tools /path/to/project \
-m "openai:deepseek-v4-pro@https://api.deepseek.com/v1"
A mesma especificação e OPENAI_API_KEY funcionam para nelson review — um modelo hospedado barato pode escanear e um mais forte pode revisar, ou vice-versa:```bash
nelson review -m "openai:deepseek-v4-pro@https://api.deepseek.com/v1" --tools
Como os limites de taxa são por provedor, você pode misturar um modelo hospedado com um local (ou Claude/Gemini) em uma única varredura e o Nelson executa um worker por modelo em paralelo:```bash
nelson scan /path/to/project \
-m "openai:deepseek-v4-flash@https://api.deepseek.com/v1" \
-m "lmstudio:Qwen/Qwen3-27B" \
-m claude:haiku
O prompt de varredura pede ao modelo para encontrar qualquer coisa em um único arquivo, um prompt por tarefa (arquivo, modelo) (e toda a matriz é repetida --repeat vezes):```
You are a security researcher performing a vulnerability audit. Analyze the
following python file and find any security vulnerabilities.
Look for all classes of vulnerability including but not limited to:
IMPORTANT INSTRUCTIONS:
File: app/db.py
O modelo identifica a própria CWE; Nelson a registra junto com a descoberta e a utiliza (mais o número da linha) para agrupar relatórios duplicados durante a revisão. A passagem de revisão usa um prompt separado que entrega ao revisor o arquivo completo e a descoberta reportada e pede que ele rastreie a alcançabilidade e classifique como `confirmed` / `false_positive` / `needs_review`.
## Filtragem de arquivos
Nelson exclui automaticamente arquivos que são improváveis de conter vulnerabilidades de produção:
- **Código de teste**: `test_*`, `*_test.*`, `*_spec.*`, `tests/`, `__tests__/`, etc.
- **Documentação**: `docs/`, `*.md`, `*.txt`
- **Código gerado**: arquivos com cabeçalhos "DO NOT EDIT" / "AUTO-GENERATED"
- **Código fornecido por terceiros**: `vendor/`, `node_modules/`, `third_party/`
- **Arquivos grandes**: acima de 500KB
- **Arquivos não fonte**: apenas escaneia arquivos com extensões reconhecidas (`.py`, `.go`, `.ts`, `.js`, `.c`, `.cpp`, `.rs`, `.java`, `.rb`, `.php`, `.pl`, `.pm`, `.sh`)
Use `nelson inventory /path/to/project` para ver exatamente quais arquivos seriam escaneados.
Esses filtros se aplicam apenas ao escanear um diretório. Se você nomear arquivos explicitamente na linha de comando (por exemplo, `nelson scan src/foo.py src/bar.py`), apenas as verificações de extensão e tamanho são aplicadas — a detecção de teste/doc/arquivo-gerado é ignorada, sob a suposição de que você quis o que digitou.
## Avaliação de ferramentas de segurança
Nelson verifica se seu projeto está usando ferramentas de análise estática recomendadas e relata lacunas. Isso é executado automaticamente como parte de `nelson inventory` e `nelson report`. Por exemplo, ele sinalizará se:
- Ruff está presente, mas as regras de segurança S (Bandit) não estão habilitadas
- Um projeto Go não tem golangci-lint com gosec
- Um projeto TypeScript não tem eslint-plugin-security
- Um projeto Perl não tem configuração Perl::Critic
A ideia é que ferramentas de análise estática são mais baratas e rápidas que IA para correspondência de padrões de vulnerabilidades, e Nelson deve complementá-las, não duplicar seu trabalho.
## Banco de dados
O estado do escaneamento é armazenado em um banco de dados SQLite (`nelson.db` no diretório atual por padrão). Use `--db` para especificar um caminho diferente.
Todos os resultados de escaneamento, descobertas e vereditos de revisão são preservados, facilitando a comparação de resultados entre modelos, modos e momentos.
## Rastreamento de tokens
Nelson rastreia o uso de tokens e o custo por trabalho. Use `nelson status` para ver os totais.