Arnés de Referencia para Defensa de Código

Una implementación de referencia para el descubrimiento y remediación autónomos de vulnerabilidades con Claude, basada en nuestros aprendizajes de asociarnos con equipos de seguridad en varias organizaciones desde el lanzamiento de Claude Mythos Preview. Para un informe de estos aprendizajes junto con mejores prácticas, consulte la publicación de blog adjunta (también disponible en blog-post.md). Para un tutorial ligero solo con SDK del mismo ciclo de reconocimiento → búsqueda → triaje → informe → parche, consulte el libro de cocina complementario.

Este repositorio no se mantiene y no acepta contribuciones.

🔒 ¿Quiere una opción gestionada? Anthropic ofrece Claude Security, un producto alojado que encuentra y corrige vulnerabilidades en su código fuente en múltiples proyectos. Claude Security escanea su repositorio en busca de vulnerabilidades, aplica un pipeline de verificación de varias etapas para reducir falsos positivos, y le permite gestionar los hallazgos a lo largo de su ciclo de vida: triaje, validación de correcciones y generación rápida de parches.

Este repositorio es una implementación de referencia de código abierto basada en mejores prácticas generales para encontrar vulnerabilidades usando Claude. Puede usarlo para construir su propio pipeline de búsqueda de vulnerabilidades, personalizar la lógica, y se puede usar con cualquier acceso que tenga a las APIs de Claude (incluyendo Bedrock, Vertex o Azure).

Contenido

• Habilidades de Claude Code: /quickstart, /threat-model, /vuln-scan, /triage, /patch, /customize: alcance interactivo, escaneo, triaje y parches. Abra este repositorio en Claude Code y ejecute /quickstart para orientarse.
• harness/: el pipeline de referencia autónomo (reconocimiento → búsqueda → verificación → informe → parche), configurado para encontrar vulnerabilidades de memoria en C/C++ usando Docker y ASAN. Este harness es una referencia, no un producto. La forma general, los prompts y el sandboxing son reutilizables, pero el harness no funcionará con todas las bases de código listas para usar. Ejecute /customize para adaptarlo a su lenguaje, detector o clase de vulnerabilidad.

⚠️ Seguridad: /quickstart, /threat-model, /vuln-scan y /triage solo leen y escriben archivos. Ejecutar /patch sobre hallazgos estáticos (TRIAGE.json o VULN-FINDINGS.json) también es de solo lectura y escritura. /customize edita el código del harness y ejecuta comandos de validación. Cualquiera de estas habilidades es segura de ejecutar sin sandbox, siempre que revise y apruebe cada uso de herramienta en Claude Code. El pipeline de referencia autónomo (incluyendo /patch sobre resultados del pipeline) ejecuta código objetivo, por lo que se niega a ejecutarse fuera de un sandbox de gVisor a menos que se anule explícitamente. Para configurarlo, ejecute scripts/setup_sandbox.sh una vez, luego invoque el pipeline mediante bin/vp-sandboxed. Consulte docs/security.md y para más detalles.

Primeros Pasos

git clone https://github.com/anthropics/defending-code-reference-harness
cd defending-code-reference-harness
claude

# Introducción de 30 segundos + primera ejecución guiada en el objetivo canary
> /quickstart

> /quickstart how do I port the pipeline to Java?
> /quickstart how do I triage all these bugs?

Lecturas Adicionales

• Publicación de Blog · La publicación de blog adjunta con aprendizajes + mejores prácticas
• Pipeline · Cómo funciona: diagrama, etapas, flags de CLI
• Seguridad · Sandboxing, qué no montar
• Sandbox del agente · Aislamiento gVisor + lista de permisos de salida para cada agente
• Personalización · Adaptar a mi stack; qué archivos cambian y por qué
• Parcheo · Generar y verificar correcciones para cierres confirmados
• Solución de Problemas · Duplicados, límites de tasa, fijación de modelo de subagente
• Salvaguardias · Bloqueo para trabajo cibernético peligroso

Aceleración

Los equipos de seguridad con los que nos hemos asociado con más éxito son aquellos que se han puesto manos a la obra más rápido. Aunque es tentador pasar meses diseñando el pipeline perfecto, recomendamos empezar con algo pequeño el Día 1 y construir desde ahí a medida que surgen aprendizajes. Los siguientes pasos siguen ese patrón y marcan un ritmo ambicioso (pero razonable) basado en lo que hemos visto.

Paso 1 (Día 1): Construir un modelo de amenaza y ejecutar su primer escaneo estático + triaje

El Día 1 se centra en ver todo el ciclo de principio a fin. Usando solo las habilidades interactivas, construirá un modelo de amenaza, ejecutará un escaneo estático delimitado por él, triará lo que regrese y redactará correcciones candidatas. Terminará el día con un modelo de amenaza, una lista clasificada de hallazgos estáticos y parches candidatos.

Las habilidades relevantes solo leen y escriben archivos en su repositorio. Mientras ejecute Claude Code de forma interactiva y apruebe cada uso de herramienta, no se necesita ningún sandbox.

# Fijar cada subagente al modelo deseado
export CLAUDE_CODE_SUBAGENT_MODEL=<model-id>
claude

# 0. Introducción + primera ejecución guiada
> /quickstart

# 1. Construir un modelo de amenaza (apuntar antes de disparar)
> /threat-model bootstrap targets/canary

# 2. Ejecutar un escaneo estático, delimitado por ese modelo de amenaza
> /vuln-scan targets/canary

# 3. Verificar, deduplicar y clasificar lo que regresó
> /triage targets/canary/VULN-FINDINGS.json

# 4. Generar correcciones candidatas para los hallazgos verificados
> /patch ./TRIAGE.json --repo targets/canary

Este flujo produce THREAT_MODEL.md, VULN-FINDINGS.{json,md}, TRIAGE.{json,md} y PATCHES/.

Los candidatos a vulnerabilidad producidos en el Paso 1 provienen de la revisión estática de Claude del código fuente (no se construye ni ejecuta nada), por lo que espere más falsos positivos en cualquier objetivo que no sea canary. En el Paso 2, producirá hallazgos verificados por ejecución.

Nota: en el objetivo canary, /triage puede descartar los hallazgos del escaneo como falsos positivos. entry.c se anuncia a sí mismo como código de demostración deliberadamente vulnerable, y /triage excluye correctamente errores en código de prueba/fixture. Para ver el flujo completo de confirmación/deduplicación/falso positivo, ejecútelo en el fixture seleccionado en su lugar (/triage .claude/skills/triage/fixtures/canary-findings.json --repo targets/canary) o apunte las habilidades del Paso 1 a su propio código.

Paso 2 (Día 2): Ejecutar el pipeline de referencia en una biblioteca C/C++

En el Día 2, pasará de las habilidades interactivas a su primera ejecución autónoma usando el pipeline de referencia. Ejecutará el ciclo completo de reconocimiento → búsqueda → verificación → informe en su entorno sobre una biblioteca de código abierto conocidamente vulnerable, luego generará un parche candidato para lo que encuentre. Terminará con un conjunto de cierres reproducibles, informes de explotabilidad y parches candidatos, junto con una idea de cómo funciona el pipeline.

Ejecutar el pipeline es simple:

# Configuración única
python3 -m venv .venv && .venv/bin/pip install -e .
./scripts/setup_sandbox.sh   # instala gVisor, construye las imágenes del agente y verifica el aislamiento; nota: requiere Docker
export ANTHROPIC_API_KEY=sk-ant-...   # o CLAUDE_CODE_OAUTH_TOKEN, o Bedrock — consulte docs/agent-sandbox.md

# Ejecutar el ciclo de reconocimiento → búsqueda → verificación → informe
bin/vp-sandboxed run drlibs --model <model-id> --runs 3 --parallel --stream --auto-focus
# Generar un parche candidato para cada hallazgo
bin/vp-sandboxed patch results/drlibs/<timestamp>/ --model <model-id>

# O, pedir a Claude Code que lance el pipeline y supervise la ejecución por usted
claude
> run the pipeline on drlibs and explain findings as they come

Los resultados del ciclo aterrizan en un directorio results/drlibs/<timestamp>/. Con el flag --stream, el primer informe aparecerá en minutos bajo reports/bug_NN/.

⚠️ run crea agentes autónomos. El pipeline ejecuta cada agente dentro de un contenedor gVisor con la salida restringida a la API de Claude. Los subcomandos que crean agentes se niegan a iniciarse fuera de él a menos que se anule explícitamente. Para más información, consulte docs/security.md y docs/agent-sandbox.md.

En segundo plano, el pipeline recorre siete etapas:

1. Build: Compila el objetivo en una imagen Docker con ASAN (el detector de errores de memoria para C y C++). El pipeline construye esta imagen automáticamente en la primera ejecución usando el Dockerfile del objetivo.
2. Recon: Un agente ligero lee el código fuente dentro de un contenedor aislado de red y propone una partición, es decir, "aquí hay N subsistemas de análisis de entrada distintos que vale la pena atacar por separado", para que agentes de búsqueda paralelos exploren áreas diferentes en lugar de converger en el mismo error. Sin el flag --auto-focus, el pipeline usa la lista focus_areas del config.yaml del objetivo.
3. Find: N agentes se ejecutan en paralelo, cada uno en su propio contenedor aislado. Cada agente lee el código fuente, crea entradas malformadas y ejecuta el binario ASAN hasta que una entrada determinada produce un fallo 3 de cada 3 veces.
4. Verify: Un agente de calificación independiente reproduce cada fallo en un contenedor nuevo que el agente de búsqueda no ha tocado. Lo único que cruza del agente de búsqueda al de calificación es la prueba de concepto que produjo.
5. Dedupe: Un agente juez compara los fallos verificados con los errores ya informados y decide si cada uno es un error nuevo, un mejor ejemplo de un error conocido o un duplicado para omitir.
6. Report: Un agente de informes escribe un análisis estructurado de explotabilidad por cada error único, incluyendo detalles sobre clase de primitiva, alcanzabilidad, ruta de escalada y gravedad.
7. Patch (el comando de parche separado arriba): Un agente de parche escribe una corrección propuesta, y un agente de calificación confirma que el nuevo código se compila, que la entrada de prueba de concepto original ya no falla, que la suite de pruebas del objetivo sigue pasando y que un agente de búsqueda nuevo no puede encontrar una manera de evitar la corrección.

Para más detalles, consulte docs/pipeline.md.

Paso 3 (Días 3-5): Personalizar el pipeline para su objetivo

En los Días 3-5, personalizará el harness para su propio objetivo. Primero, apuntará las habilidades del Paso 1 a su código, luego usará /customize para adaptar el pipeline a su stack. Al final de la semana, tendrá un directorio targets/<su-servicio>/ que el pipeline pueda ejecutar, validado con una única ejecución de prueba del pipeline, y listo para escalar en el Paso 4.

Aunque el pipeline de referencia está diseñado para encontrar vulnerabilidades de memoria en código C y C++, su forma es genérica. Adaptarlo a una nueva clase de vulnerabilidad o lenguaje solo implica responder las siguientes preguntas para su stack objetivo:

Antes de personalizar, apunte las habilidades del Paso 1 a su propio código. Como recordatorio, son de solo lectura y escritura, por lo que pueden ejecutarse sin sandbox.

claude

> /quickstart how do I customize this for ~/code/my-service?

> /threat-model bootstrap-then-interview ~/code/my-service
> /vuln-scan ~/code/my-service
> /triage ~/code/my-service/VULN-FINDINGS.json --repo ~/code/my-service

Luego, use los artefactos producidos por esas habilidades en la habilidad /customize, que modifica el harness para su base de código.

> /customize use ~/code/my-service/{THREAT_MODEL.md,VULN-FINDINGS.json} and ./TRIAGE.md

Cuando /customize termine, tendrá un directorio targets/my-service/ configurado. Valídelo con una ejecución de prueba del pipeline antes de escalar.

bin/vp-sandboxed run my-service --model <model-id> --runs 1

Para más detalles, consulte docs/customizing.md.

Paso 4 (Semana 2): Iniciar escaneo autónomo, triaje y parcheo

En la Semana 2, usará el pipeline que personalizó en el Paso 3 en sus propios objetivos, agregando un bucle externo al bucle interno del pipeline: ejecutar múltiples escaneos del pipeline, triar los hallazgos de todas esas ejecuciones, parchear según la priorización y repetir.

# Escanear - ejecutar una ola de ejecuciones paralelas contra su objetivo
bin/vp-sandboxed run my-service --model <model-id> --runs 5 --parallel --stream --auto-focus

# Triaje - deduplicar y clasificar cada hallazgo en todas las olas usando su modelo de amenaza
> /triage results/my-service/ --repo ~/code/my-service --auto --votes 5

# Parche - generar y validar correcciones, comenzando por lo que el triaje clasificó más alto
> /patch results/my-service/<timestamp>/ --model <model-id>

⚠️ Siga las mismas pautas de sandboxing que en Paso 2

Una ejecución de pipeline determinada ya verifica y deduplica sus propios hallazgos. /triage funciona en múltiples ejecuciones de pipeline. Cuando se apunta al directorio results/, colapsa duplicados en todas las ejecuciones (y cualquier hallazgo estático de /vuln-scan si está presente), recalibra las calificaciones de gravedad contra su modelo de amenaza e intenta enrutar cada hallazgo al propietario del componente.

Cuando sea posible, parchear los hallazgos rápidamente ayuda a mantener el bucle externo lo más productivo posible. Cuando los hallazgos se corrigen, el modelo no puede reencontrarlos, y en su lugar revelará problemas nuevos, típicamente más profundos. A medida que ejecute más olas de pipeline, es probable que el número de hallazgos disminuya, pero la complejidad probablemente aumente. Si no es posible un parcheo rápido, incluso solo registrar hallazgos previos en known_bugs del objetivo puede ayudar a dirigir futuras ejecuciones hacia errores más nuevos.

El triaje y parcheo autónomos siguen siendo problemas abiertos, y este harness de referencia no los resuelve completamente. Las estrategias de verificación en /patch ayudan a elevar el estándar, pero la gravedad y la priorización son, en última instancia, juicios sobre su entorno, y los parches verificados no siempre son integrables río arriba. Muchos socios han reportado estos pasos como sus cuellos de botella actuales, y debería presupuestar tiempo real de ingeniería para ellos.

Para más detalles, consulte docs/triage.md y docs/patching.md.

Perspectivas Futuras

Después de la aceleración inicial, los equipos con los que hemos trabajado han tendido a invertir en algunas direcciones:

1. Revisar todos sus repositorios internos y dependencias clave de código abierto, clasificando cuáles son los más importantes de escanear (por ejemplo, según su exposición, historial de CVEs, criticidad comercial), luego trabajar en escanear la lista en orden de prioridad.
2. Configurar infraestructura personalizada para escaneo para mover los escaneos fuera de portátiles o máquinas virtuales puntuales. Los equipos más exitosos resisten la tentación de construir la plataforma de escaneo perfecta antes de escalar.
3. Incorporar escaneos en su SDLC. Algunos equipos han configurado escaneos recurrentes (por ejemplo, diarios, semanales) o han agregado escaneos en sus pipelines de CI.
4. Probar y experimentar con los modelos para encontrar lo que mejor funciona para ellos.