Capítulo 4: Tu Primera Auditoría con Shannon

Este capítulo guía el flujo completo de una auditoría real con Shannon: preparar el entorno, lanzar el análisis, monitorear el progreso y leer el reporte final. Usaremos como ejemplo hipotético una aplicación web de gestión de proyectos con backend Node.js y base de datos PostgreSQL.

Preparación del entorno de auditoría

Antes de ejecutar Shannon, asegúrate de que:

1. La aplicación target está corriendo en un entorno de staging o desarrollo (nunca producción)
2. Tienes el repositorio clonado localmente
3. Las credenciales de prueba existen en la base de datos del entorno de staging
4. Docker está corriendo

# Verificar estado antes de comenzar
docker ps                          # Docker corriendo
npx @keygraph/shannon status       # Shannon configurado
curl -s https://staging.app.com    # App accesible

El comando start

El comando principal de Shannon es start. Sus parámetros más importantes:

npx @keygraph/shannon start \
  -u https://staging.miapp.com \      # URL de la aplicación target
  -r /home/dev/proyectos/miapp \      # Ruta al repositorio local
  -c ./shannon-config.yaml \          # (Opcional) configuración con credenciales
  -w auditoria-sprint-23              # (Opcional) nombre del workspace

Parámetro	Descripción	Requerido
-u / --url	URL base de la aplicación	Sí
-r / --repo	Ruta al repositorio con el código fuente	Sí
-c / --config	Archivo YAML con autenticación y contexto	No
-w / --workspace	Nombre del workspace para persistencia	No

Ejemplo de configuración YAML completa

Para una aplicación real, necesitarás un archivo de configuración que describe el entorno y provee credenciales:

# shannon-config.yaml

# Contexto de la aplicación (muy importante — guía la estrategia de los agentes)
description: |
  Plataforma SaaS multi-tenant para gestión de proyectos.
  Stack: Node.js 20 + Express + Prisma ORM + PostgreSQL 15.
  Autenticación: JWT con refresh tokens, TOTP opcional.
  Roles: owner, admin, member, viewer.
  Tenants completamente aislados por tenant_id en todas las queries.
  API REST documentada en /api/v1/docs (OpenAPI 3.0).
  Panel de admin en /admin (solo rol owner).

# Configuración de autenticación
authentication:
  login_type: form
  login_url: "https://staging.miapp.com/auth/login"
  credentials:
    username: "[email protected]"
    password: "PentestSecure!2026"
    # Descomentar si la cuenta tiene 2FA habilitado:
    # totp_secret: "JBSWY3DPEHPK3PXP"

# Credenciales adicionales para pruebas de autorización cruzada
# (usuarios en diferentes tenants o con diferentes roles)
additional_users:
  - username: "[email protected]"
    password: "TenantB!2026"
    role: "member"
  - username: "[email protected]"
    password: "ViewerOnly!2026"
    role: "viewer"

El campo description es más importante de lo que parece. Los agentes de Shannon lo leen para entender el contexto de negocio: si saben que la aplicación es multi-tenant, el agente de autorización buscará activamente IDOR cross-tenant. Si saben el stack tecnológico, los agentes de inyección prioriza payloads específicos para PostgreSQL y Prisma.

Lanzar la auditoría

Con todo preparado:

npx @keygraph/shannon start \
  -u https://staging.miapp.com \
  -r ~/proyectos/miapp \
  -c ./shannon-config.yaml \
  -w auditoria-v1

# Output inicial:
# [13:00:00] Shannon v0.8.1
# [13:00:01] Workspace: auditoria-v1
# [13:00:01] Target: https://staging.miapp.com
# [13:00:01] Repository: ~/proyectos/miapp (47,293 lines of code)
# [13:00:02] Starting Phase 1: Pre-Reconnaissance...

Monitorear el progreso en tiempo real

Abre una segunda terminal para seguir los logs:

npx @keygraph/shannon logs auditoria-v1

# Output en tiempo real:
# [13:00:05] Phase1/CodeAnalyzer: Parsing 234 TypeScript files...
# [13:00:12] Phase1/CodeAnalyzer: Found 67 API endpoints
# [13:00:12] Phase1/CodeAnalyzer: Identified 12 potential injection points
# [13:00:12] Phase1/CodeAnalyzer: Found 3 hardcoded connection strings
# [13:00:08] Phase1/ExternalScanner: nmap complete - ports 80,443,5432 open
# [13:00:09] Phase1/ExternalScanner: WARNING: PostgreSQL port 5432 exposed to internet
# [13:01:30] Phase2/Recon: Browser launched (Chromium headless)
# [13:01:35] Phase2/Recon: Login form found at /auth/login
# [13:01:40] Phase2/Recon: Login successful (session established)
# [13:01:55] Phase2/Recon: Navigating 67 endpoints...
# [13:04:12] Phase2/Recon: Surface map complete (61 accessible endpoints)
# [13:04:13] Phase3: Starting parallel vulnerability analysis...
# [13:04:13] Phase3/InjectionAgent: Analyzing 12 injection candidates...
# [13:04:13] Phase3/XSSAgent: Analyzing 8 user-input fields...
# [13:04:13] Phase3/AuthAgent: Analyzing JWT implementation...
# [13:04:13] Phase3/AuthzAgent: Analyzing 23 authorization checks...
# [13:04:13] Phase3/SSRFAgent: Analyzing HTTP client calls...

Señales de alerta en los logs

Presta atención a estos patrones en los logs que indican hallazgos prometedores:

# Inyección probable detectada en código
Phase3/InjectionAgent: HIGH CONFIDENCE - Direct parameter interpolation at src/api/projects.ts:156

# SSRF potencial
Phase3/SSRFAgent: SSRF candidate - User-controlled URL at src/services/webhook.ts:89

# Problema de autorización
Phase3/AuthzAgent: Missing ownership check at GET /api/projects/:id (no tenant verification)

La fase de explotación en detalle

Cuando comienza la Fase 4, Shannon intenta activamente explotar cada hipótesis:

# [13:15:00] Phase4: Starting exploitation of 18 hypotheses...

# Intento de SQL injection en el endpoint de búsqueda
# [13:15:02] Phase4/Exploit: Testing SQLi on GET /api/projects/search?q=
# [13:15:03] Phase4/Exploit: Payload: ' OR '1'='1 -> Response: 200 (all projects returned)
# [13:15:03] Phase4/Exploit: CONFIRMED: SQL Injection on /api/projects/search?q= [CRITICAL]
# [13:15:03] Phase4/Exploit: Evidence saved: screenshots/sqli-search-001.png

# Intento de IDOR cross-tenant
# [13:15:15] Phase4/Exploit: Testing IDOR - Accessing tenant-B project from tenant-A session
# [13:15:16] Phase4/Exploit: GET /api/projects/proj_tenant_b_123 -> 200 OK (data leaked!)
# [13:15:16] Phase4/Exploit: CONFIRMED: IDOR cross-tenant on /api/projects/:id [HIGH]

# Hipótesis que no se confirma
# [13:16:40] Phase4/Exploit: Testing XSS on /search - WAF blocking payloads
# [13:16:55] Phase4/Exploit: Trying 12 WAF bypass variants...
# [13:17:20] Phase4/Exploit: FAILED: XSS on /search not exploitable (WAF effective)

Tiempos esperados por fase

gantt
    title Ejemplo: auditoría de app mediana (~85 minutos)
    dateFormat mm
    section Fase 1
    Análisis de código       :done, 00, 12m
    Reconocimiento externo   :done, 00, 9m
    section Fase 2
    Mapeo de superficie      :done, 12, 18m
    section Fase 3
    5 agentes en paralelo    :active, 30, 15m
    section Fase 4
    Explotación              :crit, 45, 30m
    section Fase 5
    Generación de reporte    :50, 70, 15m

Para aplicaciones más grandes (100k+ líneas de código, 200+ endpoints), la auditoría puede extenderse a 2-3 horas y el costo puede superar los $50 USD.

Workspaces y reanudación

Los workspaces son la feature de productividad más importante de Shannon. Si la auditoría se interrumpe, relanzar el mismo comando reanuda desde el último checkpoint:

# Primera ejecución - se interrumpió a mitad de la Fase 4
npx @keygraph/shannon start -u https://staging.miapp.com -r ~/proyectos/miapp -w auditoria-v1
# Ctrl+C a los 45 minutos

# Reanudar - detecta el workspace existente
npx @keygraph/shannon start -u https://staging.miapp.com -r ~/proyectos/miapp -w auditoria-v1
# [16:00:00] Resuming workspace: auditoria-v1
# [16:00:00] Phase 1: COMPLETE (skipping)
# [16:00:00] Phase 2: COMPLETE (skipping)
# [16:00:00] Phase 3: COMPLETE (skipping)
# [16:00:00] Phase 4: PARTIAL (14/18 hypotheses tested, resuming from #15)

Esto es especialmente valioso cuando el timeout de red interrumpe una auditoría larga o cuando necesitas pausar y retomar el trabajo.

Listar workspaces existentes

npx @keygraph/shannon status

# Output:
# Active workspaces:
# - auditoria-v1     [in progress]  Phase 4/5  Started: 2026-04-20 13:00
# - auditoria-feb    [completed]    Report ready  Started: 2026-02-15 09:00
# - test-login-flow  [failed]       Phase 2/5  Error: login timeout

Leer el reporte final

Al completar la Fase 5, Shannon genera el reporte en el directorio del workspace:

# Ver dónde está el reporte
ls ~/.shannon/workspaces/auditoria-v1/reports/

# pentest-report-2026-04-20.md
# pentest-report-2026-04-20.html
# evidence/
#   sqli-search-001.png
#   idor-project-001.png
#   ...

Estructura del reporte

# Shannon Security Report
**Target**: https://staging.miapp.com
**Date**: 2026-04-20
**Duration**: 85 minutes

## Executive Summary
- 🔴 Critical: 1 (SQL Injection)
- 🟠 High: 2 (IDOR cross-tenant, Auth bypass)
- 🟡 Medium: 1 (Reflected XSS)
- 🟢 Low: 3

## Findings

### [CRITICAL] SQL Injection en /api/projects/search

**Vector**: GET /api/projects/search?q=' OR '1'='1--
**Evidence**: [Screenshot] All 2,341 projects from all tenants returned
**Proof of Concept**:
curl 'https://staging.miapp.com/api/projects/search?q=%27%20OR%20%271%27%3D%271--' \
  -H 'Authorization: Bearer eyJ...'
**Remediation**: Usar Prisma parameterized queries. Reemplazar interpolación
  directa en projects.service.ts:156 con `where: { name: { contains: q } }`

Flujo de validación post-reporte

Shannon advierte explícitamente que los reportes generados por IA requieren verificación humana. El flujo recomendado después de recibir el reporte:

flowchart LR
    R["Reporte Shannon"] --> V["Verificación manual\nde cada hallazgo"]
    V --> C1{"¿Confirmado?"}
    C1 -->|Sí| FIX["Planificar remediación"]
    C1 -->|No| DISC["Descartar / investigar más"]
    FIX --> RETEST["Retest con Shannon\nen mismo workspace"]
    RETEST --> CLEAN{"¿Limpio?"}
    CLEAN -->|Sí| CLOSE["Cerrar hallazgo"]
    CLEAN -->|No| FIX

Errores comunes y soluciones

Error: Docker no disponible

# Error: Cannot connect to Docker daemon
# Solución:
sudo systemctl start docker
# O en macOS: iniciar Docker Desktop

Error: Timeout en el login

# Error: Phase 2 failed - Login timeout after 30s
# Causas comunes:
# 1. URL de login incorrecta en el YAML
# 2. Credenciales inválidas en el entorno de staging
# 3. La app tiene captcha (no soportado sin configuración adicional)

# Verificar manualmente:
curl -X POST https://staging.miapp.com/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"[email protected]","password":"PentestSecure!2026"}'

Error: API key inválida

# Error: Anthropic API authentication failed
# Verificar:
echo $ANTHROPIC_API_KEY
# La key debe empezar con: sk-ant-api03-

Workspace corrupto

# Si un workspace queda en estado inconsistente:
npx @keygraph/shannon workspace delete auditoria-v1
# Luego relanzar desde cero con el mismo nombre

Checklist antes de cada auditoría

• App corriendo en staging (no producción)
• docker ps muestra Docker activo
• ANTHROPIC_API_KEY exportada
• shannon-config.yaml creado con credenciales válidas de staging
• Credenciales de prueba funcionan manualmente (curl o navegador)
• Nombre de workspace elegido y anotado
• Terminal secundaria lista para shannon logs
• Presupuesto de ~$50 USD en la cuenta de Anthropic

Siguiente paso

Ahora que sabes ejecutar una auditoría completa, el siguiente capítulo profundiza en las cuatro categorías de vulnerabilidades que Shannon detecta y cómo funciona el proceso de explotación para cada una.

→ Capítulo 5: Vulnerabilidades OWASP que Detecta Shannon