Autonomous AI pentester for web apps and APIs. Run white-box security assessments with Shannon — analyzes source code, identifies attack vectors, and executes real exploits to prove vulnerabilities. Triggered by 'shannon', 'pentest', 'security audit', 'vuln scan'.
Instrucciones de origen · Vista previa de solo lectura
name
shannon
version
1.0.0
description
Autonomous AI pentester for web apps and APIs. Run white-box security assessments with Shannon — analyzes source code, identifies attack vectors, and executes real exploits to prove vulnerabilities. Triggered by 'shannon', 'pentest', 'security audit', 'vuln scan'.
Shannon: Autonomous AI Pentester for Web Apps & APIs
Permissions overview: This skill orchestrates Shannon, a Docker-based pentesting tool that actively executes attacks against a target application. It clones/updates the Shannon repo locally, runs Docker containers, and reads pentest reports. Shannon performs real exploits — only run against apps you own or have explicit written authorization to test. Never run against production systems.
Shannon analyzes your source code, identifies attack vectors, and executes real exploits to prove vulnerabilities before they reach production. 96.15% exploit success rate on the XBOW security benchmark. Covers OWASP Top 10: Injection, XSS, SSRF, Broken Auth, Broken AuthZ, and more.
CRITICAL: Safety Checks (ALWAYS run first)
Before doing ANYTHING, you MUST confirm:
Authorization: Ask the user — "Do you have explicit authorization to pentest this target?" If they say no or are unsure, STOP and explain they need written permission from the system owner.
Environment: Confirm the target is a local, staging, or sandboxed environment — NEVER production.
Scope: Clarify what they want tested (full pentest vs specific category).
⚠️ Shannon executes REAL ATTACKS with mutative effects.
├─ Only run on systems you OWN or have WRITTEN AUTHORIZATION to test
├─ Never target production environments
├─ Results require human review — LLM output may contain hallucinations
└─ You are responsible for complying with all applicable laws
Display this warning BEFORE every pentest run. If the user has already confirmed authorization in this session, a brief reminder suffices.
Parse User Intent
Extract from the user's input:
TARGET_URL: The URL to pentest (e.g., http://localhost:3000, http://staging.example.com)
REPO_NAME: The source code folder name (placed in ./repos/ inside Shannon)
SCOPE: Full pentest (default) or specific categories (injection, xss, ssrf, auth, authz)
WORKSPACE: Named workspace for resume capability (optional)
If the target requires login, help the user create a YAML config:
# $SHANNON_HOME/configs/target-config.yamlauthentication:type:form# "form" or "sso"login_url:"http://localhost:3000/login"credentials:username:"admin"password:"password123"flow:"Navigate to login page, enter username and password, click Sign In"success_condition:url_contains:"/dashboard"rules:avoid:-"/logout"-"/admin/delete"focus:-"/api/"-"/auth/"pipeline:max_concurrent_pipelines:5# 1-5, default 5
Only create a config if the target requires authentication or has specific scope rules. For open/unauthenticated targets, no config is needed.
Step 3: Verify API Credentials
Check that AI provider credentials are available:
cd"$SHANNON_HOME"# Check for Anthropic API key (primary)if [ -n "${ANTHROPIC_API_KEY:-}" ]; thenecho"✅ ANTHROPIC_API_KEY is set"elif [ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ]; thenecho"✅ CLAUDE_CODE_OAUTH_TOKEN is set"elif [ "${CLAUDE_CODE_USE_BEDROCK:-}" = "1" ]; thenecho"✅ AWS Bedrock mode enabled"elif [ "${CLAUDE_CODE_USE_VERTEX:-}" = "1" ]; thenecho"✅ Google Vertex AI mode enabled"elseecho"❌ No AI credentials found."echo"Set one of: ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, or enable Bedrock/Vertex"exit 1
fi
If no credentials are found, explain the options:
Direct API (recommended): export ANTHROPIC_API_KEY=sk-ant-...
Use run_in_background: true with a timeout of 600000ms (10 minutes for initial setup). The pentest itself runs in Docker and will continue independently.
Step 5: Monitor Progress
While the pentest runs, the user can check status:
cd"$SHANNON_HOME"# List active workspaces
./shannon workspaces
# View logs for a specific workflow
./shannon logs ID={workflow-id}
Reports are saved to $SHANNON_HOME/audit-logs/{hostname}_{sessionId}/.
cd"$SHANNON_HOME"# Find the latest report
LATEST=$(ls -td audit-logs/*/ 2>/dev/null | head -1)
if [ -n "$LATEST" ]; thenecho"Latest report: $LATEST"# Find the main report file
find "$LATEST" -name "*.md" -type f | head -5
fi
IMPORTANT: Shannon's "no exploit, no report" policy means every finding has a working PoC. But remind the user that LLM-generated content requires human review.
Shannon runs inside Docker. To reach your local app:
├─ Use http://host.docker.internal:{PORT} instead of http://localhost:{PORT}
├─ macOS/Windows: works automatically with Docker Desktop
└─ Linux: add --add-host=host.docker.internal:host-gateway to docker run
Automatically translate localhost URLs to host.docker.internal in the command.
Configuration Reference
Environment Variables
Variable
Required
Description
ANTHROPIC_API_KEY
One of these
Direct Anthropic API key
CLAUDE_CODE_OAUTH_TOKEN
required
Anthropic OAuth token
CLAUDE_CODE_USE_BEDROCK
Set to 1 for AWS Bedrock
CLAUDE_CODE_USE_VERTEX
Set to 1 for Google Vertex AI
CLAUDE_CODE_MAX_OUTPUT_TOKENS
Recommended
Set to 64000
SHANNON_HOME
Optional
Shannon install dir (default: ~/shannon)
YAML Config Options
Section
Field
Description
authentication.type
form / sso
Login method
authentication.login_url
URL
Login page
authentication.credentials
object
username, password, totp_secret
authentication.flow
string
Natural language login instructions
authentication.success_condition
object
url_contains or element_present
rules.avoid
list
Paths/subdomains to skip
rules.focus
list
Paths/subdomains to prioritize
pipeline.retry_preset
subscription
Extended backoff for rate-limited plans
pipeline.max_concurrent_pipelines
1-5
Parallel agent count (default: 5)
Vulnerability Coverage
Shannon tests 50+ specific cases across 5 OWASP categories:
