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

Capítulo 2: Instalación y Configuración de Shannon

20 de abril de 2026 Por: Artiko

shannoninstalacióndockeranthropicaws-bedrockvertex-aiconfiguración

Capítulo 2: Instalación y Configuración de Shannon

Shannon funciona como una herramienta CLI que orquesta un contenedor Docker donde se ejecuta todo el trabajo de análisis y explotación. Esta arquitectura garantiza el aislamiento completo del entorno de pruebas y facilita la instalación en cualquier sistema operativo.

Prerrequisitos

Antes de instalar Shannon, asegúrate de tener estos componentes en tu sistema:

Docker

Shannon ejecuta su worker dentro de un contenedor Docker. Necesitas Docker instalado y funcionando:

# Verificar que Docker está activo
docker --version
docker ps

# En Linux, asegúrate de que tu usuario puede ejecutar Docker sin sudo
sudo usermod -aG docker $USER
newgrp docker

Versión mínima recomendada: Docker 20.10+

En macOS y Windows, la forma más sencilla es instalar Docker Desktop. En Linux, usa el paquete oficial de tu distribución.

Node.js

Shannon se distribuye como un paquete npm. Necesitas Node.js 18 o superior:

# Verificar versión
node --version  # Debe ser 18+
npx --version   # Debe estar disponible

# Con nvm (recomendado)
nvm install 20
nvm use 20

Credenciales del proveedor de IA

Shannon requiere acceso a un modelo de lenguaje grande para sus agentes. Soporta cuatro opciones:

Proveedor	Variables de entorno requeridas
Anthropic (directo)	`ANTHROPIC_API_KEY`
AWS Bedrock	`CLAUDE_CODE_USE_BEDROCK=1`, `AWS_REGION`, `AWS_BEARER_TOKEN_BEDROCK`
Google Vertex AI	`CLAUDE_CODE_USE_VERTEX=1`, `CLOUD_ML_REGION`, `ANTHROPIC_VERTEX_PROJECT_ID`
Endpoint personalizado	`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`

La opción más simple para empezar es usar Anthropic directamente.

Instalación con npx (recomendado)

La forma más rápida de usar Shannon es a través de npx, que descarga y ejecuta el paquete sin instalación permanente:

# Configuración inicial (solo la primera vez)
npx @keygraph/shannon setup

El comando setup verifica los prerrequisitos, descarga la imagen Docker del worker y configura el directorio ~/.shannon/.

# Verificar que la instalación fue exitosa
npx @keygraph/shannon --version

Configuración del proveedor de IA

Opción 1: Anthropic (más simple)

Obtén tu API key en console.anthropic.com:

# Exportar la variable de entorno
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# O persistirla en tu shell
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.bashrc
source ~/.bashrc

Shannon usa tres tamaños de modelo según la complejidad de la tarea:

# Modelos por defecto (puedes sobreescribirlos)
ANTHROPIC_SMALL_MODEL=claude-haiku-4-5-20251001   # Tareas simples, bajo costo
ANTHROPIC_MEDIUM_MODEL=claude-sonnet-4-6           # Análisis estándar
ANTHROPIC_LARGE_MODEL=claude-opus-4-6              # Razonamiento complejo

Opción 2: AWS Bedrock

Si tu organización ya tiene una cuenta de AWS con acceso a Claude:

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION="us-east-1"
export AWS_BEARER_TOKEN_BEDROCK="tu-token-de-bedrock"

Con Bedrock puedes aprovechar los contratos de datos de tu organización con AWS, lo que puede ser relevante si la aplicación auditada maneja datos sensibles.

Opción 3: Google Vertex AI

Para organizaciones con presencia en GCP:

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION="us-east5"
export ANTHROPIC_VERTEX_PROJECT_ID="mi-proyecto-gcp"
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

Opción 4: Endpoint personalizado (proxy corporativo)

Si tu organización usa un proxy de LLM corporativo o un endpoint compatible con la API de Anthropic:

export ANTHROPIC_BASE_URL="https://mi-proxy.empresa.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="mi-token-corporativo"

Instalación desde el repositorio (modo local)

Si prefieres mayor control o quieres contribuir al proyecto, puedes clonar el repositorio:

# Prerrequisito adicional: pnpm
npm install -g pnpm

# Clonar el repositorio
git clone https://github.com/KeygraphHQ/shannon
cd shannon

# Instalar dependencias
pnpm install

# Crear archivo de variables de entorno
cp .env.example .env

Edita .env con tus credenciales:

# .env
ANTHROPIC_API_KEY=sk-ant-api03-...

# Opcional: sobreescribir modelos
ANTHROPIC_LARGE_MODEL=claude-opus-4-6
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

Verificar la instalación

Antes de ejecutar tu primera auditoría, verifica que todo está funcionando:

# Con npx
npx @keygraph/shannon status

# Debe mostrar algo como:
# Shannon v0.x.x
# Docker: ✓ running
# AI Provider: ✓ Anthropic (claude-opus-4-6)
# Workspace directory: ~/.shannon/workspaces/

Estructura de directorios

Después del setup, Shannon crea la siguiente estructura:

graph TD
    HOME["~/.shannon/"] --> CONFIG["config.toml\nConfiguración global"]
    HOME --> WS["workspaces/\nCada auditoría aquí"]
    WS --> WS1["workspace-1/\ncheckpoints via git"]
    WS --> WS2["workspace-2/"]
    HOME --> LOGS["logs/\nLogs de ejecución"]

Los workspaces son repositorios git internos que guardan el progreso de cada auditoría mediante commits. Esto permite reanudar auditorías interrumpidas sin repetir agentes que ya completaron su trabajo.

Configuración de la aplicación target

Para auditorías que requieren autenticación, Shannon acepta un archivo YAML de configuración. Crea un archivo shannon-config.yaml en tu proyecto:

# shannon-config.yaml

# Descripción del entorno (ayuda a los agentes a entender el contexto)
description: |
  Aplicación de gestión de tareas multi-usuario.
  Stack: Node.js + Express + PostgreSQL.
  Tiene roles: admin, manager, employee.
  Los empleados solo pueden ver sus propias tareas.

# Configuración de autenticación
authentication:
  login_type: form           # form | basic | totp | oauth
  login_url: "https://staging.miapp.com/auth/login"
  credentials:
    username: "[email protected]"
    password: "PentestPassword123!"
    # Para apps con 2FA:
    totp_secret: "LB2E2RX7XFHSTGCK"

Tipos de autenticación soportados

Shannon maneja automáticamente flujos de autenticación complejos:

flowchart LR
    A["Usuario\nconvencional"] --> F["Formulario\nlogin_type: form"]
    B["API Key"] --> H["Header HTTP\nlogin_type: bearer"]
    C["2FA / TOTP"] --> T["Código temporal\ntotp_secret en YAML"]
    D["SSO / OAuth"] --> O["Flujo OAuth\nconfiguración extendida"]

Ejemplo con TOTP (Google Authenticator / Authy):

authentication:
  login_type: form
  login_url: "https://app.com/login"
  credentials:
    username: "[email protected]"
    password: "AdminPass456!"
    totp_secret: "JBSWY3DPEHPK3PXP"  # Secret base32 del QR de configuración

Shannon genera el código TOTP en tiempo real durante el login. No necesitas intervención manual.

Variables de entorno avanzadas

Para controlar el comportamiento de Shannon más detalladamente:

# Aumentar el límite de tokens para análisis de código muy grandes
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

# Sobreescribir el modelo para tareas específicas
# Útil para reducir costos usando modelos más económicos en fases simples
export ANTHROPIC_SMALL_MODEL=claude-haiku-4-5-20251001
export ANTHROPIC_MEDIUM_MODEL=claude-sonnet-4-6
export ANTHROPIC_LARGE_MODEL=claude-opus-4-6

Consideraciones de seguridad en la configuración

Las credenciales que configures en Shannon (API keys, contraseñas de la app target) son sensibles. Sigue estas prácticas:

Usa variables de entorno en lugar de archivos YAML cuando sea posible
Nunca commitees el archivo shannon-config.yaml ni .env al repositorio
Usa credenciales de pentesting dedicadas, no tus credenciales reales de la aplicación
El directorio ~/.shannon/ puede contener fragmentos de código del repositorio analizado durante la sesión; Shannon Pro los encripta en reposo

# Agrega a .gitignore
echo "shannon-config.yaml" >> .gitignore
echo ".env" >> .gitignore

Checklist de instalación

Antes de continuar con el siguiente capítulo, verifica:

Docker instalado y corriendo (docker ps funciona)
Node.js 18+ disponible (node --version)
npx @keygraph/shannon setup completado sin errores
Variable ANTHROPIC_API_KEY (o equivalente) exportada
npx @keygraph/shannon status muestra todos los checks en verde
Archivo shannon-config.yaml creado para tu aplicación target

Siguiente paso

Con el entorno configurado, el siguiente capítulo explora la arquitectura interna de Shannon: cómo funcionan sus 5 fases y los 13 agentes especializados que trabajan en paralelo.

→ Capítulo 3: Arquitectura y Sistema de Agentes