╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║             ██████╗  █████╗ ██████╗ ████████╗ ██████╗ ██████╗             ║
║             ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗            ║
║             ██████╔╝███████║██████╔╝   ██║   ██║   ██║██████╔╝            ║
║             ██╔══██╗██╔══██║██╔═══╝    ██║   ██║   ██║██╔══██╗            ║
║             ██║  ██║██║  ██║██║        ██║   ╚██████╔╝██║  ██║            ║
║             ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝    ╚═════╝ ╚═╝  ╚═╝            ║
║                                                                           ║
║             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 (para que comandos como `/scan` lo usen por defecto), ejecuta las comprobaciones previas de confianza y del proyecto, carga el plugin de seguimiento de cobertura y sane el entorno antes de entregar el control a Claude Code. También acepta una ruta de destino opcional y banderas como `--project`, `--continue` y `--model`; consulta `raptor --help`.

Ejecutar `claude` directamente desde dentro del directorio del repositorio también funciona: Claude Code detecta la configuración de RAPTOR desde el checkout, pero te saltas todo lo que hace el lanzador anteriormente: 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 este modo de fallo por completo.

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

El uso de contenedores es una práctica de seguridad común para restringir que los agentes accedan 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 a la 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 precompilada:```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`.

Los devcontainers de VS Code también son compatibles. 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 la primera ejecución

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

Esto ejecuta el pipeline completo: escaneo, deduplicación y luego envío de cada hallazgo a través de las etapas de validación (A-F). En un código base de tamaño mediano con ~50 hallazgos, espera entre 10 y 30 minutos y $2-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 de costos:** La capa de orquestación de Claude Code utiliza tu suscripción de Claude. La capa de despacho de análisis realiza llamadas API de LLM separadas 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 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 en 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 conocer el modelo de amenazas completo y la configuración.

Las variables de entorno que podrían inyectar código en la cadena del lanzador se eliminan al inicio (`core/security/_dangerous_env_strip.sh`). Las rutas de archivo de los repositorios escaneados nunca se interpolan en cadenas de shell; todas las llamadas a subprocesos usan 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 vulnerabilidades | Estable |
| `/binary` | Investigación de binarios de caja negra, evidencia en tiempo de ejecución, consultas de grafos y traspaso | Beta |
| `/ghidra` | Puente RE con Ghidra: adjuntar/importar proyectos `.gpr`, diff entre versiones, exportación de hallazgos | Beta |
| `/audit` | Revisión de código sistemática guiada por hipótesis y basada en herramientas | Beta |
| `/review` | Consultar el estado de la auditoría: hallazgos, brechas, cobertura, notas del operador | Estable |
| `/annotate` | Adjuntar anotaciones de prosa libres por función (notas de revisión del operador) | Estable |
| `/validate` | Pipeline de validación de explotabilidad en múltiples etapas (Etapas 0-F) | Estable |
| `/diagram` | Mapas visuales Mermaid a partir de salidas JSON de `/understand` y `/validate` | Beta |
| `/codeql` | Análisis profundo solo con CodeQL con preselección de flujo de datos SMT | Estable |
| `/analyze` | Analizar hallazgos SARIF existentes con LLM, sin volver a escanear | Estable |
| `/sca` | Análisis de composición de software: dependencias, avisos, señales de cadena de suministro, SBOM 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 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 |
| `/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, vincular, corroborar) | Estable |
| `/ask` | Enviar un prompt de formato libre a cualquier modelo LLM configurado | Estable |
| `/scorecard` | Inspeccionar la fiabilidad por modelo en clases de decisión | Estable |
| `/frida` | Instrumentación dinámica mediante Frida | Alfa |
| `/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 línea de escaneo. `/agentic` luego ejecuta Semgrep y CodeQL, deduplica los hallazgos y despacha cada uno para su validación utilizando 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 en `/understand`, análisis autónomo y `/validate`. Los modelos de amenazas existentes del proyecto se conservan 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 el patrón de la herramienta es ruido?
- Etapa B: ¿qué necesita un atacante para alcanzarlo, y qué se interpone en el camino?
- Etapa C: ¿la ruta de código realmente existe? ¿se puede alcanzar desde el exterior?
- Etapa D: decisión final: ¿es código de prueba, requiere condiciones previas poco realistas, está el modelo evadiendo?
- Etapa E: viabilidad de explotación binaria (cuando hay un artefacto compilado disponible)
- Etapa F: auto-revisión: ¿alguna etapa anterior evadió o se contradijo?

Los hallazgos que superan la validación reciben PoCs de explotación y parches generados. Un análisis entre hallazgos se ejecuta al final para encontrar causas raíz compartidas y cadenas de ataque.

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

Para un artefacto compilado, `/binary <path>` ahora ejecuta una investigación
basada en evidencia en lugar de volcar un montón de artefactos crudos de
ingeniería inversa sobre el operador. Internamente aún construye el manifiesto vinculado a SHA-256,
el registro de evidencia, el mapa de contexto, la lista de verificación y el grafo SQLite a partir de metadatos de archivo,
imports y xrefs de radare2. Las apps 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 PE, los
dispatchers de controladores de Windows y los manejadores ioctl de módulos de kernel Linux se manejan como
sus propios candidatos de ingreso también, con la arquitectura PE leída desde el encabezado
COFF en lugar de adivinarse. La capa de investigación luego consulta ese grafo,
clasifica el ingreso externo antes que las pistas genéricas de sumideros, descubre binarios
helper/hermanos declarados y escribe un informe compacto dividido en hechos,
inferencias estructurales e hipótesis no probadas. Las observaciones de Frida, los testigos de
crashes de fuzzing, las comprobaciones explícitas de Z3 y los diffs binarios pueden luego añadir evidencia
más sólida más tarde. RAPTOR también mantiene el grafo de llamadas interno necesario para recuperar
candidatos acotados de ingreso-a-parser, de modo que una devolución de llamada de app pueda 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 sea
prueba de taint. `/binary trace-parser <run-dir>` es el seguimiento dinámico explícito:
ejecuta el trace de parser estrecho de Frida, luego actualiza el mismo mapa de contexto,
handoff, grafo 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 app, 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 a base de faroles desde “`memcpy` existe” hasta “esto es
explotable”: los imports, selectores y bordes de llamada siguen siendo 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 CVEs en archivos de requisitos: RAPTOR descubre manifiestos, lockfiles, comandos de instalación en línea, dependencias de flujos de trabajo 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 por LLM. Emite hallazgos nativos de RAPTOR además de 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 code-scanning 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 IDs de los packs a archivos locales y no se realiza ninguna llamada de red. Sin la caché, RAPTOR intentará obtener los packs del registro desde semgrep.dev en el momento del escaneo; si está sin conexión, descarta los packs no almacenados en caché de forma segura y se ejecuta solo con reglas personalizadas.

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

---

## Reglas personalizadas

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

- **Semgrep (145 reglas)** — reglas de seguimiento de flujo de datos (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, open redirect, inyección de logs/cabeceras, inyección de eval, ReDoS, contaminación de prototipos, configuración incorrecta de JWT, criptografía débil, TLS inseguro y secretos codificados.
- **Coccinelle (63 reglas)** — coincidencia estructural para C/C++. Seguridad de memoria (doble liberación, use-after-free, liberación de puntero no base, liberación de array en pila, memoria mmap, use-after-close), errores de enteros (desbordamiento, extensión de signo, doble sizeof), fugas de recursos (desajuste popen/fclose, doble cierre de fdopendir), manejo de buffers (strncpy sin NUL, desajuste de tamaño en copy_user, off-by-one en malloc/strlen), seguridad de manejadores de señales, mal uso de API (dominio de flags fcntl, SIGKILL/SIGSTOP, doble byte-swap, buffer estático de inet_ntoa), eliminación de dead-store del compilador, confusión IS_ERR/PTR_ERR del kernel, inyección de cadenas de formato, carreras TOCTOU y más.
- **CodeQL (8 consultas)** — seguimiento de flujo de datos 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 packs del registro de Semgrep que RAPTOR incorpora (`p/security-audit`, `p/owasp-top-ten`, `p/secrets` siempre; packs por grupo de políticas como `p/command-injection`, `p/jwt`, `p/xss` adicionalmente) — la superposición es mínima.

---

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

RAPTOR utiliza en buena medida sus propias herramientas de seguridad, pero vale la pena ser honestos sobre qué bloquea realmente un PR y qué se ejecuta solo en segundo plano para mantenernos íntegros. Parte de esto es una barrera estricta, parte es una comprobación programada y parte es solo un benchmark que mantenemos para saber cuándo hemos empeorado las cosas. El desglose completo, incluidos los parámetros reales y cómo reproducir las comprobaciones, está en `docs/ci-controls.md`.

| Control | Qué comprueba | Disparador | Config / evidencia |
|---|---|---|---|
| Ruff | Linting de corrección de Python (`F401`, `F811`, `F821`, `F841`) | Barrera en diff de PR, más auditoría semanal de todo el árbol | `pyproject.toml`, `.github/workflows/lint.yml` |
| Pytest | Límites rápidos de unit/integración, niveles específicos por subsistema (mediante despacho por grafo de importaciones), auditoría de prompt-envelope | PRs, envíos 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 reducción de alcance por grafo de importaciones | PRs, envíos a `main`, cola de merge, programación semanal | `.github/workflows/codeql.yml`, `.github/codeql/codeql-config.yml` |
| Hardening de workflows | Acciones de terceros fijadas por SHA, permisos de privilegio mínimo, 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 de corpus | Validación del esquema de etiquetas del corpus de auditoría y verificación de pines ascendentes | PRs (etiquetas modificadas), barrido semanal completo | `.github/workflows/corpus-labels.yml` |
| Barrera SCA de PR de RAPTOR | Regresiones de dependencias y cadena de suministro introducidas por un PR | Cambios en manifest / lockfile / workflows | `.github/workflows/sca-pr-gate.yml` |
| Auto-bump 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 compromiso SCA | Si los compromisos de dependencias conocidos siguen activando la señal esperada | Programación semanal, cambios de PR relevantes | `test/data/sca-e2e/compromise-corpus/`, `.github/workflows/sca-compromise-check.yml` |
| Escaneo de cableado incorrecto | Detección de código muerto / llamadas incorrectas, deriva de documentación de variables de entorno, salvaguardas de listas de vocabulario, lint de importaciones opcionales de dependencias | Programación diaria | `.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 | Trabajos programados semanales / mensuales | `packages/sca/data/calibration/`, `.github/workflows/refresh-sca-calibration.yml`, `.github/workflows/sca-stress-sweep.yml` |
| Corpus de flujo de datos | Seguimiento de precisión / recall / categorías de FP para el comportamiento del validador | Benchmark ejecutado por desarrolladores y pruebas de corpus | `core/dataflow/corpus/`, `core/dataflow/scripts/corpus-metrics` |
| Guardián del doc de controles de CI | Las rutas documentadas existen, la config de ruff coincide, el README enlaza al doc | PRs | `.github/tests/test_ci_controls_docs.py` |

Actualmente no se aplican: `mypy` está instalado en `requirements-dev.txt` pero no bloquea nada; el formateo de Ruff no se aplica; Semgrep forma parte de la superficie de escaneo de RAPTOR, pero aún no tenemos un workflow dedicado de "escanear RAPTOR con RAPTOR" con Semgrep.

---

## Usar un LLM diferente

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

La **capa de orquestación** es siempre Claude Code. El CLAUDE.md, las skills y los comandos se ejecutan todos como instrucciones de Claude Code. Para cambiar qué modelo de Claude orquesta RAPTOR, usa 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 los hallazgos individuales de vulnerabilidades. Esta 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"
    }
  ]
}

| 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 de múltiples modelos, guardada 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 establecen roles, el primer modelo de la lista se encarga de todo. Para el análisis
de código fuente con múltiples modelos, 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 encima:```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 exploits y parches poco fiable. Para tareas de generación de código, usa un modelo de frontera.

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

Cuando tu 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 usará como prefiltro en los consumidores que se conectan al sustrato (codeql hoy; SCA y otros llegarán en seguimientos posteriores). El modelo barato solo hace cortocircuito en **falsos positivos seguros**; los casos ambiguos y los positivos seguros siempre ejecutan el análisis completo. La confianza se acumula por celda `(modelo, clase_de_decisión)` — RAPTOR registra el acuerdo entre el modelo barato y el completo, y solo hace cortocircuito una vez que el límite superior del 95% de Wilson sobre la tasa de errores de la celda cae al 5% o menos.

Para inspeccionar en qué son buenos tus modelos, usa `/scorecard` (o directamente: `libexec/raptor-llm-scorecard list`). La tarjeta de puntuación es global (las lecciones se trasladan 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 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 salida SARIF estructurada sin Claude Code, o ejecutarla de forma interactiva con el flujo de trabajo agéntico completo.

---

## Forense OSS

`/oss-forensics` investiga repositorios públicos de GitHub utilizando evidencia de múltiples fuentes: la API de GitHub, GH Archive (historial de eventos inmutable vía BigQuery), la Wayback Machine y el historial local de git. Ejecuta un pipeline estructurado desde la recopilación de evidencia hasta la formació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.

---

## Personas expertas

Siete 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
Fuzzing Strategist                             Corpus design and triage
Binary Exploitation Specialist                 ROP, heap, and memory corruption