Crea un agente de escaneo de seguridad para Claude Code basado en OWASP
El escaneo terminó a las 11:47 PM de un jueves, y me quedé mirando el terminal como si acabara de insultar toda mi base de código. Treinta y siete vulnerabilidades. Nueve críticas. Un puntaje de riesgo de 245 parpadeando en la parte superior del informe, en ese tono específico de rojo que significa “no envíes esto a producción”. ¿Lo peor? No era el código de un cliente. Era una aplicación deliberadamente vulnerable para tomar notas que había construido como blanco de pruebas para el agente de escaneo de seguridad Claude Code que estuve armando durante la tarde.
Y el agente detectó todo. Hashing de contraseñas con MD5. Concatenación directa de cadenas SQL. Una ruta de control de acceso rota en la que cualquier usuario autenticado podía eliminar las notas de cualquier otro usuario adivinando un ID. Incluso un sumidero de ejecución de código arbitrario que había enterrado a tres archivos de profundidad porque, sinceramente, quería ver si lo encontraba. Lo hizo. En treinta segundos.
En ese momento dejé de pensar en esto como un experimento de fin de semana y empecé a verlo como aquello que debí haber construido seis meses atrás.
Dirijo una marca de ciberseguridad —xCyberSecurity— y buena parte de ese trabajo consiste en realizar auditorías al estilo OWASP en aplicaciones web. La auditoría en sí requiere mucho tiempo humano y especializado. Leer código, rastrear el flujo de datos, revisar versiones de dependencias, cruzar información con CVEs, redactar hallazgos con su gravedad y posibles mitigaciones. Un ingeniero senior realiza ese trabajo. Despacio. Con cuidado. Por hora facturable.
Un agente Claude Code no puede reemplazar a ese ingeniero. Pero sí puede hacer la primera pasada. Puede detectar los problemas evidentes incluso antes de que un humano abra el archivo. Y como Claude Code incorporó el patrón Skill + sub-agente, todo el sistema es modular: una pieza reutilizable que puedo compartir entre proyectos, encadenar con otros agentes, o incorporar en un hook de pre-commit cualquier martes por la tarde.
Así es como lo construí. Y, lo que es más importante, por qué la arquitectura es fundamental.
Por qué un Solo Gran Agente No Funciona para Esto
Mi primer instinto —y probablemente el tuyo— es simplemente escribir un mega prompt para el sistema. "Eres un auditor de seguridad. Busca inyecciones SQL, control de acceso roto, cifrado débil, todo el Top 10 de OWASP, redacta un informe." Listo. A correr.
Probé primero con esa versión. Funcionaba. Más o menos. Los informes eran inconsistentes. Algunos análisis marcaban cada llamada a md5() como crítica; otros pasaban de largo. La valoración de "severidad" variaba entre ejecuciones: un escaneo llamaba “alta” a una clave API hardcodeada, el siguiente la etiquetaba como “crítica”. Peor aún, el agente no recordaba cómo debía ser un buen resultado. Cada invocación era una improvisación totalmente nueva.
El auténtico problema era estructural. Le estaba pidiendo a una ventana de contexto que retuviera cuatro cosas a la vez: el material de referencia del Top 10 de OWASP, la metodología de escaneo, el formato del reporte, y el propio código sometido a auditoría. Es demasiada carga cognitiva para meterla en un solo prompt, y Claude —incluso Opus 4.7— responde ante esa sobrecarga igual que un auditor humano tras su octava bebida energética. Se vuelve descuidado.
Las skills lo resuelven. Los subagentes también. Si los usas juntos, todo encaja de inmediato.
Si quieres el contexto más amplio de cómo encajan las skills en Claude Code, lo explico en mi guía de Skills para Agentes de Claude Code — te recomiendo leerla junto a este artículo porque el escáner que verás aquí es una aplicación práctica de esos patrones.
La arquitectura: Skill + Sub-Agente
Así es como funciona la división.
La Skill es la capa de conocimiento. Contiene el material de referencia del OWASP Top 10, la metodología de escaneo y el formato exacto del informe. Es una carpeta con un archivo SKILL.md y varios archivos markdown —uno por cada categoría OWASP— que se cargan bajo demanda. La skill no escanea nada por sí misma. Es un conjunto de instrucciones esperando a ser invocadas.
El Sub-Agente es la capa de ejecución. Es un sub-agente especializado de Claude Code con su propio prompt de sistema, su propio acceso a herramientas (Read, Glob, Grep, Bash para clones con gh, Write para informes) y las instrucciones explícitas de cargar la skill de seguridad al ejecutarse. El sub-agente es lo que invocas realmente. La skill es lo que consulta.
Esta separación importa por tres razones.
Primero, separación de responsabilidades. El conocimiento se versiona de forma independiente a la lógica de ejecución. Cuando OWASP actualizó el Top 10 en 2025 —integró SSRF en el apartado de Broken Access Control, añadió Fallos en la Cadena de Suministro de Software como nueva categoría principal e incorporó Manejo Incorrecto de Condiciones Excepcionales—, actualicé dos archivos markdown en la skill. El sub-agente no cambió. En la época de prompts monolíticos, habría tenido que reescribir todo el prompt del sistema.
Segundo, facilidad para compartir. La skill es una carpeta. Puedo comprimirla en un zip, enviarla a un compañero, subirla a un repositorio compartido o agregarla al registro de skills del equipo. El sub-agente es un único archivo markdown con frontmatter. Lo mismo. Otro miembro del equipo puede clonar ambos, conectarlos en cinco minutos y obtener resultados de escaneo idénticos a los míos.
Tercero, composabilidad. El sub-agente de scanner puede invocarse directamente —@security-scanner audita este repo— o encadenarse desde un agente coordinador de nivel superior. Tengo un agente principal que gestiona la revisión de código; cuando detecta security: en el mensaje de un commit, delega en el scanner. Ese patrón sería imposible si la seguridad residiera dentro del propio prompt del agente de revisión. Escribí sobre este tipo de transferencia en mi post sobre arquitecturas de enjambre de agentes, y el scanner es un ejemplo puro de ello.
El resto de este artículo explica la implementación real.
El SKILL.md que Puedes Copiar
La habilidad se encuentra en .claude/skills/security-vulnerability/. Aquí tienes el archivo SKILL.md: este es el esquema que realmente utilizo, ligeramente depurado:
---
name: security-vulnerability
description: Analiza una base de código o un repositorio de GitHub en busca de vulnerabilidades OWASP Top 10 2025. Úsalo cuando el usuario solicite una auditoría de seguridad, un escaneo de vulnerabilidades, una revisión OWASP o un chequeo de seguridad previo al despliegue en un directorio local o una URL de GitHub.
---
Estás realizando una auditoría de seguridad basada en las categorías OWASP Top 10 2025. Sigue exactamente el flujo de ejecución a continuación. No omitas pasos. No inventes niveles de severidad.
## Manejo de entradas
Acepta uno de dos tipos de entrada:
- Una ruta local de directorio (por ejemplo, `/Users/me/projects/app`)
- Una URL de GitHub (por ejemplo, `https://github.com/org/repo`)
Si la entrada es una URL de GitHub, clónala con:
gh repo clone <org/repo> /tmp/scan-<timestamp>
Luego, establece la ruta de trabajo en el directorio clonado.
## Flujo de Ejecución
1. **Inventariar la base de código.** Identificar lenguajes, frameworks y manifiestos de paquetes (package.json, composer.json, requirements.txt, go.mod, Gemfile, pom.xml).
2. **Cargar referencias por categoría.** Para cada categoría del OWASP Top 10 2025, leer el archivo de referencia correspondiente desde esta carpeta de la skill:
- references/A01-broken-access-control.md
- references/A02-security-misconfiguration.md
- references/A03-supply-chain-failures.md
- references/A04-injection.md
- references/A05-cryptographic-failures.md
- references/A06-insecure-design.md
- references/A07-auth-failures.md
- references/A08-data-integrity-failures.md
- references/A09-logging-alerting-failures.md
- references/A10-exceptional-conditions.md
3. **Escanear por categoría.** Para cada categoría, utilizar Grep y Read sobre la base de código empleando los patrones documentados en el archivo de referencia de esa categoría. Registrar cada hallazgo con la ruta del archivo, número de línea, fragmento de código y categoría.
4. **Verificar dependencias.** Para cada manifiesto de paquete, extraer las versiones declaradas. Marcar los paquetes con CVEs conocidos haciendo la comprobación contra OSV.dev o GitHub Advisory Database. No inventar identificadores de CVE. Si la búsqueda no es posible en el entorno actual, registrar el paquete y la versión bajo "dependencias no verificadas" en lugar de emitir un veredicto inventado.
5. **Clasificar y puntuar.** Asignar a cada hallazgo una severidad: crítica, alta, media o baja. Utilizar el criterio en references/severity-rubric.md. Calcular un puntaje de riesgo global: (crítica × 10) + (alta × 5) + (media × 2) + (baja × 1).
6. **Redactar el informe.** Guardar en `audit/YYYY-MM-DD/report.md` relativo al objetivo del escaneo. Utilizar el formato de informe siguiente.
## Formato del informe
El informe debe contener, en este orden:
1. **Resumen** — objetivo, fecha del escaneo, hallazgos totales por gravedad, puntuación de riesgo general, veredicto de aprobación/rechazo.
2. **Hallazgos por categoría** — una sección por cada categoría OWASP con hallazgos. Cada hallazgo incluye: gravedad, archivo:línea, fragmento de código, por qué es relevante, sugerencia de corrección.
3. **Riesgos de dependencias** — paquetes conocidos como vulnerables con referencias CVE y posibles rutas de actualización.
4. **Dependencias no verificadas** — paquetes señalados pero no confirmados.
5. **Prioridad de remediación** — una lista ordenada de las diez principales correcciones por gravedad y esfuerzo.
## Reglas estrictas
- Nunca inventes identificadores CVE, niveles de severidad o soluciones si no tienes plena confianza. Marca explícitamente cualquier incertidumbre.
- Nunca apliques correcciones de forma automática. El sub-agente puede proponer parches en un archivo aparte, pero modificar el código fuente requiere aprobación humana explícita.
- Si un archivo supera las 2000 líneas, léelo por fragmentos. No lo omitas.
- Cada hallazgo debe citar un archivo específico y un rango de líneas.
Eso es todo. Todo el cerebro de la habilidad. Cada archivo de referencia bajo references/ es un documento enfocado de 200 a 400 líneas: definición, patrones comunes para buscar con grep, ejemplos específicos de lenguaje y la escala de severidad para esa categoría. Puedes redactar esos archivos de referencia en una tarde si has trabajado alguna vez en seguridad.
El Subagente Que Lo Usa
El subagente reside en .claude/agents/security-scanner.md. Aquí tienes el frontmatter y la instrucción de sistema — de nuevo, la versión real que ejecuto:
---
name: security-scanner
description: Audita un directorio local o un repositorio de GitHub contra el OWASP Top 10 2025. Úsalo proactivamente cuando el usuario mencione auditoría de seguridad, escaneo de vulnerabilidades, pentest, verificación previa al despliegue o revisión OWASP.
model: opus
tools: Read, Glob, Grep, Bash, Write
---
Eres un ingeniero senior de seguridad de aplicaciones. Tu trabajo es ejecutar una auditoría exhaustiva basada en OWASP Top 10 2025 sobre una base de código objetivo y producir un informe accionable por un revisor humano.
Al ser invocado:
1. Confirma con el usuario el objetivo del escaneo si hay ambigüedad (ruta local vs URL de GitHub).
2. Carga la skill `security-vulnerability`. Sigue su flujo de ejecución exactamente.
3. Ejecuta el escaneo. Sé sistemático, no ingenioso. La cobertura es más importante que la velocidad.
4. Escribe el informe en `audit/YYYY-MM-DD/report.md` y presenta el resumen en el chat.
5. Cuando el informe esté guardado, ofrece —pero no realices— correcciones automáticas para hallazgos que sean mecánicamente seguras (por ejemplo, reemplazar `md5()` por `password_hash()`, parametrizar una consulta SQL). Espera aprobación explícita antes de modificar cualquier archivo fuente.
Reglas operativas:
- No realizas pentesting en sistemas en producción. Solo análisis estático.
- No adivinas. Si un hallazgo es incierto, márcalo como incierto en el informe.
- No eliminas ni mueves archivos.
- Registras cada llamada de herramienta. Mantén el rastro de auditoría en `audit/YYYY-MM-DD/trail.log`.
Dos archivos. Ese es todo el escáner.
Qué sucedió cuando lo ejecuté
Construí una aplicación de notas deliberadamente vulnerable como objetivo de prueba. Stack tipo Laravel, SQLite, algunas rutas, autenticación de usuario, CRUD de notas. Enterré seis tipos de vulnerabilidades a propósito y añadí un par más que olvidé que había escrito.
El escaneo tomó aproximadamente 90 segundos de principio a fin sobre una base de código de 4,000 líneas. Aquí está el resumen que produjo:
- Total de hallazgos: 37
- Críticos: 9
- Altos: 15
- Medios: 12
- Bajos: 1
- Puntaje de riesgo: 245 (crítico)
Los hallazgos críticos abarcaron A01 Control de Acceso Roto (dos rutas sin verificación de propiedad — cualquier usuario autenticado podía editar o eliminar cualquier nota adivinando el ID), A04 Inyección (tres casos de concatenación de cadenas en consultas SQL), A05 Fallos Criptográficos (hash de contraseñas con MD5 más un APP_KEY codificado en duro en un .env.example commiteado), y A06 Diseño Inseguro (un endpoint de administrador que aceptaba un parámetro cmd que iba directamente a una llamada de ejecución en shell).
El informe desglosó todo esto con rutas de archivo, números de línea, fragmentos exactos y una solución sugerida para cada hallazgo. Para los casos de inyección SQL, propuso la reescritura de consultas parametrizadas inline. Para el hash MD5, recomendó el uso de Hash::make() de Laravel y señaló la ruta de migración para los registros de contraseñas existentes.
¿Fue perfecto? No. Señaló una instrucción de logging que imprimía un correo de usuario como un problema A09, lo cual es defendible pero pareció agresivo — en la mayoría de jurisdicciones eso no se considera hallazgo. También pasó por alto una condición de carrera sutil en el endpoint de compartir notas que un revisor humano vería en unos treinta segundos. El reconocimiento estático de patrones no puede razonar sobre concurrencia, y ningún prompt va a solucionar eso.
Pero lo que detectó, lo hizo de manera impecable. Y ahora tengo un informe con sello de fecha guardado en audit/2026-04-18/ que puedo enviar a un cliente.
Integración en un Flujo Pre-Commit o de CI
El sub-agente es útil por sí solo. Pero resulta mucho más valioso cuando se ejecuta automáticamente.
Para pre-commit, tengo un hook de Git que invoca el modo headless de Claude Code solo sobre los archivos staged. Carga el sub-agente del escáner, delimita el escaneo a las rutas modificadas y falla el commit si aparece algún hallazgo crítico o alto nuevo que no estuviera en el escaneo anterior. La palabra clave aquí es “nuevo”: ejecutar un escaneo OWASP completo en cada commit sería absurdo. Un escaneo delta contra la última línea base aprobada es lo adecuado.
Para CI, sigue el mismo patrón con un wrapper diferente. Una GitHub Action se ejecuta en los pull requests, clona la rama del PR en un directorio temporal, invoca el escáner y publica el resumen como un comentario en el PR con el informe completo subido como artefacto de build. Si la puntuación de riesgo supera un umbral establecido respecto a la base branch, el check falla. El propietario del equipo puede anular esto con una etiqueta aprobada. Este flujo ya ha detectado dos actualizaciones de dependencias que introducían paquetes transitivamente vulnerables antes de llegar a main.
Ninguna de estas tareas le corresponde implementarlas al escáner; son orquestaciones alrededor del escáner. Pero ambas son triviales de integrar una vez que existen la skill y el sub-agente, porque el escáner solo lee una ruta y escribe un informe. Todo lo demás es simplemente pegamento.
Dónde Falla Esto, Honestamente
No voy a fingir que esto es un reemplazo para un pentester humano, así que seamos específicos sobre los límites.
Falsos positivos. El escáner reporta en exceso sobre ciertos patrones. Cada llamada a md5() es marcada, incluso si se usa para un propósito no relacionado con la seguridad, como la generación de huellas digitales de contenido. Cada llamada potencialmente peligrosa en un archivo de pruebas es reportada. Aprendes a clasificar los resultados, pero si tienes que entregar el informe a un cliente no técnico, tendrás que hacer esa clasificación tú mismo.
Sin razonamiento en tiempo de ejecución. El análisis estático ve lo que dice el código, no lo que ocurre cuando se ejecuta. Condiciones de carrera, ataques por temporización, fallos en la lógica de negocio que solo surgen con una secuencia específica de llamadas API: el escáner no puede detectar eso. Un pentester sí. Esto es una brecha irreemplazable.
La inteligencia sobre dependencias depende de la fuente. El escáner consulta OSV.dev y GitHub Advisories. Si un paquete tiene un CVE publicado, perfecto. Si tiene una vulnerabilidad reportada hace tres días y aún no figura en una base de datos pública, el escáner la omitirá. Los zero-days siempre serán un problema humano.
El auto-fix es una trampa. Este punto quiero recalcarlo especialmente. El subagente puede proponer correcciones. Nunca se deben aplicar sin revisión. Lo sé porque la primera versión del agente sí aplicaba correcciones, y alegremente sustituyó una llamada a md5() dentro de un flujo de verificación de contraseñas heredado sin iniciar una migración de contraseñas. El cambio rompió el login para todos los usuarios existentes en un entorno de staging. Corregir de forma estática sin considerar la migración puede convertir un hallazgo "medio" en una interrupción crítica. Siempre debe haber una persona revisando.
Seguridad en las skills. Por último —y esto me hizo reflexionar cuando leí la investigación reciente de Repello sobre la seguridad en las skills—, hay que tener presente que las skills son contexto ejecutable. Cualquier skill que instales puede leer tu sistema de archivos y ejecutar comandos de shell. Una skill maliciosa disfrazada de escáner de seguridad es un riesgo real. Yo escribo mis propias skills, audito cada skill que importo y mantengo un perímetro de confianza muy estricto. Tú también deberías hacerlo.
La parte que la mayoría pasa por alto
Lo que más repito cuando otros desarrolladores me preguntan sobre este patrón es que el scanner no es la parte valiosa. El scanner es una semana de trabajo. Cualquier ingeniero competente con Claude Code y una tarde puede construir uno.
La parte valiosa es la disciplina que te impone la división entre Skill y subagente. Al escribir el skill, en realidad estás dejando por escrito cómo se ve una buena auditoría de seguridad: las categorías, los patrones, el criterio de severidad, el formato del informe. Ese documento, guardado en .claude/skills/security-vulnerability/, es un fragmento de conocimiento institucional que antes no existía. Es más valioso que el propio agente. Porque el año que viene, cuando OWASP publique el Top 10 de 2028 y la mitad de las categorías cambien otra vez, solo actualizas los archivos de referencia. El agente sigue funcionando. El conocimiento está versionado, es compartible y no reside únicamente en la cabeza de alguien.
Esa es la verdadera lección de este desarrollo. No es “Automatizé OWASP”. La lección es que los agentes modulares te obligan a hacer explícito tu conocimiento, y el conocimiento explícito se multiplica.
Elige un repositorio esta noche. No el del cliente. Uno tuyo. Ejecuta un escaneo. Mira los hallazgos. Aprenderás más sobre tu propio código en noventa segundos que en los últimos seis meses de entregas.
Preguntas Frecuentes
¿Puede Claude Code escanear un repositorio privado de GitHub?
Sí, siempre y cuando la CLI de gh en la máquina donde corre Claude Code esté autenticada con acceso a ese repositorio. El escáner utiliza internamente gh repo clone, por lo que hereda los permisos que obtuviste con gh auth login. Para repositorios de organizaciones, asegúrate de que tu token tenga el alcance repo.
¿El escáner reemplaza herramientas como Snyk o Semgrep?
No. Las complementa. Snyk y Semgrep aplican conjuntos de reglas curadas y bases de datos de vulnerabilidades que son más autorizados que cualquier prompt de un LLM. El escáner de Claude Code aporta razonamiento: puede rastrear el flujo de datos y detectar problemas contextuales que las reglas estáticas no ven. Usa ambos. El escáner detecta fallos de diseño; Snyk identifica CVEs conocidos más rápido.
¿Cuánto cuesta ejecutar un escaneo OWASP de esta manera?
En Opus 4.7, un escaneo completo de una base de código de 4,000 líneas con la configuración Skill + sub-agente me cuesta unos pocos dólares por ejecución en uso de API. Los escaneos delta sobre archivos staged en un hook de pre-commit son mucho más económicos. Si tienes una suscripción a Claude Code con uso incluido, la mayoría de los escaneos diarios encajan dentro de ese presupuesto.
¿Puedo compartir la skill con mi equipo sin compartir mi cuenta de Claude?
Sí. La skill es solo una carpeta de archivos markdown. Haz commit de .claude/skills/security-vulnerability/ en el repositorio de tu proyecto o en un repo compartido de skills. Cada miembro del equipo con Claude Code la cargará automáticamente desde su propia cuenta. Lo mismo aplica para el archivo sub-agente en .claude/agents/.
¿Debe el escáner aplicar automáticamente las correcciones?
No, y argumentaría que nunca. Propón correcciones, escríbelas en un archivo patch separado, y exige revisión humana antes de modificar cualquier archivo fuente. Personalmente he roto un entorno de staging por confiar en que el agente aplicara un cambio de cifrado "seguro". Seguro en aislamiento, catastrófico al combinarse con el resto del flujo de autenticación. Mantén siempre al humano en el proceso.
Trabajemos Juntos
¿Buscas construir sistemas de IA, automatizar flujos de trabajo o escalar tu infraestructura tecnológica? Me encantaría ayudarte.
- Fiverr (desarrollos e integraciones a medida): fiverr.com/s/EgxYmWD
- Portafolio: mejba.me
- Ramlit Limited (soluciones empresariales): ramlit.com
- ColorPark (diseño y branding): colorpark.io
- xCyberSecurity (servicios de seguridad): xcybersecurity.io
