Framework autônomo de pesquisa em segurança que integra análise estática, análise binária, fuzzing, validação de vulnerabilidades baseada em LLM, geração de exploits e criação de patches para operações ofensivas e defensivas.
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ ██████╗ █████╗ ██████╗ ████████╗ ██████╗ ██████╗ ║
║ ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗ ║
║ ██████╔╝███████║██████╔╝ ██║ ██║ ██║██████╔╝ ║
║ ██╔══██╗██╔══██║██╔═══╝ ██║ ██║ ██║██╔══██╗ ║
║ ██║ ██║██║ ██║██║ ██║ ╚██████╔╝██║ ██║ ║
║ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ║
║ ║
║ Autonomous Offensive/Defensive Research Framework ║
║ Based on Claude Code (v3.1.0) ║
║ ║
║ Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake) ║
║ Michael Bargury, John Cartwright ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════╝
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣠⣤⣤⣀⣀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣾⣿⣿⠿⠿⠟
⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⣀⣀⣀⣤⣴⣶⣶⣶⣤⣿⡿⠁⠀⠀⠀
⣀⠤⠴⠒⠒⠛⠛⠛⠛⠛⠿⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⣿⣿⣿⡟⠻⢿⡀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⢿⣿⠟⠀⠸⣊⡽⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⡇⣿⡁⠀⠀⠀⠉⠁⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠻⠿⣿⣧⠀ Get them bugs.....⠀⠀⠀⠀⠀
Autores: Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake), Michael Bargury, John Cartwright (@gadievron, @danielcuthbert, @thomasdullien, @mbrg, @grokjc)
Licença: MIT, consulte LICENSE. Observe que o CodeQL possui sua própria licença e não permite uso comercial.
Repositório: https://github.com/gadievron/raptor
O RAPTOR é um framework autônomo de pesquisa em segurança construído sobre o Claude Code (mas não vinculado a ele — você também pode conectar sua própria camada de análise). Ele combina análise estática, análise binária, validação de vulnerabilidades com tecnologia LLM, geração de exploits e escrita de patches em um único fluxo de trabalho que você pode executar contra um código-fonte ou binário.
Não é um software polido. Foi construído no tempo livre, mantido unido com entusiasmo e fita adesiva, e funciona bem o suficiente para não conseguirmos parar de usá-lo. Se quiser melhorá-lo, abra um PR.
RAPTOR significa Recursive Autonomous Penetration Testing and Observation Robot (Robô Autônomo e Recursivo de Testes de Penetração e Observação). Queríamos muito chamá-lo de RAPTOR.
O RAPTOR é, em sua maior parte, código gerado por IA. Os humanos definem a direção, revisam a saída e tomam decisões de design; a IA escreve a implementação. A verificação mecânica (testes, análise estática, calibração de corpus) mantém o padrão de qualidade onde precisa estar, independentemente de quem — ou o quê — escreveu o código.
pip install semgrep) para análise estática. O CodeQL é opcional, mas recomendado.Para a camada de despacho de análise (o LLM que analisa descobertas individuais), o próprio Claude Code lida com tudo por padrão — nenhuma chave de API extra é necessária. Se você quiser análise com vários modelos (por exemplo, Claude + GPT + Gemini), precisará de chaves de API para cada provedor. Consulte Usando um LLM diferente abaixo.
git clone https://github.com/gadievron/raptor.git cd raptor
pip install -r requirements.txt
npm install -g @anthropic-ai/claude-code
pip install semgrep
export PATH="$PATH:$PWD/bin"
raptor
O lançador `raptor` é a forma recomendada de iniciar uma sessão, e funciona a partir de qualquer diretório — ele resolve a instalação do RAPTOR, lembra o diretório a partir do qual você lançou (para que comandos como `/scan` usem-no como padrão), executa as verificações de confiança e de projeto pré-voo, carrega o plugin de rastreamento de cobertura e sanitiza o ambiente antes de entregar o controle ao Claude Code. Ele também aceita um caminho de destino opcional e flags como `--project`, `--continue` e `--model` — veja `raptor --help`.
Executar `claude` diretamente de dentro do diretório do repositório também funciona — o Claude Code capta a configuração do RAPTOR a partir do checkout — mas você pula tudo o que o lançador faz acima: sem verificações pré-voo, sem rastreamento de cobertura, e comandos que usam como padrão "o diretório a partir do qual você executou" não conseguem vê-lo.
**Importante:** o RAPTOR carrega sua configuração a partir do diretório do repositório. Se você executar `claude` a partir de qualquer outro diretório, obtém o Claude Code puro, não o RAPTOR. O lançador `raptor` evita esse modo de falha por completo.
### Opção 2: Executar em um contêiner (recomendado)
Usar contêineres é uma prática de segurança comum para restringir agentes de acessar áreas do seu sistema de arquivos que você não quer que eles acessem, além de limitar o raio de impacto de qualquer código malicioso que possa ser executado (por exemplo, via ataque à cadeia de suprimentos). A imagem é grande (cerca de 6 GB). Ela parte do devcontainer Microsoft Python 3.12 e adiciona ferramentas de análise estática, fuzzing e automação de navegador.
Você pode baixar uma imagem pré-construída:```bash
docker pull danielcuthbert/raptor:latest
or crie-o localmente usando o Dockerfile incluído:```bash
docker build -f .devcontainer/Dockerfile -t raptor:latest .
A imagem espera que o framework RAPTOR (este repositório) seja montado em `/workspaces/raptor` na inicialização. Opcionalmente, você pode montar uma pasta de destino para análise local.
Para iniciar o contêiner:```bash
docker run -it \
-v "$(pwd):/workspaces/raptor" \
raptor:latest
Para montar também uma pasta de destino:```bash
docker run -it
-v "$(pwd):/workspaces/raptor"
-v "/path/to/target-folder:/workspaces/target"
raptor:latest
Adicione `--privileged` se precisar do depurador determinístico `rr`.
Os devcontainers do VS Code também são suportados. Para montar uma pasta de destino, adicione-a à seção `mounts` de `.devcontainer/devcontainer.json`:```jsonc
"mounts": [
// ...existing entries...
"source=/path/to/target-folder,target=/workspaces/target,type=bind,consistency=cached"
]
Em seguida, abra o repositório no VS Code — ele solicitará que você o reabra no contêiner:```bash cd /path/to/raptor code .
De qualquer forma, uma vez dentro do contêiner, execute `raptor` para começar.
---
## O que esperar na primeira execução
A coisa mais simples que você pode fazer:```
/scan /path/to/code
Este executa o Semgrep (mais Coccinelle quando o spatch está instalado; adicione --codeql para CodeQL) contra o alvo, remove duplicatas dos achados e grava um relatório SARIF. Sem análise por LLM, sem chaves de API além do Claude Code. Leva alguns minutos em um repositório típico.
Para adicionar validação com LLM:``` /agentic /path/to/code
Isto executa o pipeline completo: scan, deduplicação e, em seguida, envia cada descoberta pelas etapas de validação (A-F). Em uma base de código de médio porte com ~50 descobertas, espere 10-30 minutos e $2-8 em custos de LLM na camada de análise (dependendo do modelo). O limite de custo padrão é $10 por execução; ajuste com `--max-cost-usd`.
**Nota de custo:** A camada de orquestração do Claude Code usa sua assinatura do Claude. A camada de despacho de análise faz chamadas de API LLM separadas que são cobradas por token. Se você usar apenas o Claude Code como modelo de análise (o padrão), não há custo extra além da sua assinatura. Se você configurar modelos externos (OpenAI, Gemini, etc.), essas chamadas de API serão cobradas nesses provedores.
---
## Modelo de segurança
O RAPTOR executa código gerado por LLM e analisa repositórios não confiáveis. Subprocessos que lidam com conteúdo não confiável são isolados em sandbox usando namespaces Linux, Landlock e seccomp. O sandbox bloqueia acesso à rede, restringe a visibilidade do sistema de arquivos e limita o consumo de recursos. Consulte `docs/sandbox.md` para o modelo de ameaça completo e a configuração.
Variáveis de ambiente que poderiam injetar código na cadeia de inicialização são removidas na inicialização (`core/security/_dangerous_env_strip.sh`). Caminhos de arquivo de repositórios escaneados nunca são interpolados em strings de shell — todas as chamadas de subprocesso usam argumentos baseados em lista.
---
## O que o RAPTOR pode fazer
| Comando | O que faz | Status |
|---------|-------------|--------|
| `/agentic` | Fluxo de trabalho autônomo completo: scan, validar, explorar, corrigir | Estável |
| `/scan` | Análise estática com Semgrep e CodeQL | Estável |
| `/understand` | Mapear superfície de ataque, rastrear fluxos de dados, caçar variantes de vulnerabilidades | Estável |
| `/binary` | Investigação binária de caixa-preta, evidências em tempo de execução, consultas de grafo e handoff | Beta |
| `/ghidra` | Ponte RE do Ghidra: anexar/importar projetos `.gpr`, diff entre versões, exportação de descobertas | Beta |
| `/audit` | Revisão sistemática de código orientada por hipóteses e fundamentada em ferramentas | Beta |
| `/review` | Consultar estado da auditoria: descobertas, lacunas, cobertura, notas do operador | Estável |
| `/annotate` | Anexar anotações de prosa livres por função (notas de revisão do operador) | Estável |
| `/validate` | Pipeline de validação de explorabilidade em múltiplas etapas (Etapas 0-F) | Estável |
| `/diagram` | Mapas visuais Mermaid a partir de saídas JSON de `/understand` e `/validate` | Beta |
| `/codeql` | Análise profunda somente com CodeQL com pré-triagem de fluxo de dados SMT | Estável |
| `/analyze` | Analisar descobertas SARIF existentes com LLM, sem re-escanear | Estável |
| `/sca` | Análise de composição de software: dependências, avisos, sinais de supply-chain, SBOMs e correções | Beta |
| `/cve-diff` | Descobrir e comparar o commit de correção de um CVE em OSV, NVD, GitHub e GitLab | Beta |
| `/cve-env` | Construir e verificar um ambiente Docker executando o aplicativo afetado por um CVE em sua versão pré-correção | Experimental |
| `/exploit` | Gerar código de exploit proof-of-concept | Beta |
| `/patch` | Gerar correções seguras para vulnerabilidades confirmadas | Beta |
| `/fuzz` | Fuzzing binário com AFL++ e análise de crashes | Estável |
| `/crash-analysis` | Análise autônoma de causa raiz para crashes em C/C++ | Estável |
| `/oss-forensics` | Investigação forense baseada em evidências para repositórios GitHub | Estável |
| `/project` | Espaços de trabalho nomeados para organizar execuções e rastrear descobertas ao longo do tempo | Estável |
| `/describe` | Descrever um alvo: mix de linguagens, sistema de build, lacunas de ferramentas, estimativa de custo (somente leitura) | Estável |
| `/threat-model` | Criar, inspecionar e manter modelos de ameaça por projeto | Estável |
| `/sage` | Camada de memória persistente (armazenar, recuperar, vincular, corroborar) | Estável |
| `/ask` | Enviar um prompt livre para qualquer modelo LLM configurado | Estável |
| `/scorecard` | Inspecionar confiabilidade por modelo em classes de decisão | Estável |
| `/frida` | Instrumentação dinâmica via Frida | Alpha |
| `/web` | Varredura de aplicações web: crawl, integração ffuf/nuclei, injeção verificada por oracle, callbacks SSRF cegos | Beta |
---
## Como o pipeline funciona
Comece criando um projeto para que todas as suas execuções fiquem em um só lugar:```
/project create myapp --target /path/to/code # create a project first
/project use myapp # set it as active
/understand --map # map the attack surface
/agentic --threat-model --validate # map, model, scan, validate
/project findings # review everything in one place
Para um artefacto compilado, o ponto de partida equivalente é:```text /binary investigate /path/to/binary # build the evidence-backed binary map /binary graph --edges --json # query the persisted graph /binary trace-parser # collect runtime parser evidence /binary harness # draft a harness only when the boundary is explicit
`/understand` constrói um mapa de contexto de pontos de entrada, limites de confiança e sinks antes de qualquer linha de digitalização acontecer. `/agentic` então executa Semgrep e CodeQL, deduplica as descobertas e despacha cada uma para validação usando a metodologia exploitation-validator:
Com `--threat-model`, o RAPTOR executa o mapa primeiro, cria `threat-model.json` e `THREAT_MODEL.md` se o projeto ainda não os tiver, e então alimenta uma versão compacta em `/understand`, análise autónoma e `/validate`. Os modelos de ameaça existentes do projeto são preservados a menos que passes `--threat-model-refresh`; mapas de recurso desatualizados são recusados a menos que passes explicitamente `--threat-model-use-stale`. Também converte fluxos não verificados mapeados em SARIF candidato para que falhas do scanner não matem a execução. É contexto de propriedade do operador, não prova mágica: as descobertas ainda precisam de evidência de código ou confirmação apoiada por oráculo. Consulta `docs/threat-model.md`.
- Etapa A: o padrão é realmente uma vulnerabilidade, ou a ferramenta está a fazer correspondência de padrões por ruído?
- Etapa B: o que um atacante precisa para o alcançar, e o que se interpõe no caminho?
- Etapa C: o caminho de código existe realmente? pode ser alcançado a partir do exterior?
- Etapa D: decisão final — é código de teste, requer pré-condições irrealistas, o modelo está a fazer hedging?
- Etapa E: viabilidade de exploração binária (quando um artefacto compilado está disponível)
- Etapa F: auto-revisão — alguma etapa anterior fez hedging ou contradisse-se?
As descobertas que passam na validação recebem PoCs de exploração e patches gerados. Uma análise entre descobertas é executada no final para encontrar causas-raiz partilhadas e cadeias de ataque.
`/validate` executa este mesmo pipeline como um passo autónomo se já tiveres descobertas de uma digitalização anterior.
Para um artefacto compilado, `/binary <path>` agora executa uma investigação
com evidência em primeiro lugar em vez de despejar uma pilha de artefactos
brutos de engenharia reversa sobre o operador. Por baixo, ainda constrói o
manifesto vinculado a SHA-256, o registo de evidências, o mapa de contexto,
a checklist e o grafo SQLite a partir de metadados de ficheiros, imports e
xrefs do radare2. Apps Mach-O também recebem inventário de slices, metadados
de bundle e seletores de classes Objective-C / Swift; pseudocódigo de alto
valor é persistido em vez de desaparecer dentro da execução. Exports de DLLs
PE, dispatchers de drivers Windows e handlers de ioctl de módulos de kernel
Linux são tratados como os seus próprios candidatos de ingresso também, com
a arquitetura PE lida a partir do cabeçalho COFF em vez de adivinhada. A
camada de investigação então consulta esse grafo, classifica o ingresso
externo antes de pistas genéricas de sink, descobre binários helper/irmãos
declarados e escreve um relatório compacto dividido em factos, inferências
estruturais e hipóteses não comprovadas. Observações do Frida, testemunhas
de crashes de fuzzing, verificações explícitas do Z3 e diffs binários podem
adicionar evidência mais forte mais tarde. O RAPTOR também mantém o grafo de
chamadas interno necessário para recuperar candidatos limitados de
ingresso-para-parser, para que um callback de app possa ser reduzido à
função interna que realmente chama `XML_Parse`, `d2i_X509`,
`jpeg_read_header` ou outra superfície de parser real sem fingir que isso é
prova de taint. `/binary trace-parser <run-dir>` é o acompanhamento dinâmico
explícito: executa o trace de parser estreito do Frida e depois atualiza o
mesmo mapa de contexto, handoff, grafo e relatório de investigação no lugar.
`/binary investigate --active` mapeia primeiro e só lança uma campanha de
fuzzing real quando existe um limite de harness concreto; alvos de app, DLL e
driver recebem um passo de harness ou snapshot em vez disso. `/binary harness`
escreve uma especificação de harness apoiada por evidências para o ingresso
escolhido e só emite código-fonte candidato quando o contrato ABI ou IOCTL é
explícito. Não inventa o caminho de “`memcpy` existe” para “isto é
explorável”: imports, seletores e arestas de chamada permanecem candidatos
até algo mecânico provar mais. Consulta `docs/binary-analysis.md`.
---
## Análise de Composição de Software
`/sca` analisa o lado de dependências e cadeia de fornecimento de um projeto. Não é apenas uma pesquisa de CVE em ficheiros de requisitos: o RAPTOR descobre manifests, lockfiles, comandos de instalação inline, dependências de workflows e fontes de pacotes de container/imagem base, e depois normaliza-os numa única vista de dependências.
A digitalização enriquece as dependências com avisos OSV, CISA KEV, EPSS, CISA Vulnrichment/SSVC, alcançabilidade, sinais de evidência de exploração, verificações de higiene, heurísticas de cadeia de fornecimento, conclusões de política de licenças e revisão/triagem opcional por LLM. Emite descobertas nativas do RAPTOR mais SBOM e saída amigável para CI:
- `findings.json` - descobertas canónicas do RAPTOR
- `report.md` - resumo legível por humanos
- `sbom.cdx.json` - SBOM CycloneDX com dados VEX
- `findings.sarif` - saída de code-scanning do GitHub/GitLab
Comandos comuns:```bash
python3 raptor.py sca --repo /path/to/project
python3 raptor.py sca --repo /path/to/project --no-llm
python3 raptor.py sca --repo /path/to/project --fail-on-severity high --fail-on-kev
python3 raptor.py sca --repo /path/to/project fix
python3 raptor.py sca check PyPI django 4.2.10
Subcomandos úteis incluem fix, check, upgrade, diff, verify, health, render, suppress e clean-cache. Consulte docs/sca.md para a referência completa.
O RAPTOR possui uma integração Z3 em duas camadas (pip install z3-solver). Ela é opcional. Tudo funciona sem ela, mas os resultados são melhores com ela.
Pré-triagem de fluxo de dados (CodeQL)
Quando o CodeQL produz um resultado de caminho, as restrições do caminho são verificadas quanto à satisfatibilidade antes de qualquer chamada de LLM ser feita. Caminhos comprovadamente inalcançáveis são descartados imediatamente. Para caminhos alcançáveis, o Z3 produz entradas candidatas concretas que entram no prompt de análise, para que o LLM tenha algo específico para raciocinar em vez de padrões abstratos.
Análise de restrições one-gadget (viabilidade binária)
Durante a avaliação de viabilidade de exploração binária, o Z3 verifica se as restrições de registradores e memória de um one-gadget são satisfatíveis em relação ao estado concreto do crash. Os gadgets são classificados por alcançabilidade real em vez de heurísticas, para que você gaste tempo em gadgets que podem realmente funcionar.
O Z3 está pré-instalado no devcontainer. Para instalações manuais: pip install z3-solver.
As regras personalizadas do RAPTOR em engine/semgrep/rules/ são totalmente locais e são executadas sem acesso à rede.
Para pacotes de registro (p/security-audit, p/owasp-top-ten, etc.), o diretório de cache é fornecido vazio. Uma ferramenta de cache (engine/semgrep/tools/cache-packs.py) cuida da população:```bash
python3 engine/semgrep/tools/cache-packs.py update
python3 engine/semgrep/tools/cache-packs.py fetch
python3 engine/semgrep/tools/cache-packs.py import semgrep-cache-2026-07-16.zip
python3 engine/semgrep/tools/cache-packs.py list
Uma vez preenchido, o scanner resolve os IDs de pacotes para arquivos locais e nenhuma chamada de rede acontece. Sem o cache, o RAPTOR tentará buscar pacotes de registro do semgrep.dev no momento da varredura; se estiver offline, ele descarta pacotes não armazenados em cache de forma graciosa e executa apenas com regras personalizadas.
O CodeQL precisa de acesso à rede apenas durante a configuração inicial para baixar o CLI e os pacotes de consulta. Uma vez instalado, ele funciona offline.
---
## Regras personalizadas
O RAPTOR inclui mais de 200 regras personalizadas de análise estática, testadas de forma adversarial para eliminar falsos positivos:
- **Semgrep (145 regras)** — regras de rastreamento de taint e padrões para Python, Go, Java e JS/TS. Cobre SQLi, XSS, SSRF, SSTI, injeção de comandos, desserialização, XXE, injeção LDAP/NoSQL, path traversal, open redirect, injeção de log/cabeçalho, injeção de eval, ReDoS, poluição de protótipo, configuração incorreta de JWT, criptografia fraca, TLS inseguro e segredos codificados.
- **Coccinelle (63 regras)** — correspondência estrutural para C/C++. Segurança de memória (double free, use-after-free, free de ponteiro não base, free de array de pilha, memória mmap'd, use-after-close), bugs de inteiros (overflow, extensão de sinal, double sizeof), vazamentos de recursos (incompatibilidade popen/fclose, double close de fdopendir), manipulação de buffers (strncpy sem NUL, incompatibilidade de tamanho copy_user, off-by-one de malloc/strlen), segurança de manipuladores de sinais, uso incorreto de API (domínio de flag fcntl, SIGKILL/SIGSTOP, double byte-swap, buffer estático inet_ntoa), eliminação de dead-store pelo compilador, confusão IS_ERR/PTR_ERR do kernel, injeção de string de formato, corridas TOCTOU e mais.
- **CodeQL (8 consultas)** — rastreamento de taint interprocedural para C++ (injeção de string de formato, truncamento de inteiros, use-after-move, invalidação de iteradores) e Java (XXE, desserialização insegura, injeção de log, SSRF em Spring).
Navegue pelas regras diretamente: `engine/semgrep/rules/`, `engine/coccinelle/rules/`, `engine/codeql/queries/`. Elas complementam os pacotes de registro do Semgrep que o RAPTOR incorpora (`p/security-audit`, `p/owasp-top-ten`, `p/secrets` sempre; pacotes por grupo de política como `p/command-injection`, `p/jwt`, `p/xss` por cima) — a sobreposição é mínima.
---
## Como o RAPTOR verifica a si mesmo
O RAPTOR usa uma boa parte de suas próprias ferramentas de segurança, mas vale a pena ser honesto sobre o que realmente bloqueia um PR e o que apenas roda em segundo plano para nos manter honestos. Parte disso é um bloqueio rígido, parte é uma verificação agendada e parte é apenas um benchmark que mantemos para saber quando pioramos as coisas. O detalhamento completo, incluindo os parâmetros reais e como reproduzir as verificações, está em `docs/ci-controls.md`.
| Controle | O que verifica | Gatilho | Config / evidência |
|---|---|---|---|
| Ruff | Linting de correção de Python (`F401`, `F811`, `F821`, `F841`) | Gate de diff de PR, além de auditoria semanal de árvore completa | `pyproject.toml`, `.github/workflows/lint.yml` |
| Pytest | Limites rápidos de unit/integração, camadas específicas de subsistema (via despacho de grafo de importação), auditoria de envelope de prompt | PRs, pushes para `main`, fila de merge, suíte completa agendada | `pytest.ini`, `.github/workflows/tests.yml`, `.github/workflows/nightly.yml` |
| CodeQL Advanced | Varredura de código Python, C/C++ e GitHub Actions com estreitamento de escopo por grafo de importação | PRs, pushes para `main`, fila de merge, agendamento semanal | `.github/workflows/codeql.yml`, `.github/codeql/codeql-config.yml` |
| Hardening de workflow | Ações de terceiros fixadas por SHA, permissões de privilégio mínimo, linting de metadados de comandos | Toda alteração de workflow e toda execução de lint | `.github/workflows/`, `.github/scripts/check_command_metadata.py` |
| Lint de rótulos de corpus | Validação de esquema de rótulos de corpus de auditoria e verificação de pin upstream | PRs (rótulos alterados), varredura completa semanal | `.github/workflows/corpus-labels.yml` |
| Gate de PR SCA do RAPTOR | Regressões de dependência e cadeia de suprimentos introduzidas por um PR | Alterações de manifest / lockfile / workflow | `.github/workflows/sca-pr-gate.yml` |
| Self-bump SCA do RAPTOR | Endurecimento mecânico de dependências e propostas seguras de upgrade | Agendamento semanal, execução manual | `.github/workflows/sca-self-bump.yml` |
| Corpus de comprometimento SCA | Se comprometimentos conhecidos de dependências ainda disparam o sinal esperado | Agendamento semanal, alterações relevantes de PR | `test/data/sca-e2e/compromise-corpus/`, `.github/workflows/sca-compromise-check.yml` |
| Varredura de mau cabeamento | Detecção de código morto / chamada errada, deriva de documentação de variáveis de ambiente, guardrails de lista de vocabulário, lint de import opcional de dependência | Agendamento diário | `.github/workflows/miswiring-scan.yml`, `.github/scripts/*_baseline.json` |
| Calibração SCA + corpus de estresse | Se a pontuação de risco e a cobertura do parser derivam ao longo do tempo | Trabalhos agendados semanais / mensais | `packages/sca/data/calibration/`, `.github/workflows/refresh-sca-calibration.yml`, `.github/workflows/sca-stress-sweep.yml` |
| Corpus de dataflow | Rastreamento de precisão / recall / categoria de FP para o comportamento do validador | Benchmark executado por desenvolvedor e testes de corpus | `core/dataflow/corpus/`, `core/dataflow/scripts/corpus-metrics` |
| Guarda de doc de controles de CI | Caminhos documentados existem, config do ruff corresponde, README linka para o doc | PRs | `.github/tests/test_ci_controls_docs.py` |
Atualmente não aplicado: `mypy` está instalado em `requirements-dev.txt`, mas não bloqueia nada; a formatação do Ruff não é aplicada; o Semgrep faz parte da superfície de varredura do RAPTOR, mas ainda não temos um workflow dedicado de "varrer o RAPTOR com o RAPTOR" usando Semgrep.
---
## Usando um LLM diferente
O RAPTOR tem duas camadas de modelo separadas, e vale a pena saber como ambas funcionam antes de alterar qualquer coisa.
A **camada de orquestração** é sempre o Claude Code. O CLAUDE.md, as skills e os comandos rodam todos como instruções do Claude Code. Para alterar qual modelo Claude orquestra o RAPTOR, use a flag `--model` do Claude Code ou o comando `/model` dentro de uma sessão.
A **camada de despacho de análise** é o LLM que analisa descobertas individuais de vulnerabilidades. Ela é separada da camada de orquestração e pode ser qualquer provedor suportado. Configure-a em `~/.config/raptor/models.json`:```json
{
"models": [
{
"provider": "anthropic",
"model": "claude-opus-4-6",
"api_key": "sk-ant-...",
"role": "analysis"
},
{
"provider": "openai",
"model": "gpt-5.4",
"api_key": "sk-...",
"role": "analysis"
},
{
"provider": "anthropic",
"model": "claude-sonnet-4-6",
"api_key": "sk-ant-...",
"role": "aggregate"
}
]
}
Ou ignore o arquivo de configuração e defina variáveis de ambiente. O RAPTOR as detectará automaticamente:```bash export ANTHROPIC_API_KEY=sk-ant-... # Anthropic Claude export OPENAI_API_KEY=sk-... # OpenAI export GEMINI_API_KEY=... # Google Gemini export MISTRAL_API_KEY=... # Mistral export OLLAMA_HOST=http://localhost:11434 # Local Ollama
| Função | O que faz |
|------|-------------|
| `analysis` | Valida e analisa cada descoberta (Etapas A-F) |
| `code` | Escreve PoCs de exploração e código de patch |
| `consensus` | Voto de segunda opinião sobre verdadeiros positivos |
| `aggregate` | Opcional. Síntese narrativa escrita por LLM sobre a correlação determinística multi-modelo, gravada em `aggregation.json` e no relatório final `agentic-report.md` |
| `fallback` | Usado se o modelo principal falhar ou atingir limites de taxa |
Se nenhuma função for definida, o primeiro modelo da lista lida com tudo. Para análise
de código-fonte multi-modelo, configure dois ou mais modelos `analysis` — você obterá a
correlação determinística por padrão. A função `aggregate` é opcional e adiciona um
resumo escrito por LLM por cima:```bash
python3 raptor.py agentic --repo /code \
--model claude-opus-4-6 \
--model gpt-5.4 \
--aggregate claude-sonnet-4-6
Orçamento controlado:```bash
python3 raptor.py agentic --repo /code --max-cost-usd 5.00
Ollama funciona para análise, mas produz código de exploit e patch não confiável. Para tarefas de geração de código, use um modelo de fronteira.
### Curto-circuito de nível rápido + o scorecard de modelos
Quando o seu modelo de nível de análise tem um irmão mais barato do mesmo provedor (Anthropic Opus → Haiku, OpenAI 5.x → 4o-mini, Gemini Pro → Flash-Lite, Mistral Large → Small), o RAPTOR o usará como pré-filtro em consumidores que se conectam ao substrato (codeql hoje; SCA e outros conforme forem lançados). O modelo barato só faz curto-circuito em **falsos positivos confiantes**; casos ambíguos e TP confiantes sempre executam a análise completa. A confiança se acumula por célula `(modelo, classe_de_decisão)` — o RAPTOR registra a concordância barato-vs-completo e só faz curto-circuito quando o limite superior de Wilson de 95% na taxa de erro da célula cai para 5% ou menos.
Para inspecionar no que seus modelos são bons, use `/scorecard` (ou diretamente: `libexec/raptor-llm-scorecard list`). O scorecard é global (as lições são transportadas entre projetos) e persiste em `out/llm_scorecard.json`.
---
## Projetos
Sem um projeto, cada execução recebe seu próprio diretório com timestamp em `out/`. Com um projeto, tudo vai para um único lugar e você obtém descobertas mescladas, rastreamento de cobertura e diffs entre execuções.```bash
/project create myapp --target /path/to/code -d "Short description"
/project use myapp
/scan
/understand --map
/validate
/project status # all runs, pass/fail, timestamps
/project findings # merged findings across all runs
/project findings --detailed # per-finding detail
/project coverage --detailed # which files were reviewed
/project diff myapp run1 run2 # compare two runs
/project report # full merged report
/project clean --keep 3 # remove old runs, keep the last 3
/project export myapp /tmp/myapp.zip
/project none # clear active project
O RAPTOR é composto por duas camadas.
A camada de execução em Python (raptor.py, packages/, core/, engine/) cuida do trabalho pesado: executar Semgrep e CodeQL, gerenciar subprocessos, analisar SARIF, deduplicar descobertas, despachar chamadas de API LLM, rastrear custos e escrever arquivos de saída. Ela não toma decisões. Ela executa.
A camada de decisão do Claude Code (.claude/, tiers/, CLAUDE.md) toma as decisões: quais descobertas priorizar, como interpretar os resultados, qual é o cenário de ataque e se a exploração é realista. Implementada como skills, comandos e agentes do Claude Code que carregam progressivamente.```
CLAUDE.md always loaded -- bootstrap, routing, security rules
.claude/commands/ slash commands (/agentic, /scan, /validate, etc.)
.claude/skills/ methodology detail, loaded on demand
tiers/ adversarial thinking, recovery, expert personas
.claude/agents/ specialist sub-agents (offsec, crash analysis, forensics)
A divisão significa que você pode executar a camada Python a partir de um pipeline de CI (`python3 raptor.py scan --repo ...`) e obter saída SARIF estruturada sem o Claude Code, ou executá-la interativamente com o fluxo de trabalho agêntico completo.
---
## Forense OSS
`/oss-forensics` investiga repositórios públicos do GitHub usando evidências de múltiplas fontes: a API do GitHub, o GH Archive (histórico imutável de eventos via BigQuery), o Wayback Machine e o histórico local do git. Ele executa um pipeline estruturado desde a coleta de evidências até a formação de hipóteses e um relatório forense final.
Requer `GOOGLE_APPLICATION_CREDENTIALS` para acesso ao BigQuery. Consulte `.claude/commands/oss-forensics.md` para detalhes.
---
## Personas especialistas
Sete personas especialistas estão disponíveis sob demanda. Carregue uma quando quiser uma perspectiva diferente sobre uma descoberta ou uma técnica específica:```
Exploit Developer (Mark Dowd) Exploit PoC generation
Crash Analyst (Charlie Miller / Halvar Flake) Crash analysis and exploitability assessment
Security Researcher General adversarial code review
Patch Engineer Secure fix generation
Penetration Tester Realistic attack scenario assessment
Fuzzing Strategist Corpus design and triage
Binary Exploitation Specialist ROP, heap, and memory corruption
Diga ao Claude qual usar, por exemplo, "Use o Especialista em Exploração Binária".
Consulte docs/README.md para o índice completo. Guias principais:
| Arquivo | Conteúdo |
|---|---|
docs/commands.md | Referência completa de comandos de barra com todas as flags |
docs/architecture.md | Estrutura do código e árvore de diretórios |
docs/llm.md | Configuração de provedores de LLM, Bedrock, fluxos de trabalho multimodelo |
docs/sandbox.md | Isolamento de processos: perfis, Landlock, namespaces |
docs/audit.md | Revisão sistemática de código: hipóteses, ferramentas, estratégias, portões |
docs/validation.md | Pipeline de validação de explorabilidade (estágios 0--1) |
docs/static-analysis.md | Regras do Semgrep e Coccinelle |
docs/codeql.md | Integração do CodeQL e análise autónoma |
docs/binary-analysis.md | Oráculo binário, /binary, viabilidade de exploração |
docs/fuzzing.md | AFL++ e libFuzzer |
docs/crash-analysis.md | Análise autónoma de causa raiz de falhas |
docs/sca.md | Análise de composição de software |
docs/frida.md | Instrumentação dinâmica |
docs/security.md | Modelo de segurança do próprio RAPTOR |
docs/ci-controls.md | Controlos de CI, fluxos de trabalho e evidências de benchmark |
docs/threat-model.md | Funcionalidade de modelo de ameaças por projeto |
docs/python-cli.md | Referência da CLI Python para scripting e CI |
docs/concepts.md | Conceitos principais: modelo de duas camadas, ciclo de vida de descobertas, escolha de um comando |
docs/agentic.md | Fluxo de trabalho autónomo: pipeline /agentic, flags de enriquecimento, multimodelo |
docs/sage.md |
O RAPTOR é open source. Bons pontos de partida se quiser contribuir:
@RequestParam, parâmetros tipados do FastAPI) — o semgrep não consegue corresponder a estas fontes, pelo que abordagens alternativas são bem-vindasOs lançamentos são etiquetados como vX.Y.Z e construídos automaticamente pela CI. Os prefixos de commits determinam o que entra no changelog: feat: para novas funcionalidades, fix: para correções de bugs, security: para alterações de segurança, docs: para documentação. Qualquer coisa sem prefixo fica em "Outras alterações". Não é necessária uma convenção rigorosa, mas ajuda.
Envie pull requests. Fale connosco no canal #raptor no Slack do Prompt||GTFO: https://join.slack.com/t/promptgtfo/shared_invite/zt-3v2b4sll3-SfyzFRw2lykx_XQX7F3uNQ
MIT -- Copyright (c) 2025-2026 Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake), Michael Bargury, John Cartwright.
Consulte o LICENSE para o texto completo. Reveja as licenças de todas as dependências antes de uso comercial — o CodeQL, em particular, não o permite.
Problemas: https://github.com/gadievron/raptor/issues
| Memória persistente SAGE: configuração, chave HMAC, CPU/GPU, casos de uso |
docs/dependencies.md | Ferramentas externas, versões e licenças |
tiers/personas/README.md | Referência de personas especialistas |