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

Si agregas `bin/` a tu PATH (o enlazas simbólicamente `bin/raptor` en algún lugar del PATH), puedes ejecutar `raptor` desde cualquier directorio -- el lanzador resuelve la instalación de RAPTOR y configura el directorio de trabajo automáticamente.

**Importante:** RAPTOR carga su configuración desde el directorio del repositorio. Si ejecutas `claude` desde un directorio diferente, obtienes Claude Code simple, no RAPTOR. O bien haz `cd` al repositorio primero, o usa el lanzador `raptor`.

### Opción 2: Devcontainer (recomendado)

Todo preinstalado. Abre en VS Code con **Dev Containers: Open Folder in Container**, o descarga la imagen preconstruida:```bash
docker pull danielcuthbert/raptor:latest
docker run --privileged -it -v "$(pwd):/workspaces/raptor" danielcuthbert/raptor:latest

El flag `--privileged` es necesario para el depurador determinista `rr`. La imagen es grande (alrededor de 6 GB). Comienza desde el devcontainer de Microsoft Python 3.12 y añade análisis estático, fuzzing y herramientas de automatización de navegadores.

Una vez dentro, simplemente di "hi" para comenzar, o salta directamente a un comando.

---

## Qué esperar en la primera ejecución

Lo más simple 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 una base de código de tamaño mediano con ~50 hallazgos, espere de 10 a 30 minutos y $2-8 en costos de LLM de la capa de análisis (dependiendo del modelo). El límite de costo predeterminado es $10 por ejecución; ajústelo con `--max-cost-usd`.

**Nota sobre costos:** La capa de orquestación de Claude Code utiliza su suscripción de Claude. La capa de envío de análisis realiza llamadas API de LLM separadas que se facturan por token. Si solo usa Claude Code como modelo de análisis (el predeterminado), no hay costo adicional más allá de su suscripción. Si configura modelos externos (OpenAI, Gemini, etc.), esas llamadas 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 aíslan (sandbox) usando espacios de nombres de Linux, Landlock y seccomp. El entorno aislado bloquea el acceso a la red, restringe la visibilidad del sistema de archivos y limita el consumo de recursos. Consulte `docs/sandbox.md` para conocer 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 iniciar (`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 utilizan argumentos basados en listas.

---

## Lo que RAPTOR puede hacer

| 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 superficie de ataque, rastrear flujos de datos, buscar variantes de vulnerabilidad | Estable |
| `/binary` | Investigación binaria de caja negra, evidencia en tiempo de ejecución, consultas de grafos y traspaso | Beta |
| `/validate` | Pipeline de validación de explotabilidad de múltiples etapas (Etapas 0-F) | Estable |
| `/codeql` | Análisis profundo solo con CodeQL con preselección de flujo de datos SMT | Estable |
| `/sca` | Análisis de composición de software: dependencias, avisos, señales de cadena de suministro, SBOMs y correcciones | Beta |
| `/exploit` | Generar código de explotación de prueba de concepto | Beta |
| `/patch` | Generar parches seguros para vulnerabilidades confirmadas | Beta |
| `/fuzz` | Fuzzing binario con AFL++ y análisis de fallos | Estable |
| `/crash-analysis` | Análisis autónomo de causa raíz para fallos en 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 |
| `/threat-model` | Crear, inspeccionar y mantener modelos de amenazas por proyecto | Estable |
| `/sage` | Capa de memoria persistente (almacenar, recordar, vincular, corroborar) | Estable |
| `/frida` | Instrumentación dinámica mediante Frida | Alpha |
| `/web` | Escaneo de aplicaciones web | Alpha/borrador |

---

## Cómo funciona el pipeline

Comience creando un proyecto para que todas sus ejecuciones estén 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 ocurra una línea de escaneo. `/agentic` luego ejecuta Semgrep y CodeQL, deduplica los hallazgos y envía cada uno para su validación utilizando la metodología de validador de explotación:

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

- Stage A: ¿es el patrón realmente una vulnerabilidad, o es ruido de coincidencia de patrones de la herramienta?
- Stage B: ¿qué necesita un atacante para alcanzarlo, y qué se interpone en el camino?
- Stage C: ¿existe realmente la ruta de código? ¿se puede alcanzar desde fuera?
- Stage D: decisión final: ¿es esto código de prueba, necesita condiciones previas irreales, está el modelo siendo cauteloso?
- Stage E: viabilidad de explotación del binario (cuando hay un artefacto compilado disponible)
- Stage F: autorevisión: ¿alguna etapa anterior fue cautelosa o se contradijo?

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

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

Para un artefacto compilado, `/binary <path>` ahora ejecuta una investigación basada en evidencia en lugar de arrojar un montón de artefactos brutos de ingeniería inversa al operador. Debajo aún construye el manifiesto vinculado a SHA-256, el libro de evidencia, el mapa de contexto, la lista de verificación y el gráfico SQLite a partir de metadatos de archivo, importaciones y referencias cruzadas de radare2. Las aplicaciones Mach-O también obtienen inventario de slices, metadatos del 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 PE, los despachadores de controladores de Windows y los manejadores ioctl de módulos del kernel de Linux también se manejan como sus propios candidatos de ingreso, con la arquitectura PE leída del encabezado COFF en lugar de adivinada. La capa de investigación luego consulta ese gráfico, clasifica el ingreso externo antes que las pistas de sumidero genérico, 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 las diferencias binarias pueden agregar evidencia más sólida más adelante. RAPTOR también mantiene el gráfico de llamadas interno necesario para recuperar candidatos de ingreso a analizador acotados, de modo que una devolución de llamada de la aplicación puede reducirse a la función interna que realmente llama a `XML_Parse`, `d2i_X509`, `jpeg_read_header` u otra superficie de analizador real sin pretender que eso sea prueba de mancha. `/binary trace-parser <run-dir>` es la continuación dinámica explícita: ejecuta el rastreo estrecho del analizador de Frida, luego actualiza el mismo mapa de contexto, transferencia, gráfico e informe de investigación en su lugar. `/binary investigate --active` mapea primero y solo lanza una campaña de fuzzing real cuando existe un límite de harness concreto; los objetivos de aplicación, DLL y controlador reciben 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 abre paso desde “`memcpy` existe” hasta “esto es explotable”: las importaciones, selectores y bordes de llamada siguen siendo candidatos hasta que algo mecánico pruebe más. Consulte `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, archivos de bloqueo, comandos de instalación en línea, dependencias de flujo de trabajo y fuentes de paquetes de contenedores/imágenes base, 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/triaje opcional de LLM. Emite hallazgos nativos de RAPTOR más SBOM y salida amigable para 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 poblado, el escáner resuelve los ID de los paquetes a archivos locales y no se realiza ninguna llamada de red. Sin la caché, RAPTOR intentará obtener paquetes del registro desde semgrep.dev durante el escaneo; si está fuera de línea, descarta los paquetes no cacheados de forma segura y ejecuta solo con reglas personalizadas.

CodeQL solo necesita acceso a la red durante la configuración inicial para descargar la CLI y los paquetes de consultas. Una vez instalado, funciona fuera de línea.

---

## Reglas personalizadas

RAPTOR incluye 185 reglas personalizadas de análisis estático, probadas adversarialmente para eliminar falsos positivos:

- **Semgrep (123 reglas)** — reglas de taint-tracking y 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, open redirect, inyección de log/header, eval injection, ReDoS, prototype pollution, configuración incorrecta de JWT, criptografía débil, TLS inseguro y secretos codificados.
- **Coccinelle (54 reglas)** — coincidencia estructural para C/C++. Seguridad de memoria (double free, use-after-free, free of non-base pointer, free of stack array, mmap'd memory, use-after-close), errores de enteros (overflow, sign extension, double sizeof), fugas de recursos (popen/fclose mismatch, fdopendir double close), manejo de buffers (strncpy without NUL, copy_user size mismatch, malloc/strlen off-by-one), seguridad de manejadores de señales, mal uso de la API (fcntl flag domain, SIGKILL/SIGSTOP, double byte-swap, inet_ntoa static buffer), eliminación de almacenamiento muerto del compilador, confusión IS_ERR/PTR_ERR del kernel, inyección de cadenas de formato, carreras TOCTOU y más.
- **CodeQL (8 consultas)** — rastreo de taint interprocedural para C++ (format string injection, integer truncation, use-after-move, iterator invalidation) y Java (XXE, insecure deserialisation, log injection, Spring SSRF).

Explore las reglas directamente: `engine/semgrep/rules/`, `engine/coccinelle/rules/`, `engine/codeql/queries/`. Estos complementan los paquetes del registro (`p/security-audit`, `p/owasp-top-ten`, `p/0xdea`, `p/trailofbits`) que proporcionan ~950 reglas adicionales — la superposición es mínima.

---

## Usando un LLM diferente

RAPTOR tiene dos capas de modelo separadas, y vale la pena saber cómo funcionan ambas antes de cambiar algo.

La **capa de orquestación** es siempre Claude Code. Los archivos CLAUDE.md, skills y comandos se ejecutan como instrucciones de Claude Code. Para cambiar qué modelo de Claude orquesta RAPTOR, use la bandera `--model` de Claude Code o el comando `/model` dentro de una sesión.

La **capa de despacho de análisis** es el LLM que analiza hallazgos de vulnerabilidad individuales. Esta es separada de la capa de orquestación y puede ser cualquier proveedor compatible. Configúrela 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 diferentes tareas:

| Rol | Qué hace |
|------|-------------|
| `analysis` | Valida y analiza cada hallazgo (Etapas A-F) |
| `code` | Escribe PoCs de exploits y código de parches |
| `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 en el informe final `agentic-report.md` |
| `fallback` | Se usa si el modelo principal falla o alcanza los límites de tasa |

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

Ollama funciona para el análisis, pero produce código de exploit y parche poco fiable. Para tareas de generación de código, utilice un modelo frontier.

### Cortocircuito de nivel rápido + la tarjeta de puntuación del modelo

Cuando su modelo de nivel de análisis tiene un hermano más barato del mismo proveedor (Anthropic Opus → Haiku, OpenAI 5.x → 4o-mini, Gemini Pro → Flash-Lite, Mistral Large → Small), RAPTOR lo utilizará como prefiltro en los consumidores que se conecten al sustrato (codeql hoy; SCA y otros como seguimientos). El modelo barato solo hace cortocircuito en **falsos positivos seguros**; los casos ambiguos y los TP seguros siempre ejecutan el análisis completo. La confianza se acumula por celda `(modelo, clase_de_decisión)` — RAPTOR registra el acuerdo barato vs completo y solo cortocircuita una vez que el límite superior de Wilson del 95% sobre la tasa de fallos de la celda cae al 5% o menos.

Para inspeccionar en qué son buenos sus modelos, use `/scorecard` (o directamente: `libexec/raptor-llm-scorecard list`). La tarjeta de puntuación es global (las lecciones se aplican entre proyectos) y persiste en `out/llm_scorecard.json`.

---

## Proyectos

Sin un proyecto, cada ejecución obtiene su propio directorio con marca de tiempo en `out/`. Con un proyecto, todo va a un solo lugar y obtiene hallazgos combinados, seguimiento de cobertura y diferencias 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 ejecutarlo 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), Wayback Machine y el historial local de git. Ejecuta un pipeline estructurado desde la recolección de evidencia hasta la formación de hipótesis y un informe forense final.

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

---

## Expert personas

Siete personas expertas están disponibles a pedido. 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
Fuzzing Strategist                             Corpus design and triage
Binary Exploitation Specialist                 ROP, heap, and memory corruption