╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║             ██████╗  █████╗ ██████╗ ████████╗ ██████╗ ██████╗             ║
║             ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗            ║
║             ██████╔╝███████║██████╔╝   ██║   ██║   ██║██████╔╝            ║
║             ██╔══██╗██╔══██║██╔═══╝    ██║   ██║   ██║██╔══██╗            ║
║             ██║  ██║██║  ██║██║        ██║   ╚██████╔╝██║  ██║            ║
║             ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝    ╚═════╝ ╚═╝  ╚═╝            ║
║                                                                           ║
║             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.....⠀⠀⠀⠀⠀

O lançador `raptor` é a forma recomendada de iniciar uma sessão, e funciona a partir de qualquer diretório -- resolve a instalação do RAPTOR, memoriza o diretório a partir do qual foi lançado (para que comandos como `/scan` o usem por omissão), executa as verificações de confiança e de projeto prévias, carrega o plugin de rastreio de cobertura e sanitiza o ambiente antes de passar o controlo ao Claude Code. Também aceita um caminho de destino opcional e flags como `--project`, `--continue` e `--model` -- consulte `raptor --help`.

Executar simplesmente `claude` a partir de dentro do diretório do repositório também funciona -- o Claude Code deteta a configuração do RAPTOR a partir do checkout -- mas perde tudo o que o lançador faz acima: sem verificações prévias, sem rastreio de cobertura, e os comandos que usam por omissão "o diretório a partir do qual executou isto" não o conseguem ver.

**Importante:** O RAPTOR carrega a sua configuração a partir do diretório do repositório. Se executar `claude` a partir de qualquer outro diretório, obtém o Claude Code simples, não o RAPTOR. O lançador `raptor` evita completamente este modo de falha.

### Opção 2: Executar num contentor (recomendado)

A utilização de contentores é uma prática de segurança comum para restringir o acesso dos agentes a áreas do seu sistema de ficheiros às quais não quer que acedam, bem como para limitar o raio de impacto de qualquer código malicioso que possa ser executado (por exemplo, através de um ataque à cadeia de fornecimento). A imagem é grande (cerca de 6 GB). Parte do devcontainer Microsoft Python 3.12 e adiciona ferramentas de análise estática, fuzzing e automação de navegador.

Pode descarregar uma imagem pré-construída:```bash
docker pull danielcuthbert/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

Adicione `--privileged` se você precisar do depurador determinístico `rr`.

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

De qualquer forma, depois de entrar no container, execute `raptor` para começar.

---

## 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, deduplicate e, em seguida, envia cada descoberta pelas etapas de validação (A-F). Em uma base de código de tamanho médio com ~50 descobertas, espere de 10 a 30 minutos e de $2 a $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 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 por esses 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 usando namespaces do 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 arquivos de repositórios escaneados 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 autônomo completo: scan, validate, exploit, patch | 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 vulnerabilidade | Estável |
| `/binary` | Investigação de binário em caixa-preta, evidências em tempo de execução, consultas de grafo e handoff | Beta |
| `/ghidra` | Ponte de 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 em prosa de formato livre por função (notas de revisão do operador) | Estável |
| `/validate` | Pipeline de validação de explorabilidade em múltiplos estágios (Estágios 0-F) | Estável |
| `/diagram` | Mapas visuais Mermaid a partir das 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 reescanear | Estável |
| `/openant` | Scan de código-fonte com LLM do OpenAnt: análise de AST mais raciocínio de LLM por função | Beta |
| `/sca` | Análise de composição de software: dependências, avisos, sinais de cadeia de suprimentos, SBOMs e correções | Beta |
| `/cve-diff` | Descobrir e comparar o commit de correção de uma CVE em OSV, NVD, GitHub e GitLab | Beta |
| `/cve-env` | Construir e verificar um ambiente Docker executando a aplicação afetada por uma CVE em sua versão pré-patch | Experimental |
| `/exploit` | Gerar código de exploit de prova de conceito | Beta |
| `/patch` | Gerar patches seguros 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 de 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 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 de formato livre para qualquer modelo de LLM configurado | Estável |
| `/scorecard` | Inspecionar a confiabilidade por modelo em classes de decisão | Estável |
| `/frida` | Instrumentação dinâmica via Frida | Alpha |
| `/web` | Escaneamento de aplicações web: crawl, integração ffuf/nuclei, injeção verificada por oráculo, callbacks de SSRF cego | 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

`/understand` constrói um mapa de contexto de pontos de entrada, limites de confiança e sinks antes que qualquer linha de análise seja executada. `/agentic` então executa Semgrep e CodeQL, deduplica os achados e despacha cada um 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`. Modelos de ameaça existentes do projeto são preservados a menos que você passe `--threat-model-refresh`; mapas de fallback obsoletos são recusados a menos que você passe explicitamente `--threat-model-use-stale`. Ele também transforma 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: os achados ainda precisam de evidência de código ou confirmação respaldada por oráculo. Veja `docs/threat-model.md`.

- Estágio A: o padrão é realmente uma vulnerabilidade, ou a ferramenta está fazendo correspondência de padrões com ruído?
- 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 de fora?
- Estágio D: decisão final -- isto é código de teste, precisa de pré-condições irrealistas, o modelo está se esquivando?
- Estágio E: viabilidade de exploit binário (quando um artefato compilado está disponível)
- Estágio F: auto-revisão -- algum estágio anterior se esquivou ou se contradisse?

Achados que passam na validação recebem PoCs de exploit e patches gerados. Uma análise cruzada de achados é 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á tem achados de uma varredura anterior.

Para um artefato compilado, `/binary <path>` agora executa uma investigação
orientada a evidências em vez de despejar uma pilha de artefatos brutos de engenharia reversa
no operador. Por baixo, ele ainda constrói o manifesto vinculado a SHA-256,
o livro-razão de evidências, o mapa de contexto, a checklist 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; pseudocódigo de alto valor é
persistido em vez de desaparecer dentro da execução. Exportações de DLL PE, dispatchers de driver Windows
e handlers ioctl de módulos de kernel Linux também são tratados como
seus próprios candidatos de ingresso, com a arquitetura PE lida 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 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 crash de fuzzing,
verificações explícitas de 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 limitados de ingresso-para-parser, para que um callback de aplicativo possa ser restringido à
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 acompanhamento dinâmico explícito:
ele executa o trace estreito do parser Frida, então atualiza o mesmo mapa de contexto,
handoff, grafo e relatório de investigação no local. `/binary investigate --active` mapeia primeiro e só lança uma
campanha real de fuzzing quando existe um limite concreto de harness; alvos de aplicativo, DLL e driver
recebem um passo de harness ou snapshot em vez disso. `/binary harness` escreve uma
especificação de harness respaldada por 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 blefa o caminho de "`memcpy` existe" para "isto é
explorável": imports, seletores e arestas de chamada permanecem 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 imagem de contêiner/base, e então os normaliza em uma única visão 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 exploit, verificações de higiene, heurísticas de cadeia de suprimentos, achados de política de licença e revisão/triagem opcional por LLM. Ela emite achados nativos do RAPTOR mais SBOM e saída amigável para CI:

- `findings.json` - achados canônicos 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 preenchido, o scanner resolve os IDs de pacote para ficheiros locais e não ocorre qualquer chamada de rede. Sem a cache, o RAPTOR tentará obter os pacotes de registo de semgrep.dev no momento da análise; se estiver offline, descarta os pacotes não armazenados em cache de forma graciosa e executa apenas com regras personalizadas.

O CodeQL necessita de acesso à rede apenas durante a configuração inicial para descarregar a CLI e os pacotes de consulta. Uma vez instalado, executa offline.

---

## Regras personalizadas

O RAPTOR inclui mais de 200 regras personalizadas de análise estática, testadas adversarialmente para eliminar falsos positivos:

- **Semgrep (~150 regras)** — regras de rastreio de taint e de 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/header, injeção de eval, ReDoS, prototype pollution, má configuração de JWT, criptografia fraca, TLS inseguro e segredos codificados.
- **Coccinelle (68 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 stack, memória mmap'd, use-after-close), bugs de inteiros (overflow, extensão de sinal, double sizeof), fugas de recursos (incompatibilidade popen/fclose, duplo close de fdopendir), tratamento de buffers (strncpy sem NUL, incompatibilidade de tamanho em copy_user, off-by-one em malloc/strlen), segurança de signal handlers, uso indevido de API (domínio de flags fcntl, SIGKILL/SIGSTOP, duplo 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 mais.
- **CodeQL (8 consultas)** — rastreio de taint interprocedimental 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, SSRF no Spring).

Navegue pelas regras diretamente: `engine/semgrep/rules/`, `engine/coccinelle/rules/`, `engine/codeql/queries/`. Estas complementam os pacotes de registo Semgrep que o RAPTOR obtém (`p/security-audit`, `p/owasp-top-ten`, `p/secrets` sempre; pacotes por grupo de políticas como `p/command-injection`, `p/jwt`, `p/xss` adicionalmente) — a sobreposição é mínima.

---

## Como o RAPTOR se verifica a si próprio

O RAPTOR faz dogfooding de uma boa parte das suas próprias ferramentas de segurança, mas vale a pena ser honesto sobre o que realmente bloqueia um PR e o que apenas corre em segundo plano para nos manter honestos. Parte disto é um gate rígido, parte é uma verificação agendada, e parte é apenas um benchmark que mantemos por perto para conseguirmos perceber quando piorámos algo. A decomposição mais completa, incluindo os parâmetros reais e como reproduzir as verificações, está em `docs/ci-controls.md`.

| Controlo | O que verifica | Gatilho | Config / evidência |
|---|---|---|---|
| Ruff | Linting de correção em Python (`F401`, `F811`, `F821`, `F841`) | Gate de diff em PR, mais auditoria semanal de toda a árvore | `pyproject.toml`, `.github/workflows/lint.yml` |
| Pytest | Fronteiras rápidas de testes unitários/integração, tiers específicos por subsistema (via dispatch do grafo de imports), auditoria de prompt-envelope | PRs, pushes para `main`, merge queue, suite completa agendada | `pytest.ini`, `.github/workflows/tests.yml`, `.github/workflows/nightly.yml` |
| CodeQL Advanced | Análise de código de Python, C/C++ e GitHub Actions com estreitamento de âmbito pelo grafo de imports | PRs, pushes para `main`, merge queue, agendamento semanal | `.github/workflows/codeql.yml`, `.github/codeql/codeql-config.yml` |
| Endurecimento de workflows | Actions de terceiros fixadas por SHA, permissões de menor privilégio, linting de metadados de comandos | Cada alteração de workflow e cada execução de lint | `.github/workflows/`, `.github/scripts/check_command_metadata.py` |
| Lint de etiquetas do corpus | Validação do esquema de etiquetas do corpus de auditoria e verificação de pins upstream | PRs (etiquetas alteradas), varredura completa semanal | `.github/workflows/corpus-labels.yml` |
| Gate de PR do RAPTOR SCA | Regressões de dependências e supply-chain introduzidas por um PR | Alterações a manifestos / lockfiles / workflows | `.github/workflows/sca-pr-gate.yml` |
| Auto-bump do RAPTOR SCA | Endurecimento mecânico de dependências e propostas de atualização seguras | Agendamento semanal, execução manual | `.github/workflows/sca-self-bump.yml` |
| Corpus de compromisso SCA | Se compromissos conhecidos de dependências ainda disparam o sinal esperado | Agendamento semanal, alterações relevantes em PRs | `test/data/sca-e2e/compromise-corpus/`, `.github/workflows/sca-compromise-check.yml` |
| Detetores de invariantes do repositório | Deteção de código morto / chamadas erradas, desvio de documentação de variáveis de ambiente, guardrails de listas de vocabulário, formas de bytes de JSON canónico, lint de imports de dependências opcionais | Gate de PR (job `repo-invariants` em `lint.yml`), mais varredura diária | `.github/workflows/lint.yml`, `.github/workflows/miswiring-scan.yml`, `.github/scripts/*_baseline.json` |
| Calibração SCA + corpus de stress | Se a pontuação de risco e a cobertura do parser sofrem desvio ao longo do tempo | Jobs agendados semanais / mensais | `packages/sca/data/calibration/`, `.github/workflows/refresh-sca-calibration.yml`, `.github/workflows/sca-stress-sweep.yml` |
| Corpus de dataflow | Rastreio de precisão / recall / categoria de FP para o comportamento do validador | Benchmark executado por developers e testes de corpus | `core/dataflow/corpus/`, `core/dataflow/scripts/corpus-metrics` |
| Guarda do documento de controlos de CI | Os caminhos documentados existem, a configuração do ruff corresponde, o README liga ao documento | PRs | `.github/tests/test_ci_controls_docs.py` |

Atualmente não aplicado: `mypy` está fixado em `pyproject.toml` mas não bloqueia nada; a formatação do Ruff não é aplicada; o Semgrep faz parte da superfície de scanner do RAPTOR, mas ainda não temos um workflow Semgrep dedicado a "scan RAPTOR with RAPTOR".

---

## Usar um LLM diferente

O RAPTOR tem duas camadas de modelo separadas, e vale a pena saber como ambas funcionam antes de alterar algo.

A **camada de orquestração** é o Claude Code -- mas apenas para a shell interativa `raptor` (esta camada conversacional, de slash-commands). O CLAUDE.md, as skills e os comandos correm todos como instruções do Claude Code aí. Para alterar qual modelo Claude orquestra essa camada, use a flag `--model` do Claude Code ou o comando `/model` dentro de uma sessão. Se não quiser esta camada de todo, veja [Running fully standalone](#running-fully-standalone-no-claude-code) abaixo.

A **camada de dispatch de análise** é o LLM que analisa descobertas individuais de vulnerabilidades. Esta é separada da camada de orquestração e pode ser qualquer fornecedor 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"
    }
  ]
}

Papéis de modelo permitem que você atribua modelos diferentes a tarefas diferentes:

| Papel | O que faz |
|------|-------------|
| `analysis` | Valida e analisa cada descoberta (Estágios A-F) |
| `code` | Escreve PoCs de exploit 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 `agentic-report.md` final |
| `fallback` | Usado se o modelo primário falhar ou atingir limites de taxa |

Se nenhum papel estiver 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

O Ollama funciona bem para análise; a confiabilidade para geração de código de exploit/patch acompanha a escala e a quantização do modelo, em vez de ser uma propriedade fixa dos modelos locais — consulte [Quality Tradeoffs](https://github.com/gadievron/raptor/blob/main/llm.md#quality-tradeoffs) no guia do LLM, e verifique `/scorecard` para saber o que o seu modelo específico está realmente medindo.

### Executando totalmente autônomo (sem Claude Code)

`bin/raptor` -- o shell interativo com o banner e comandos de barra, ou seja, esta camada conversacional -- executa diretamente na CLI do Claude Code e sempre precisa de seu próprio login. A mecânica real por baixo dele não precisa: `python3 raptor.py <mode>` é uma CLI Python simples, sem nenhuma dependência do Claude Code.```bash
# No `claude` process involved at any point
python3 raptor.py doctor                        # status check -- explicitly "no claude needed"
python3 raptor.py agentic --repo /path/to/code   # scan -> dedup -> analysis
python3 raptor.py scan --repo /path/to/code

Aponte `models.json` / `OLLAMA_HOST` para uma instância local do Ollama (veja acima) e todo esse caminho nunca conversa com a Anthropic -- útil para máquinas isoladas ou hardware apenas local. Você perde a camada conversacional de slash-commands (este chat); o pipeline de scan/análise/exploit em si não é afetado.

### Curto-circuito do tier rápido + o scorecard de modelos

Quando seu modelo de tier 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 os follow-ups chegam). 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 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 sobre 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 se acumulam 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 achados mesclados, 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 separaçã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 de OSS

O `/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), a Wayback Machine e o histórico local do git. Ele executa um pipeline estruturado desde a coleta de evidências, passando pela formulação de hipóteses, até um relatório forense final.

Requer `GOOGLE_APPLICATION_CREDENTIALS` para acesso ao BigQuery. Consulte `.claude/commands/oss-forensics.md` para obter detalhes.

---

## Personas especialistas

Oito personas especialistas estão disponíveis sob demanda. Carregue uma quando quiser uma perspectiva diferente sobre um achado 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
Web Researcher (James Kettle)                  Web endpoint research (smuggling, cache poisoning, SSRF)
Fuzzing Strategist                             Corpus design and triage
Binary Exploitation Specialist                 ROP, heap, and memory corruption

Manter `/web`, Z3, SAGE e SDKs de provedores de nuvem como extras opcionais evita
tornar a instalação padrão do RAPTOR mais pesada e frágil do que o necessário.