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

El lanzador `raptor` es la forma recomendada de iniciar una sesión, y funciona desde cualquier directorio -- resuelve la instalación de RAPTOR, recuerda el directorio desde el que lo lanzaste (por lo que comandos como `/scan` lo usan por defecto), ejecuta las comprobaciones previas de confianza y de proyecto, carga el plugin de seguimiento de cobertura y sanitiza el entorno antes de ceder el control a Claude Code. También acepta una ruta de destino opcional y flags como `--project`, `--continue` y `--model` -- consulta `raptor --help`.

Ejecutar `claude` directamente desde dentro del directorio del repositorio también funciona -- Claude Code toma la configuración de RAPTOR desde el checkout -- pero te saltas todo lo que hace el lanzador mencionado arriba: sin comprobaciones previas, sin seguimiento de cobertura, y los comandos que usan por defecto "el directorio desde el que ejecutaste esto" no pueden verlo.

**Importante:** RAPTOR carga su configuración desde el directorio del repositorio. Si ejecutas `claude` desde cualquier otro directorio, obtienes Claude Code normal, no RAPTOR. El lanzador `raptor` evita por completo este modo de fallo.

### Opción 2: Ejecutar en un contenedor (recomendado)

Usar contenedores es una práctica de seguridad común para restringir a los agentes el acceso a áreas de tu sistema de archivos a las que no quieres que accedan, así como para limitar el radio de impacto de cualquier código malicioso que pueda ejecutarse (por ejemplo, mediante un ataque de cadena de suministro). La imagen es grande (alrededor de 6 GB). Parte del devcontainer de Microsoft Python 3.12 y añade herramientas de análisis estático, fuzzing y automatización de navegador.

Puedes descargar una imagen preconstruida:```bash
docker pull danielcuthbert/raptor:latest

La imagen espera que el framework RAPTOR (este repositorio) esté montado en `/workspaces/raptor` al iniciarse. Opcionalmente, puedes montar una carpeta de destino para el análisis local.

Para iniciar el contenedor:```bash
docker run -it \
  -v "$(pwd):/workspaces/raptor" \
  raptor:latest

Añade `--privileged` si necesitas el depurador determinista `rr`.

También se admiten los devcontainers de VS Code. Para montar una carpeta de destino, añádela a la sección `mounts` de `.devcontainer/devcontainer.json`:```jsonc
"mounts": [
  // ...existing entries...
  "source=/path/to/target-folder,target=/workspaces/target,type=bind,consistency=cached"
]

De cualquier manera, una vez que estés dentro del contenedor, ejecuta `raptor` para comenzar.

---

## Qué esperar en una primera ejecución

Lo más sencillo que puedes hacer:```
/scan /path/to/code

Esto ejecuta el pipeline completo: escanear, deduplicar y luego enviar cada hallazgo a través de las etapas de validación (A-F). En un código base de tamaño medio con ~50 hallazgos, se esperan de 10 a 30 minutos y de $2 a $8 en costos de LLM de la capa de análisis (según el modelo). El límite de costo predeterminado es de $10 por ejecución; ajústalo con `--max-cost-usd`.

**Nota sobre costos:** La capa de orquestación de Claude Code utiliza tu suscripción de Claude. La capa de despacho de análisis realiza llamadas separadas a la API de LLM que se facturan por token. Si solo usas Claude Code como modelo de análisis (el predeterminado), no hay costo adicional más allá de tu suscripción. Si configuras modelos externos (OpenAI, Gemini, etc.), esas llamadas a la API se facturan a esos proveedores.

---

## Modelo de seguridad

RAPTOR ejecuta código generado por LLM y analiza repositorios no confiables. Los subprocesos que manejan contenido no confiable se ejecutan en un sandbox usando namespaces de Linux, Landlock y seccomp. El sandbox bloquea el acceso a la red, restringe la visibilidad del sistema de archivos y limita el consumo de recursos. Consulta `docs/sandbox.md` para el modelo de amenazas completo y la configuración.

Las variables de entorno que podrían inyectar código en la cadena de lanzamiento se eliminan al inicio (`core/security/_dangerous_env_strip.sh`). Las rutas de archivos de los repositorios escaneados nunca se interpolan en cadenas de shell — todas las llamadas a subprocesos usan argumentos basados en listas.

---

## Qué puede hacer RAPTOR

| Comando | Qué hace | Estado |
|---------|-------------|--------|
| `/agentic` | Flujo de trabajo autónomo completo: escanear, validar, explotar, parchear | Estable |
| `/scan` | Análisis estático con Semgrep y CodeQL | Estable |
| `/understand` | Mapear la superficie de ataque, rastrear flujos de datos, cazar variantes de vulnerabilidades | Estable |
| `/binary` | Investigación de binarios de caja negra, evidencia en tiempo de ejecución, consultas de grafos y transferencia | Beta |
| `/ghidra` | Puente de RE de Ghidra: adjuntar/importar proyectos `.gpr`, diff entre versiones, exportación de hallazgos | Beta |
| `/audit` | Revisión de código sistemática basada en hipótesis y fundamentada en herramientas | Beta |
| `/review` | Consultar el estado de auditoría: hallazgos, brechas, cobertura, notas del operador | Estable |
| `/annotate` | Adjuntar anotaciones en prosa de formato libre por función (notas de revisión del operador) | Estable |
| `/validate` | Pipeline de validación de explotabilidad de múltiples etapas (Etapas 0-F) | Estable |
| `/diagram` | Mapas visuales de Mermaid a partir de las salidas JSON de `/understand` y `/validate` | Beta |
| `/codeql` | Análisis profundo solo con CodeQL con pre-filtrado de flujo de datos SMT | Estable |
| `/analyze` | Analizar hallazgos SARIF existentes con LLM, sin volver a escanear | Estable |
| `/openant` | Escaneo de código fuente con LLM de OpenAnt: análisis de AST más razonamiento LLM por función | Beta |
| `/sca` | Análisis de composición de software: dependencias, avisos, señales de cadena de suministro, SBOMs y correcciones | Beta |
| `/cve-diff` | Descubrir y comparar el commit de corrección de un CVE en OSV, NVD, GitHub y GitLab | Beta |
| `/cve-env` | Construir y verificar un entorno Docker que ejecute la aplicación afectada por un CVE en su versión previa al parche | Experimental |
| `/exploit` | Generar código de exploit de prueba de concepto | Beta |
| `/patch` | Generar parches seguros para vulnerabilidades confirmadas | Beta |
| `/fuzz` | Fuzzing de binarios con AFL++ y análisis de fallos | Estable |
| `/crash-analysis` | Análisis autónomo de causa raíz para fallos de C/C++ | Estable |
| `/oss-forensics` | Investigación forense respaldada por evidencia para repositorios de GitHub | Estable |
| `/project` | Espacios de trabajo con nombre para organizar ejecuciones y rastrear hallazgos a lo largo del tiempo | Estable |
| `/describe` | Describir un objetivo: mezcla de lenguajes, sistema de compilación, brechas de herramientas, estimación de costos (solo lectura) | Estable |
| `/threat-model` | Crear, inspeccionar y mantener modelos de amenazas por proyecto | Estable |
| `/sage` | Capa de memoria persistente (almacenar, recordar, enlazar, corroborar) | Estable |
| `/ask` | Enviar un prompt de formato libre a cualquier modelo LLM configurado | Estable |
| `/scorecard` | Inspeccionar la fiabilidad por modelo en las clases de decisión | Estable |
| `/frida` | Instrumentación dinámica mediante Frida | Alpha |
| `/web` | Escaneo de aplicaciones web: rastreo, integración con ffuf/nuclei, inyección verificada por oráculo, callbacks de SSRF ciego | Beta |

---

## Cómo funciona el pipeline

Comienza creando un proyecto para que todas tus ejecuciones queden en un solo 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` construye un mapa de contexto de puntos de entrada, límites de confianza y sumideros antes de que se ejecute una sola línea de escaneo. `/agentic` luego ejecuta Semgrep y CodeQL, deduplica los hallazgos y despacha cada uno para su validación usando la metodología exploitation-validator:

Con `--threat-model`, RAPTOR ejecuta primero el mapa, crea `threat-model.json` y `THREAT_MODEL.md` si el proyecto aún no los tiene, y luego alimenta una versión compacta a `/understand`, al análisis autónomo y a `/validate`. Los modelos de amenazas existentes del proyecto se preservan a menos que pases `--threat-model-refresh`; los mapas de respaldo obsoletos se rechazan a menos que pases explícitamente `--threat-model-use-stale`. También convierte los flujos no verificados mapeados en SARIF candidato para que los fallos del escáner no maten la ejecución. Es contexto propiedad del operador, no prueba mágica: los hallazgos aún necesitan evidencia de código o confirmación respaldada por oráculo. Consulta `docs/threat-model.md`.

- Etapa A: ¿el patrón es realmente una vulnerabilidad, o es ruido de coincidencia de patrones de la herramienta?
- Etapa B: ¿qué necesita un atacante para alcanzarlo, y qué se interpone en el camino?
- Etapa C: ¿existe realmente la ruta de código? ¿se puede alcanzar desde fuera?
- Etapa D: veredicto final -- ¿es código de prueba, necesita precondiciones poco realistas, está el modelo siendo evasivo?
- Etapa E: viabilidad de explotación binaria (cuando hay un artefacto compilado disponible)
- Etapa F: autorrevisión -- ¿alguna etapa anterior fue evasiva o se contradijo a sí misma?

Los hallazgos que superan la validación obtienen PoCs de explotación y parches generados. Al final se ejecuta un análisis cruzado de hallazgos para encontrar causas raíz compartidas y cadenas de ataque.

`/validate` ejecuta este mismo pipeline como paso independiente si ya tienes hallazgos de un escaneo previo.

Para un artefacto compilado, `/binary <path>` ahora ejecuta una
investigación basada en evidencia en lugar de volcar un montón de artefactos
de ingeniería inversa en bruto sobre el operador. Por debajo sigue construyendo el manifiesto vinculado a SHA-256,
el libro de evidencia, el mapa de contexto, la lista de verificación y el grafo SQLite a partir de metadatos de archivo,
importaciones y referencias cruzadas de radare2. Las aplicaciones Mach-O también obtienen inventario de slices, metadatos de bundle
y selectores de clases Objective-C / Swift; el pseudocódigo de alto valor se
persiste en lugar de desaparecer dentro de la ejecución. Las exportaciones de DLL de PE, los despachadores de controladores de Windows y los manejadores ioctl de módulos del kernel de Linux también se tratan como
sus propios candidatos de ingreso, con la arquitectura PE leída desde la cabecera COFF
en lugar de adivinada. La capa de investigación luego consulta ese grafo,
clasifica el ingreso externo antes que las pistas genéricas de sumideros, descubre binarios auxiliares/hermanos declarados y escribe un informe compacto dividido en hechos,
inferencias estructurales e hipótesis no probadas. Las observaciones de Frida, los testigos de fallos de fuzzing, las comprobaciones explícitas de Z3 y los diffs binarios pueden luego añadir evidencia más sólida. RAPTOR también conserva el grafo de llamadas interno necesario para recuperar candidatos acotados de ingreso-a-parser, de modo que una callback de aplicación puede reducirse a la
función interna que realmente llama a `XML_Parse`, `d2i_X509`,
`jpeg_read_header` u otra superficie de parser real sin pretender que eso es
prueba de taint. `/binary trace-parser <run-dir>` es el seguimiento dinámico explícito:
ejecuta el trace acotado del parser con Frida, luego refresca el mismo mapa de contexto,
el handoff, el grafo y el informe de investigación en su lugar. `/binary investigate --active` mapea primero y solo lanza una campaña real
de fuzzing cuando existe un límite de harness concreto; los objetivos de aplicación, DLL y controlador obtienen un paso de harness o snapshot en su lugar. `/binary harness` escribe una especificación de harness respaldada por evidencia para el ingreso elegido y solo emite código fuente candidato cuando el contrato ABI o IOCTL es explícito. No se pasa de "`memcpy` existe" a "esto es
explotable": las importaciones, los selectores y las aristas de llamada permanecen como candidatos hasta que
algo mecánico pruebe más. Consulta `docs/binary-analysis.md`.

---

## Análisis de Composición de Software

`/sca` analiza el lado de dependencias y cadena de suministro de un proyecto. No es solo una búsqueda de CVE en archivos de requisitos: RAPTOR descubre manifiestos, lockfiles, comandos de instalación en línea, dependencias de workflows y fuentes de paquetes de contenedores/imágenes base, y luego los normaliza en una única vista de dependencias.

El escaneo enriquece las dependencias con avisos de OSV, CISA KEV, EPSS, CISA Vulnrichment/SSVC, alcanzabilidad, señales de evidencia de explotación, comprobaciones de higiene, heurísticas de cadena de suministro, hallazgos de política de licencias y revisión/triage opcional con LLM. Emite hallazgos nativos de RAPTOR más SBOM y salida compatible con CI:

- `findings.json` - hallazgos canónicos de RAPTOR
- `report.md` - resumen legible por humanos
- `sbom.cdx.json` - SBOM CycloneDX con datos VEX
- `findings.sarif` - salida de escaneo de código de GitHub/GitLab

Comandos comunes:```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

Una vez poblada, el escáner resuelve los IDs de paquete a archivos locales y no se realiza ninguna llamada de red. Sin la caché, RAPTOR intentará obtener los paquetes del registro desde semgrep.dev en el momento del escaneo; si está sin conexión, descarta los paquetes no almacenados en caché de forma controlada y se ejecuta solo con reglas personalizadas.

CodeQL necesita acceso a la red solo durante la configuración inicial para descargar la CLI y los paquetes de consultas. Una vez instalado, se ejecuta sin conexión.

---

## Reglas personalizadas

RAPTOR incluye más de 200 reglas de análisis estático personalizadas, probadas de forma adversarial para eliminar falsos positivos:

- **Semgrep (~150 reglas)** — reglas de seguimiento de taint y de patrones para Python, Go, Java y JS/TS. Cubre SQLi, XSS, SSRF, SSTI, inyección de comandos, deserialización, XXE, inyección LDAP/NoSQL, path traversal, redirección abierta, inyección de logs/headers, inyección de eval, ReDoS, contaminación de prototipos, mala configuración de JWT, criptografía débil, TLS inseguro y secretos embebidos en el código.
- **Coccinelle (68 reglas)** — coincidencia estructural para C/C++. Seguridad de memoria (double free, use-after-free, free de puntero no base, free de array en pila, memoria mapeada con mmap, use-after-close), errores con enteros (desbordamiento, extensión de signo, doble sizeof), fugas de recursos (desajuste popen/fclose, doble cierre de fdopendir), manejo de búferes (strncpy sin NUL, desajuste de tamaño en copy_user, off-by-one en malloc/strlen), seguridad de manejadores de señales, uso incorrecto de API (dominio de flags de fcntl, SIGKILL/SIGSTOP, doble byte-swap, búfer estático de inet_ntoa), eliminación de almacenamiento muerto por el compilador, confusión IS_ERR/PTR_ERR en el kernel, inyección de cadenas de formato, condiciones de carrera TOCTOU y más.
- **CodeQL (8 consultas)** — seguimiento de taint interprocedimental para C++ (inyección de cadenas de formato, truncamiento de enteros, use-after-move, invalidación de iteradores) y Java (XXE, deserialización insegura, inyección de logs, SSRF en Spring).

Explora las reglas directamente: `engine/semgrep/rules/`, `engine/coccinelle/rules/`, `engine/codeql/queries/`. Estas complementan los paquetes del registro de Semgrep que RAPTOR incorpora (`p/security-audit`, `p/owasp-top-ten`, `p/secrets` siempre; paquetes por grupo de políticas como `p/command-injection`, `p/jwt`, `p/xss` además) — la superposición es mínima.

---

## Cómo se audita RAPTOR a sí mismo

RAPTOR aplica el dogfooding a buena parte de su propio conjunto de herramientas de seguridad, pero merece la pena ser honestos sobre qué bloquea realmente un PR y qué simplemente se ejecuta en segundo plano para mantenernos honestos. Parte de esto es una barrera estricta, parte es una comprobación programada y parte es simplemente un benchmark que conservamos para poder detectar cuándo hemos empeorado las cosas. El desglose más completo, incluidos los parámetros reales y cómo reproducir las comprobaciones, está en `docs/ci-controls.md`.

| Control | Qué comprueba | Disparador | Configuración / evidencia |
|---|---|---|---|
| Ruff | Linting de corrección de Python (`F401`, `F811`, `F821`, `F841`) | Barrera sobre el diff del PR, más auditoría semanal de todo el árbol | `pyproject.toml`, `.github/workflows/lint.yml` |
| Pytest | Fronteras rápidas de pruebas unitarias/de integración, niveles específicos por subsistema (mediante despacho por grafo de imports), auditoría del prompt-envelope | PRs, pushes a `main`, cola de merge, suite completa programada | `pytest.ini`, `.github/workflows/tests.yml`, `.github/workflows/nightly.yml` |
| CodeQL Advanced | Escaneo de código de Python, C/C++ y GitHub Actions con acotación de alcance mediante grafo de imports | PRs, pushes a `main`, cola de merge, programación semanal | `.github/workflows/codeql.yml`, `.github/codeql/codeql-config.yml` |
| Endurecimiento de workflows | Actions de terceros fijadas por SHA, permisos de mínimo privilegio, linting de metadatos de comandos | Cada cambio de workflow y cada ejecución de lint | `.github/workflows/`, `.github/scripts/check_command_metadata.py` |
| Lint de etiquetas del corpus | Validación del esquema de etiquetas del corpus de auditoría y verificación de pines upstream | PRs (etiquetas modificadas), barrido completo semanal | `.github/workflows/corpus-labels.yml` |
| Barrera SCA PR de RAPTOR | Regresiones de dependencias y cadena de suministro introducidas por un PR | Cambios en manifiestos / lockfiles / workflows | `.github/workflows/sca-pr-gate.yml` |
| Auto-actualización SCA de RAPTOR | Endurecimiento mecánico de dependencias y propuestas de actualización seguras | Programación semanal, ejecución manual | `.github/workflows/sca-self-bump.yml` |
| Corpus de compromisos SCA | Si los compromisos de dependencias conocidos siguen disparando la señal esperada | Programación semanal, cambios relevantes en PRs | `test/data/sca-e2e/compromise-corpus/`, `.github/workflows/sca-compromise-check.yml` |
| Detectores de invariantes del repositorio | Detección de código muerto / llamadas incorrectas, deriva en la documentación de variables de entorno, barreras de listas de vocabulario, formas canónicas de bytes en JSON, lint de imports de dependencias opcionales | Barrera de PR (job `repo-invariants` de `lint.yml`), más barrido diario | `.github/workflows/lint.yml`, `.github/workflows/miswiring-scan.yml`, `.github/scripts/*_baseline.json` |
| Calibración SCA + corpus de estrés | Si la puntuación de riesgo y la cobertura del parser se desvían con el tiempo | Jobs programados semanales / mensuales | `packages/sca/data/calibration/`, `.github/workflows/refresh-sca-calibration.yml`, `.github/workflows/sca-stress-sweep.yml` |
| Corpus de dataflow | Seguimiento de precisión / exhaustividad / categoría de FP para el comportamiento del validador | Benchmark ejecutado por el desarrollador y pruebas de corpus | `core/dataflow/corpus/`, `core/dataflow/scripts/corpus-metrics` |
| Guardia del documento de controles de CI | Que existan las rutas documentadas, que la configuración de ruff coincida, que el README enlace al documento | PRs | `.github/tests/test_ci_controls_docs.py` |

Actualmente no aplicado: `mypy` está fijado en `pyproject.toml` pero no bloquea nada; el formateo de Ruff no se aplica; Semgrep forma parte de la superficie de escaneo de RAPTOR, pero todavía no tenemos un workflow de Semgrep dedicado a "escanear RAPTOR con RAPTOR".

---

## Usar un LLM diferente

RAPTOR tiene dos capas de modelo separadas, y merece la pena entender cómo funciona cada una antes de cambiar nada.

La **capa de orquestación** es Claude Code -- pero solo para el shell interactivo `raptor` (esta capa conversacional, de slash-commands). El CLAUDE.md, las skills y los comandos se ejecutan todos como instrucciones de Claude Code ahí. Para cambiar qué modelo de Claude orquesta esa capa, usa el flag `--model` de Claude Code o el comando `/model` dentro de una sesión. Si no quieres esta capa en absoluto, consulta [Ejecución totalmente autónoma](#running-fully-standalone-no-claude-code) más abajo.

La **capa de despacho de análisis** es el LLM que analiza los hallazgos de vulnerabilidad individuales. Es independiente de la capa de orquestación y puede ser cualquier proveedor compatible. Configúrala en `~/.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"
    }
  ]
}

Los roles de modelo te permiten asignar diferentes modelos a distintas tareas:

| Rol | Qué hace |
|------|-------------|
| `analysis` | Valida y analiza cada hallazgo (Etapas A-F) |
| `code` | Escribe PoCs de explotación y código de parche |
| `consensus` | Voto de segunda opinión sobre verdaderos positivos |
| `aggregate` | Opcional. Síntesis narrativa escrita por LLM sobre la correlación determinista multi-modelo, escrita en `aggregation.json` y el `agentic-report.md` final |
| `fallback` | Se usa si el modelo principal falla o alcanza los límites de tasa |

Si no se establece ningún rol, el primer modelo de la lista se encarga de todo. Para el análisis multi-modelo
de código fuente, configura dos o más modelos `analysis` — obtendrás la
correlación determinista por defecto. El rol `aggregate` es opcional y añade un
resumen escrito por LLM sobre ello:```bash
python3 raptor.py agentic --repo /code \
  --model claude-opus-4-6 \
  --model gpt-5.4 \
  --aggregate claude-sonnet-4-6

Ollama funciona bien para el análisis; la fiabilidad para la generación de código de exploit/parche depende de la escala del modelo y la cuantización, más que de ser una propiedad fija de los modelos locales — consulta [Quality Tradeoffs](https://github.com/gadievron/raptor/blob/main/llm.md#quality-tradeoffs) en la guía de LLM, y revisa `/scorecard` para ver qué está midiendo realmente tu modelo específico.

### Ejecución totalmente independiente (sin Claude Code)

`bin/raptor` -- el shell interactivo con el banner y los comandos de barra, es decir, esta capa conversacional -- hace exec directamente en el CLI de Claude Code y siempre necesita su propio inicio de sesión. La mecánica real subyacente no: `python3 raptor.py <mode>` es un CLI de Python simple sin ninguna dependencia de 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

Apunta `models.json` / `OLLAMA_HOST` a una instancia local de Ollama (ver arriba) y toda esta ruta nunca se comunica con Anthropic -- útil para máquinas aisladas o hardware exclusivamente local. Pierdes la capa conversacional de comandos con barra (este chat); el propio pipeline de escaneo/análisis/exploit no se ve afectado.

### Cortocircuito de nivel rápido + el cuadro de puntuación de modelos

Cuando tu modelo de nivel de análisis tiene un hermano más económico del mismo proveedor (Anthropic Opus → Haiku, OpenAI 5.x → 4o-mini, Gemini Pro → Flash-Lite, Mistral Large → Small), RAPTOR lo usará como prefiltro en los consumidores que se conectan al sustrato (codeql hoy; SCA y otros a medida que lleguen los seguimientos). El modelo económico solo cortocircuita en **falsos positivos con confianza**; los casos ambiguos y los TP con confianza siempre ejecutan el análisis completo. La confianza se acumula por celda `(model, decision_class)` — RAPTOR registra la concordancia entre el modelo económico y el completo y solo cortocircuita una vez que el límite superior del 95% de Wilson sobre la tasa de fallos de la celda cae en o por debajo del 5%.

Para inspeccionar en qué son buenos tus modelos, usa `/scorecard` (o directamente: `libexec/raptor-llm-scorecard list`). El cuadro de puntuación es global (las lecciones se mantienen entre proyectos) y persiste en `out/llm_scorecard.json`.

---

## Proyectos

Sin un proyecto, cada ejecución obtiene su propio directorio con marca de tiempo bajo `out/`. Con un proyecto, todo va a un solo lugar y obtienes hallazgos fusionados, seguimiento de cobertura y diffs entre ejecuciones.```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

La división significa que puedes ejecutar la capa de Python desde un pipeline de CI (`python3 raptor.py scan --repo ...`) y obtener una salida SARIF estructurada sin Claude Code, o ejecutarla de forma interactiva con el flujo de trabajo agéntico completo.

---

## OSS forensics

`/oss-forensics` investiga repositorios públicos de GitHub utilizando evidencia de múltiples fuentes: la API de GitHub, GH Archive (historial de eventos inmutable a través de BigQuery), la Wayback Machine y el historial local de git. Ejecuta un pipeline estructurado desde la recopilación de evidencia hasta la formulación de hipótesis y un informe forense final.

Requiere `GOOGLE_APPLICATION_CREDENTIALS` para el acceso a BigQuery. Consulta `.claude/commands/oss-forensics.md` para más detalles.

---

## Expert personas

Ocho personas expertas están disponibles bajo demanda. Carga una cuando quieras una perspectiva diferente sobre un hallazgo o una 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

Mantener `/web`, Z3, SAGE y los SDK de proveedores de nube como extras opcionales evita que la instalación predeterminada de RAPTOR sea más pesada y frágil de lo necesario.