╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║             ██████╗  █████╗ ██████╗ ████████╗ ██████╗ ██████╗             ║
║             ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗            ║
║             ██████╔╝███████║██████╔╝   ██║   ██║   ██║██████╔╝            ║
║             ██╔══██╗██╔══██║██╔═══╝    ██║   ██║   ██║██╔══██╗            ║
║             ██║  ██║██║  ██║██║        ██║   ╚██████╔╝██║  ██║            ║
║             ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝    ╚═════╝ ╚═╝  ╚═╝            ║
║                                                                           ║
║             Autonomous Offensive/Defensive Research Framework             ║
║             Based on Claude Code (v3.0.0)                                 ║
║                                                                           ║
║             Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake)    ║
║             Michael Bargury, John Cartwright                              ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣠⣤⣤⣀⣀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣾⣿⣿⠿⠿⠟
⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⣀⣀⣀⣤⣴⣶⣶⣶⣤⣿⡿⠁⠀⠀⠀
⣀⠤⠴⠒⠒⠛⠛⠛⠛⠛⠿⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⣿⣿⣿⡟⠻⢿⡀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⢿⣿⠟⠀⠸⣊⡽⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⡇⣿⡁⠀⠀⠀⠉⠁⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠻⠿⣿⣧⠀ Get them bugs.....⠀⠀⠀⠀⠀

Se adicionar `bin/` ao seu PATH (ou criar um symlink de `bin/raptor` em algum lugar do PATH), você pode executar `raptor` de qualquer diretório — o launcher resolve a instalação do RAPTOR e configura o diretório de trabalho automaticamente.

**Importante:** o RAPTOR carrega sua configuração a partir do diretório do repositório. Se você executar `claude` de um diretório diferente, terá o Claude Code normal, não o RAPTOR. Ou faça `cd` para o repositório primeiro, ou use o launcher `raptor`.

### Opção 2: Devcontainer (recomendado)

Tudo pré-instalado. Abra no VS Code com **Dev Containers: Open Folder in Container**, ou puxe a imagem pré-construída:```bash
docker pull danielcuthbert/raptor:latest
docker run --privileged -it -v "$(pwd):/workspaces/raptor" danielcuthbert/raptor:latest

A flag `--privileged` é necessária para o depurador determinístico `rr`. 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.

Depois de entrar, basta dizer "hi" para começar, ou ir direto para um comando.

---

## O que esperar na primeira execução

A coisa mais simples que você pode fazer:```
/scan /path/to/code

Isso executa o pipeline completo: scan, deduplicação e envio de cada achado pelas etapas de validação (A-F). Em uma base de código de médio porte com ~50 achados, espere de 10 a 30 minutos e $2-8 em custos de LLM da camada de análise (dependendo do modelo). O limite de custo padrão é de $10 por execução; ajuste com `--max-cost-usd`.

**Nota sobre custos:** A camada de orquestração do Claude Code usa sua assinatura do Claude. A camada de despacho de análise faz chamadas separadas à API de LLM, 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 do Linux, Landlock e seccomp. O sandbox bloqueia o acesso à rede, restringe a visibilidade do sistema de arquivos e limita o consumo de recursos. Consulte `docs/sandbox.md` para ver o modelo de ameaças completo e a configuração.

Variáveis de ambiente que possam 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 analisados nunca são interpolados em strings de shell — todas as chamadas de subprocesso usam argumentos baseados em listas.

---

## O que o RAPTOR pode fazer

| Comando | O que faz | Status |
|---------|-------------|--------|
| `/agentic` | Fluxo de trabalho totalmente autônomo: scan, validação, exploração e correção | 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 de binários caixa-preta, evidências de runtime, consultas em grafo e handoff | Beta |
| `/validate` | Pipeline de validação de explorabilidade em múltiplas etapas (Etapas 0-F) | Estável |
| `/codeql` | Análise profunda somente com CodeQL e pré-triagem de fluxo de dados com SMT | Estável |
| `/sca` | Análise de composição de software: dependências, advisories, sinais de supply chain, SBOMs e correções | Beta |
| `/exploit` | Gerar código de exploit de prova de conceito | Beta |
| `/patch` | Gerar correções seguras para vulnerabilidades confirmadas | Beta |
| `/fuzz` | Fuzzing de binários 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 do GitHub | Estável |
| `/project` | Espaços de trabalho nomeados para organizar execuções e acompanhar achados ao longo do tempo | 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 |
| `/frida` | Instrumentação dinâmica via Frida | Alpha |
| `/web` | Varredura de aplicações web | Alpha/stub |

---

## 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

`/understand` constrói um mapa de contexto de pontos de entrada, limites de confiança e sumidouros antes que qualquer varredura aconteça. `/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 fornece uma versão compacta para `/understand`, análise autônoma e `/validate`. Modelos de ameaça existentes do projeto são preservados a menos que você passe `--threat-model-refresh`; mapas de fallback desatualizados são recusados a menos que você passe explicitamente `--threat-model-use-stale`. Ele também transforma fluxos mapeados não verificados em SARIF candidato, para que falhas do scanner não interrompam a execução. É contexto de propriedade do operador, não prova mágica: as descobertas ainda precisam de evidência no código ou confirmação apoiada por oráculo. Veja `docs/threat-model.md`.

- Estágio A: o padrão é realmente uma vulnerabilidade ou é ruído de correspondência de padrões da ferramenta?
- Estágio B: o que um atacante precisa para alcançá-lo e o que fica no caminho?
- Estágio C: o caminho de código realmente existe? pode ser alcançado a partir de fora?
- Estágio D: decisão final -- isto é código de teste, precisa de pré-condições irrealistas, o modelo está sendo evasivo?
- Estágio E: viabilidade de exploração binária (quando um artefato compilado está disponível)
- Estágio F: auto-revisão -- algum estágio anterior foi evasivo ou se contradisse?

Descobertas que passam na validação recebem PoCs de exploração e patches gerados. Uma análise cruzada de descobertas é executada no final para encontrar causas-raiz compartilhadas e cadeias de ataque.

`/validate` executa esse mesmo pipeline como uma etapa autônoma se você já tiver descobertas de uma varredura anterior.

Para um artefato compilado, `/binary <path>` agora executa uma investigação orientada por evidências
em vez de despejar uma pilha de artefatos brutos de engenharia reversa sobre o operador.
Por baixo, ele ainda constrói o manifesto vinculado a SHA-256, o registro de evidências,
o mapa de contexto, a lista de verificação e o grafo SQLite a partir de metadados de arquivo,
imports e xrefs do radare2. Aplicativos Mach-O também recebem inventário de slices,
metadados de bundle e seletores de classe Objective-C / Swift; o pseudocódigo de alto valor é
persistido em vez de desaparecer durante a execução. Exportações de DLL PE, dispatchers de drivers
do Windows e handlers de ioctl de módulos de kernel Linux também são tratados como candidatos
de ingresso próprios, 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, prioriza o ingresso externo antes de pistas
genéricas de sink, descobre binários auxiliares/irmãos declarados e escreve um relatório compacto
dividido em fatos, 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 então
adicionar evidências mais fortes posteriormente. O RAPTOR também mantém o grafo de chamadas interno
necessário para recuperar candidatos delimitados de ingresso-para-parser, de modo que um callback
de aplicativo possa ser reduzido à função interna que realmente chama `XML_Parse`, `d2i_X509`,
`jpeg_read_header` ou outra superfície real de parser, sem fingir que isso é prova de taint.
`/binary trace-parser <run-dir>` é o complemento dinâmico explícito: ele executa o rastreamento estreito
do parser via Frida e depois atualiza no mesmo local o mapa de contexto, o handoff, o grafo
e o relatório de investigação. `/binary investigate --active` mapeia primeiro e só lança uma campanha real de fuzzing
quando existe um limite concreto de harness; alvos de aplicativos, DLLs e drivers recebem uma etapa
de harness ou snapshot em vez disso. `/binary harness` escreve uma especificação de harness apoiada
em evidências para o ingresso escolhido e só emite código-fonte candidato quando o contrato de ABI ou
IOCTL é explícito.
Ele não tenta passar de “`memcpy` existe” para “isso é explorável” na base do blefe:
imports, seletores e arestas de chamada permanecem como candidatos até que algo mecânico
prove mais. Veja `docs/binary-analysis.md`.

---

## Análise de Composição de Software

`/sca` analisa o lado de dependências e cadeia de suprimentos de um projeto. Não é apenas uma consulta de CVE em arquivo de requisitos: o RAPTOR descobre manifests, lockfiles, comandos de instalação inline, dependências de workflow e fontes de pacotes de contêiner/imagem base, e então os normaliza em uma visão única de dependências.

A varredura enriquece as dependências com avisos do 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 suprimentos, descobertas de política de licença e revisão/triagem opcional por LLM. Ela emite descobertas nativas do RAPTOR além de SBOM e saída compatível com 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

Uma vez populado, o scanner resolve os IDs de pack para arquivos locais e nenhuma chamada de rede é feita. Sem o cache, o RAPTOR tentará buscar os packs de registro em semgrep.dev no momento da varredura; se estiver offline, ele descarta os packs não armazenados em cache sem problemas e executa apenas com regras personalizadas.

O CodeQL precisa de acesso à rede apenas durante a configuração inicial para baixar a CLI e os query packs. Depois de instalado, ele funciona offline.

---

## Regras personalizadas

O RAPTOR inclui 185 regras personalizadas de análise estática, testadas de forma adversarial para eliminar falsos positivos:

- **Semgrep (123 regras)** — regras de taint-tracking e de padrão para Python, Go, Java e JS/TS. Abrange 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 hardcoded.
- **Coccinelle (54 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 na pilha, memória mapeada com mmap, use-after-close), bugs de inteiros (overflow, extensão de sinal, double sizeof), vazamentos de recursos (incompatibilidade popen/fclose, double close em fdopendir), manipulação de buffers (strncpy sem NUL, incompatibilidade de tamanho em copy_user, off-by-one em malloc/strlen), segurança de manipuladores de sinais, uso incorreto de API (domínio de flags fcntl, SIGKILL/SIGSTOP, double byte-swap, buffer estático de inet_ntoa), eliminação de dead store pelo compilador, confusão IS_ERR/PTR_ERR no kernel, injeção de format string, corridas TOCTOU e muito mais.
- **CodeQL (8 consultas)** — rastreamento de taint interprocedural para C++ (injeção de format string, truncamento de inteiros, use-after-move, invalidação de iteradores) e Java (XXE, desserialização insegura, injeção de log, Spring SSRF).

Navegue pelas regras diretamente: `engine/semgrep/rules/`, `engine/coccinelle/rules/`, `engine/codeql/queries/`. Elas complementam os packs de registro (`p/security-audit`, `p/owasp-top-ten`, `p/0xdea`, `p/trailofbits`), que fornecem ~950 regras adicionais — a sobreposição é mínima.

---

## Usando um LLM diferente

O RAPTOR possui duas camadas de modelo separadas, e vale a pena entender como ambas funcionam antes de alterar qualquer coisa.

A **camada de orquestração** é sempre o Claude Code. O CLAUDE.md, as habilidades e os comandos são executados 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 compatível. 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"
    }
  ]
}

Os papéis de modelo permitem atribuir diferentes modelos a diferentes tarefas:

| Papel | O que faz |
|------|-------------|
| `analysis` | Valida e analisa cada achado (Estágios A-F) |
| `code` | Escreve PoCs de exploração e código de correção |
| `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 nenhum papel for definido, o primeiro modelo da lista cuida de 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. O papel `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

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 camada rápida + o scorecard de modelos

Quando seu modelo de camada 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 em seguida). O modelo barato só faz curto-circuito em **falsos positivos confiantes**; casos ambíguos e TPs confiantes sempre executam a análise completa. A confiança se acumula por célula `(model, decision_class)` — o RAPTOR registra a concordância entre barato e completo e só faz curto-circuito quando o limite superior de 95% de Wilson para a 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 valem para todos os projetos) e persiste em `out/llm_scorecard.json`.

---

## Projetos

Sem um projeto, cada execução recebe seu próprio diretório com carimbo de data/hora em `out/`. Com um projeto, tudo vai para um só 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

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