Playbook de Agentes Seguros

Un playbook de seguridad de código abierto para agentes de IA. Procedimientos estructurados basados en OWASP que permiten a los agentes realizar tareas de ingeniería de seguridad, desde revisiones de código hasta auditorías de seguridad de agentes de IA.

Tabla de Contenidos

• ¿Por qué usar esto?
• Qué es esto
• Inicio Rápido
• Catálogo de Habilidades
• Agentes
• Ejemplo de Salida
• Plays
• Arquitectura
• Fundación OWASP
• Proyectos Relacionados
• Contribuciones

¿Por qué usar esto?

Sin un playbook, pedirle a un agente de IA que "revise mi código por seguridad" te da una lista de verificación superficial. Con estos plays, el agente sigue un procedimiento estructurado basado en OWASP, probando sistemáticamente cada clase de vulnerabilidad, generando hallazgos con mapeos CWE, referencias cruzadas OpenCRE, fragmentos de evidencia y código de remediación específico.

• Metodología consistente — Cada evaluación sigue un procedimiento documentado, no instrucciones ad-hoc. Los resultados son reproducibles entre ejecuciones y revisores.
• Salida estructurada y procesable — Los hallazgos incluyen severidad, CWE, evidencia y pasos de remediación con ejemplos de código. Sin advertencias vagas.
• Trazabilidad entre estándares — Los hallazgos enlazan a CWE, ASVS, WSTG y NIST 800-53 a través de OpenCRE para mapeo de cumplimiento.
• 17 habilidades de seguridad — Desde escaneo de CVE en dependencias hasta pruebas de inyección de prompts y modelado de amenazas multi-agente. Instálalo como plugin de Claude Code o úsalo de forma independiente.
• Funciona más allá de Claude Code — Las habilidades son plugins de Claude Code; los plays son procedimientos independientes que cualquier agente de IA puede seguir.

Qué es esto

Esto no es un framework ni una biblioteca. No hay código que importar.

Cada play es un procedimiento de seguridad paso a paso con listas de verificación, criterios de decisión y plantillas de salida. Un agente de IA sigue el procedimiento para producir hallazgos consistentes y basados en evidencia. Piénsalo como el playbook de un analista SOC, pero escrito para que lo ejecuten agentes de IA.

Inicio Rápido

Con Claude Code (recomendado):

Paso 1 — Registra el marketplace de plugins:

/plugin marketplace add OWASP/secure-agent-playbook

Paso 2 — Instala un conjunto de habilidades:

/plugin install code-security-skills@agent-security-playbook
/plugin install ai-security-skills@agent-security-playbook

Paso 3 — Usa las habilidades mencionando la tarea en la conversación:

"Revisa este código en busca de problemas de seguridad"
"Escanea mis dependencias en busca de CVE"
"Audita esta configuración de servidor MCP"
"Prueba este chatbot contra inyección de prompts"

Claude activará automáticamente la habilidad relevante según el contexto. Consulta Catálogo de Habilidades para todas las habilidades disponibles y Ejemplo de Salida para ver cómo se ven los resultados.

Plugin para la organización — Para administradores de organizaciones de Claude que instalan mediante Organization Plugins:

1. Ve a la última versión
2. Descarga secure-agent-playbook.zip de los activos de la versión
3. Sube el zip en Configuración de la organización > Plugins > Añadir plugin

Nota: No uses el botón "Download ZIP" de GitHub — anida archivos en un subdirectorio que el validador de plugins rechaza. Usa siempre el zip de los activos de la versión.

Desarrollo local — Para probar desde un clon local en lugar de GitHub:

/plugin marketplace add /path/to/agent-security-playbook
/plugin install code-security-skills@agent-security-playbook
/plugin install ai-security-skills@agent-security-playbook

Sin Claude Code:

Consulta los plays directamente como procedimientos para cualquier agente de IA o uso manual:

• Apunta tu agente a un play: "Sigue el procedimiento en plugins/ai-security-skills/plays/agent-security-audit.md"
• O usa los plays como listas de verificación para revisiones de seguridad manuales

Catálogo de Habilidades

Seguridad de Código e Infraestructura (code-security-skills)

Seguridad de IA y Agentes (ai-security-skills)

Agentes

Los agentes son especialistas de seguridad autónomos que invocan habilidades y producen informes estructurados. Cada agente tiene un prompt de sistema enfocado, acceso a herramientas limitado y habilidades precargadas. Úsalos individualmente o como equipo coordinado.

Uso independiente — invoca cualquier agente directamente:

"Usa code-security-reviewer para revisar src/"
"Usa dependency-auditor para escanear este proyecto"

Evaluación en equipo — con equipos de agentes habilitados, el líder del equipo despacha especialistas en paralelo y consolida los hallazgos en un solo informe:

"Ejecuta una evaluación de seguridad completa de este proyecto"

El líder del equipo delimita el objetivo, despacha especialistas relevantes (saltándose aquellos cuyo enfoque no está presente), deduplica hallazgos, identifica cadenas de riesgo entre dominios y produce un informe unificado usando templates/report.md.

Los equipos de agentes requieren CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Consulta la documentación de Claude Code para la configuración. Los agentes individuales funcionan sin esta bandera.

Ejemplo de Salida

Ejecutar "Revisa src/auth/ en busca de problemas de seguridad" en un código base Node.js/Express produce hallazgos como estos:

Security Code Review — src/auth/
Scope: Node.js/Express, server-side, processes user credentials
Findings: CRITICAL 1 | HIGH 2 | MEDIUM 1 | LOW 0

[CRÍTICO] Inyección SQL en Búsqueda de Usuario

• CWE: CWE-89
• OpenCRE: CRE-764-507 — Prevención de Inyección
• Ref. OWASP: A03:2021 Injection
• Ubicación: src/auth/login.js:42
• Impacto: El atacante puede extraer toda la tabla de usuarios, omitir la autenticación o ejecutar SQL arbitrario mediante el parámetro id manipulado
• Evidencia:
  root@kitploit:~

  // src/auth/login.js:42
  const user = await db.query("SELECT * FROM users WHERE id=" + req.params.id);
  

• Remediación: Usa consultas parametrizadas:
  root@kitploit:~

  const user = await db.query("SELECT * FROM users WHERE id = $1", [req.params.id]);
  

• Confianza: ALTA

Cada habilidad produce hallazgos estructurados con severidad, CWE, evidencia y código de remediación. Consulta examples/ para informes de evaluación de muestra completos.

Plays

Plays de Seguridad de IA/Agentes

El diferenciador: procedimientos de seguridad diseñados específicamente para la era de los agentes de IA. Incluidos dentro del plugin ai-security-skills.

Plays de Análisis de Código y Dependencias

Valor práctico inmediato para cualquier código base. Incluidos dentro del plugin code-security-skills.

Planificados

• Nivel 2: Modelado de amenazas, verificación ASVS, endurecimiento de infraestructura
• Nivel 3: Lista de verificación de pruebas WSTG, orquestación DAST, mapeo de superficie de ataque
• Nivel 5: Evaluación de madurez SAMM, mapeo de cumplimiento, informes agregados

Arquitectura

Diseño de tres capas: cada capa vive dentro de la carpeta fuente del plugin para que la instalación del marketplace incluya todo lo que las habilidades necesitan:

• plugins/<name>/agents/ — Especialistas de seguridad autónomos con prompts de sistema enfocados, ubicados dentro de cada plugin. Cada agente invoca una o más habilidades, opera en un contexto aislado y produce informes estructurados. Puede trabajar solo o como un equipo coordinado.
• plugins/<name>/skills/ — Archivos SKILL.md autocontenidos que siguen la especificación Agent Skills. Distribuidos a través de plugins/code-security-skills/ y plugins/ai-security-skills/, registrados en el marketplace mediante .claude-plugin/marketplace.json. Cada habilidad resume un procedimiento y referencia su play correspondiente dentro del mismo plugin.
• plugins/<name>/plays/ — Procedimientos de referencia completos con listas de verificación detalladas, tablas, criterios de decisión y ejemplos. Las habilidades hacen referencia a estos para una cobertura exhaustiva.
• plugins/<name>/templates/ y plugins/<name>/data/ — Plantillas de salida (finding.md, ) y conjuntos de datos de referencia OWASP (FIASSE v1.0.4, ASVS v5.0, prompts de código seguro) que las habilidades cargan en tiempo de ejecución.

Los agentes orquestan, las habilidades ejecutan, los plays proporcionan el procedimiento completo. Los contribuyentes editan los plays. Esto significa que el playbook funciona con cualquier agente de IA (solo apúntalo a un play), mientras que los usuarios de Claude Code obtienen instalación basada en plugins con agentes y habilidades.

Fundación OWASP

Todos los plays hacen referencia a estándares y conjuntos de datos de OWASP:

• OWASP Top 10 — Riesgos en aplicaciones web
• OWASP API Security Top 10 — Riesgos específicos de API
• OWASP Top 10 para Aplicaciones LLM — Riesgos de IA/LLM
• Iniciativa de Seguridad Agentica de OWASP — Riesgos de agentes autónomos (Top 10 para Aplicaciones Agenticas)
• OWASP ASVS — Requisitos de verificación de seguridad
• OWASP MASVS — Estándar de Verificación de Seguridad de Aplicaciones Móviles
• OWASP AISVS — Estándar de Verificación de Seguridad de IA
• OWASP WSTG — Metodología de pruebas
• OWASP SAMM — Modelo de madurez de programas de seguridad
• OWASP Cheat Sheet Series — Guía de seguridad para desarrolladores
• OWASP FIASSE — Marco de Ingeniería Inherentemente Adaptativa y Asegurable (v1.0.4)

Proyectos Relacionados

Contribuciones

Consulta CONTRIBUTING.md para obtener pautas detalladas.

Los nuevos plays deben:

• Resolver una tarea de seguridad bien definida
• Incluir condiciones de activación claras (¿cuándo debería ejecutarse este play?)
• Seguir un procedimiento estructurado con puntos de control
• Producir hallazgos utilizando el formato templates/finding.md dentro del plugin
• Hacer referencia a estándares OWASP cuando corresponda
• Preferir herramientas existentes (semgrep, trivy, osv-scanner, trufflehog) en lugar de reimplementar detección
• Vivir dentro de la carpeta plays/ del plugin correspondiente para que se incluyan en la instalación del marketplace

Licencia

Licenciado bajo Creative Commons Attribution 4.0 International (CC-BY-4.0). Consulta THIRD_PARTY_NOTICES.md para la atribución del contenido de proyectos upstream de OWASP.