← Volver al listado de tecnologías ← Índice de Shannon

Capítulo 3: Arquitectura y Sistema de Agentes de Shannon

20 de abril de 2026 Por: Artiko

shannonarquitecturaagentesmultiagenteclaude-sdkplaywrightnmap

Capítulo 3: Arquitectura y Sistema de Agentes de Shannon

Shannon no es un escáner monolítico. Es un sistema multiagente donde diferentes agentes especializados trabajan en paralelo, cada uno enfocado en una categoría específica de vulnerabilidades o en una tarea de infraestructura del pentest. Entender esta arquitectura te permite predecir el comportamiento de Shannon, depurar problemas y aprovechar mejor sus capacidades.

Visión general de las 5 fases

El flujo completo de una auditoría Shannon se divide en cinco fases secuenciales, aunque dentro de cada fase varios agentes pueden ejecutarse concurrentemente:

flowchart TD
    F1["Fase 1\nPre-Reconocimiento\nAnálisis de código fuente +\nescaneo externo (nmap, subfinder)"]
    F2["Fase 2\nReconocimiento\nMapeo de superficie de ataque\nmediante automatización de navegador"]
    F3["Fase 3\nAnálisis de Vulnerabilidades\n5 agentes paralelos generan\nhipótesis de explotación"]
    F4["Fase 4\nExplotación\nValidación con Playwright +\nherramientas CLI"]
    F5["Fase 5\nReporte\nSíntesis de evidencias\nen formato pentest profesional"]

    F1 --> F2
    F2 --> F3
    F3 --> F4
    F4 --> F5

Cada fase persiste su estado en el workspace mediante commits git. Si la auditoría se interrumpe (por ejemplo, por un timeout de red), puede reanudarse desde el punto exacto de interrupción.

Fase 1: Pre-Reconocimiento

Esta fase combina dos actividades en paralelo: análisis del código fuente y reconocimiento externo.

Análisis de código fuente

Un agente lee el repositorio completo para construir un mapa de la arquitectura de la aplicación:

Endpoints y rutas HTTP — identifica todos los controladores, handlers y rutas definidas
Modelos de datos — entiende las entidades y sus relaciones
Mecanismos de autenticación — detecta middleware de auth, JWT, sesiones
Puntos de entrada de datos externos — parámetros de query, body, headers, cookies
Llamadas a servicios externos — URLs hardcodeadas, llamadas HTTP internas, SSRF potencial
Stack tecnológico — frameworks, ORMs, librerías de seguridad usadas

Este análisis de código fuente es lo que distingue fundamentalmente a Shannon de un escáner de caja negra. Un escáner externo solo ve los endpoints que puede descubrir mediante crawling. Shannon sabe de todos los endpoints desde el primer minuto.

Reconocimiento externo

Simultáneamente, otro agente ejecuta herramientas de reconocimiento externo:

graph LR
    EXT["Reconocimiento Externo"] --> NMAP["Nmap\nPuertos y servicios"]
    EXT --> SUB["Subfinder\nSubdominios"]
    EXT --> WW["WhatWeb\nFingerprinting de tecnologías"]
    EXT --> SCHEMA["Schemathesis\nFuzzing de APIs REST/GraphQL"]

Nmap escanea puertos abiertos, detecta servicios y versiones, identificando servicios expuestos que podrían ser vectores de ataque (Elasticsearch abierto, Redis sin auth, servicios de admin expuestos).

Subfinder enumera subdominios del objetivo para encontrar entornos de staging, APIs internas o paneles de administración accesibles públicamente.

WhatWeb hace fingerprinting de la aplicación web: versión del servidor, frameworks utilizados, headers de seguridad presentes o ausentes.

Schemathesis toma la especificación OpenAPI o GraphQL schema de la aplicación (si están disponibles) y genera casos de prueba automáticamente para fuzzing inicial.

Fase 2: Reconocimiento

Con el mapa construido en la fase anterior, un agente utiliza Playwright (el framework de automatización de navegador) para validar los hallazgos:

Navega la aplicación real como lo haría un usuario
Valida que los endpoints identificados en el código realmente existen y son accesibles
Documenta la arquitectura de autorización real (qué endpoints requieren autenticación, qué roles existen)
Identifica componentes dinámicos que no son visibles en el código estático (formularios generados dinámicamente, flujos de wizard multi-paso)
Si hay credenciales configuradas, completa el flujo de login incluyendo TOTP

Esta validación es crítica porque el código fuente puede tener rutas comentadas, condicionadas por feature flags, o deshabilitadas en el entorno de staging. El agente de reconocimiento reconcilia el análisis estático con la realidad del runtime.

Fase 3: Análisis de Vulnerabilidades (5 agentes en paralelo)

Este es el corazón del sistema multiagente. Cinco agentes especializados trabajan simultáneamente, cada uno buscando una categoría de vulnerabilidades:

graph TD
    MAP["Mapa de superficie de ataque\n(resultado Fase 2)"] --> A1
    MAP --> A2
    MAP --> A3
    MAP --> A4
    MAP --> A5

    A1["Agente de Inyección\nSQL, NoSQL, Command,\nXXE, SSTI"]
    A2["Agente XSS\nReflected, Stored,\nDOM-based, Template"]
    A3["Agente SSRF\nInternal, External,\nBlind, OOB"]
    A4["Agente de Autenticación\nBrute force, Session fixation,\nJWT weak signing, Token leakage"]
    A5["Agente de Autorización\nIDOR, Privilege escalation,\nMissing checks, BOLA"]

    A1 --> HYP["Hipótesis de Explotación"]
    A2 --> HYP
    A3 --> HYP
    A4 --> HYP
    A5 --> HYP

Cada agente recibe el mapa completo de la aplicación y genera una lista priorizada de hipótesis de explotación: “este endpoint probablemente es vulnerable a SQL injection porque concatena directamente el parámetro id en la query sin sanitización”.

Las hipótesis incluyen:

El vector de ataque específico (qué endpoint, qué parámetro)
El payload sugerido basado en el stack tecnológico identificado
La evidencia del código fuente que sustenta la hipótesis
La severidad estimada si la hipótesis se confirma

Fase 4: Explotación

Los agentes de explotación toman las hipótesis de la fase anterior e intentan confirmarlas contra la aplicación real. Esta es la fase donde Shannon realmente se diferencia: si no logra ejecutar el exploit, la hipótesis no llega al reporte.

sequenceDiagram
    participant A as Agente de Explotación
    participant P as Playwright Browser
    participant App as Aplicación Target
    participant W as Workspace (git)

    A->>P: Navegar a endpoint vulnerable
    P->>App: GET /users?id=1' OR '1'='1
    App-->>P: Respuesta HTTP (datos de todos los usuarios)
    P-->>A: Captura de pantalla + response body
    A->>W: Commit: SQLi confirmado en /users?id= (evidencia adjunta)
    A->>A: Generar PoC reproducible

Para cada hipótesis, el agente:

Abre el navegador con Playwright y navega al endpoint
Inyecta el payload específico
Analiza la respuesta para confirmar el éxito del exploit
Captura evidencia (screenshot, response body, cookies exfiltradas, etc.)
Genera un PoC reproducible que un humano puede ejecutar manualmente

Si el exploit falla, el agente intenta variantes del payload (diferentes encodings, bypass de WAF, variaciones del vector). Si ninguna variante funciona, la hipótesis se descarta y no aparece en el reporte final.

Herramientas disponibles en la fase de explotación

Los agentes tienen acceso a:

Herramienta	Uso
Playwright	Navegación, formularios, cookies, screenshots
curl / fetch	Peticiones HTTP directas con headers personalizados
SQLMap (modo no agresivo)	Confirmación de SQLi con extracción controlada
Nmap scripts	Validación de servicios específicos
Herramientas CLI del repositorio	Tests del propio proyecto como vector de explotación

Fase 5: Reporte

El agente de reporte consolida toda la evidencia y genera un documento profesional. El reporte final incluye:

Resumen ejecutivo con el número de vulnerabilidades críticas, altas, medias y bajas
Por cada vulnerabilidad confirmada:
- Descripción técnica y categoría OWASP
- Evidencia (screenshot, response, token capturado)
- PoC reproducible paso a paso
- Impacto estimado en el negocio
- Recomendación de remediación específica al stack de la aplicación
Superficie de ataque analizada — todos los endpoints revisados

Sistema de workspaces y checkpoints

Shannon usa git internamente para guardar el estado de cada auditoría:

gitGraph
    commit id: "init: workspace creado"
    commit id: "phase1: análisis código completado"
    commit id: "phase2: reconocimiento completado"
    commit id: "phase3: hipótesis generadas (23 total)"
    commit id: "phase4: SQLi confirmado en /api/users"
    commit id: "phase4: XSS almacenado confirmado en /comments"
    commit id: "phase5: reporte final generado"

Si la auditoría falla en la Fase 4 por un timeout, al relanzar Shannon con el mismo nombre de workspace, detecta automáticamente hasta qué punto llegó y reanuda desde el último checkpoint, evitando repetir el trabajo ya completado.

# Primera ejecución (puede interrumpirse)
npx @keygraph/shannon start -u https://staging.app.com -r /path/repo -w auditoria-v2

# Reanudar la misma auditoría
npx @keygraph/shannon start -u https://staging.app.com -r /path/repo -w auditoria-v2
# Shannon detecta: "Fase 4 completada al 60%, reanudando..."

Logs y monitoreo en tiempo real

Durante una auditoría puedes ver qué están haciendo los agentes en tiempo real:

# En una terminal separada
npx @keygraph/shannon logs auditoria-v2

# Output ejemplo:
# [12:34:01] Phase1/CodeAnalyzer: Identified 47 endpoints, 8 potential injection points
# [12:34:15] Phase2/Recon: Login successful (TOTP validated)
# [12:35:02] Phase3/InjectionAgent: Generated 12 SQLi hypotheses
# [12:35:02] Phase3/XSSAgent: Generated 7 XSS hypotheses
# [12:36:44] Phase4/Exploit: SQLi CONFIRMED on GET /api/products?category= (UNION-based)
# [12:37:01] Phase4/Exploit: XSS hypothesis FAILED on /search (WAF blocking)

# Ver estado general
npx @keygraph/shannon status

Procesamiento paralelo: impacto en el costo

El procesamiento paralelo de los 5 agentes en la Fase 3 y 4 acelera significativamente la auditoría, pero implica que múltiples llamadas a la API de IA ocurren simultáneamente. Esto explica el costo de ~$50 por auditoría completa:

gantt
    title Timeline de una auditoría Shannon (~80 minutos)
    dateFormat mm
    section Fase 1
    Análisis código      :00, 10m
    Reconocimiento ext.  :00, 8m
    section Fase 2
    Recon navegador      :10, 15m
    section Fase 3
    Agente Inyección     :25, 12m
    Agente XSS           :25, 10m
    Agente SSRF          :25, 11m
    Agente Auth          :25, 9m
    Agente Authz         :25, 13m
    section Fase 4
    Explotación          :38, 30m
    section Fase 5
    Reporte              :68, 12m

Implementación: Claude Agent SDK

Shannon está construido con el Claude Agent SDK de Anthropic. Cada agente es una instancia del SDK configurada con:

Herramientas específicas a su rol (Playwright para los agentes de explotación, herramientas de filesystem para el analizador de código)
Instrucciones de sistema que definen su especialidad y metodología
Contexto compartido del mapa de la aplicación construido en fases anteriores

Esta arquitectura permite que Keygraph actualice o mejore agentes individualmente sin necesidad de modificar el sistema completo.

Resumen del capítulo

Elemento	Detalle
Fases	5 (Pre-recon, Recon, Análisis, Explotación, Reporte)
Agentes especializados	13 total en Shannon Pro, 5+ en Lite
Paralelismo	Fases 3 y 4 ejecutan agentes simultáneamente
Persistencia	Workspaces con checkpoints via git
Navegador	Playwright (Chrome headless)
Herramientas externas	Nmap, Subfinder, WhatWeb, Schemathesis

Siguiente paso

Con la arquitectura clara, el siguiente capítulo guía paso a paso tu primera auditoría real, cubriendo el comando start, la configuración de autenticación y la interpretación de los logs en tiempo real.

→ Capítulo 4: Tu Primera Auditoría