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

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

20 de abril de 2026 Por: Artiko

shannonauditoríapentestworkspaceyamlautenticacióntotp

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:

La aplicación target está corriendo en un entorno de staging o desarrollo (nunca producción)
Tienes el repositorio clonado localmente
Las credenciales de prueba existen en la base de datos del entorno de staging
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: 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

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

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

Preparación del entorno de auditoría

El comando start

Ejemplo de configuración YAML completa

Lanzar la auditoría

Monitorear el progreso en tiempo real

Señales de alerta en los logs

La fase de explotación en detalle

Tiempos esperados por fase

Workspaces y reanudación

Listar workspaces existentes

Leer el reporte final

Estructura del reporte

Flujo de validación post-reporte

Errores comunes y soluciones

Error: Docker no disponible

Error: Timeout en el login

Error: API key inválida

Workspace corrupto

Checklist antes de cada auditoría

Siguiente paso

El comando `start`