shannon

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:

1. 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.
2. Environment: Confirm the target is a local, staging, or sandboxed environment — NEVER production.
3. 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:

1. TARGET_URL: The URL to pentest (e.g., http://localhost:3000, http://staging.example.com)
2. REPO_NAME: The source code folder name (placed in ./repos/ inside Shannon)
3. SCOPE: Full pentest (default) or specific categories (injection, xss, ssrf, auth, authz)
4. WORKSPACE: Named workspace for resume capability (optional)
5. CONFIG: Custom YAML config path (optional, for auth flows, focus/avoid rules)

Common invocation patterns:

• /shannon http://localhost:3000 myapp → Full pentest of local app
• /shannon --workspace=audit1 http://staging.example.com backend-api → Named workspace for resuming
• /shannon --scope=xss,injection http://localhost:8080 frontend → Targeted categories
• /shannon status → Check running pentests
• /shannon results → Show latest report
• /shannon stop → Stop running pentest

Display parsed intent:

🔐 Shannon Pentest
├─ Target: {TARGET_URL}
├─ Source: repos/{REPO_NAME}
├─ Scope: {SCOPE or "Full (all 5 OWASP categories)"}
├─ Workspace: {WORKSPACE or "auto-generated"}
└─ Config: {CONFIG or "default"}

Estimated runtime: 1–1.5 hours │ Estimated cost: ~$50 (Claude Sonnet)

---

Step 0: Ensure Shannon is Installed

Check if Shannon is cloned locally:

SHANNON_HOME="${SHANNON_HOME:-$HOME/shannon}"

if [ -d "$SHANNON_HOME" ] && [ -f "$SHANNON_HOME/shannon" ]; then
  echo "Shannon found at $SHANNON_HOME"
  cd "$SHANNON_HOME" && git pull --ff-only 2>/dev/null || true
else
  echo "Shannon not found. Cloning..."
  git clone https://github.com/KeygraphHQ/shannon.git "$SHANNON_HOME"
fi

# Verify Docker is available
if command -v docker &>/dev/null; then
  echo "Docker: $(docker --version)"
else
  echo "ERROR: Docker is required. Install Docker Desktop: https://docker.com/products/docker-desktop"
  exit 1
fi

If Shannon is not installed, clone it and inform the user. If Docker is missing, stop and tell them to install it.

SHANNON_HOME defaults to ~/shannon. Users can override with SHANNON_HOME env var.

---

Step 1: Prepare Source Code

Shannon needs the target's source code in $SHANNON_HOME/repos/{REPO_NAME}/.

Ask the user where their source code is:

# If user provides a local path
REPO_PATH="/path/to/their/source"
REPO_NAME="myapp"

# Create symlink or copy into Shannon's repos directory
mkdir -p "$SHANNON_HOME/repos"
if [ ! -d "$SHANNON_HOME/repos/$REPO_NAME" ]; then
  ln -s "$(realpath "$REPO_PATH")" "$SHANNON_HOME/repos/$REPO_NAME"
  echo "Linked $REPO_PATH → repos/$REPO_NAME"
fi

If the user provides a GitHub URL instead:

cd "$SHANNON_HOME/repos"
git clone "$GITHUB_URL" "$REPO_NAME"

---

Step 2: Configure Authentication (if needed)

If the target requires login, help the user create a YAML config:

# $SHANNON_HOME/configs/target-config.yaml
authentication:
  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:-}" ]; then
  echo "✅ ANTHROPIC_API_KEY is set"
elif [ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ]; then
  echo "✅ CLAUDE_CODE_OAUTH_TOKEN is set"
elif [ "${CLAUDE_CODE_USE_BEDROCK:-}" = "1" ]; then
  echo "✅ AWS Bedrock mode enabled"
elif [ "${CLAUDE_CODE_USE_VERTEX:-}" = "1" ]; then
  echo "✅ Google Vertex AI mode enabled"
else
  echo "❌ 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-...
• OAuth: export CLAUDE_CODE_OAUTH_TOKEN=...
• AWS Bedrock: export CLAUDE_CODE_USE_BEDROCK=1 + AWS credentials
• Google Vertex: export CLAUDE_CODE_USE_VERTEX=1 + service account in ./credentials/

Also recommend: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

---

Step 4: Launch the Pentest

CRITICAL: Confirm with the user before launching. Display the full command and wait for approval.

cd "$SHANNON_HOME"

# Build the command
CMD="./shannon start URL={TARGET_URL} REPO={REPO_NAME}"

# Add optional flags
# CONFIG=configs/target-config.yaml  (if auth config exists)
# WORKSPACE={WORKSPACE}              (if user specified)
# OUTPUT=./audit-logs/               (default)

echo "Ready to launch:"
echo "  $CMD"
echo ""
echo "This will start Docker containers and begin the pentest."
echo "Runtime: ~1-1.5 hours │ Cost: ~\$50 (Claude Sonnet)"

After user confirms, run in background:

cd "$SHANNON_HOME" && ./shannon start URL={TARGET_URL} REPO={REPO_NAME} {EXTRA_FLAGS}

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}

Explain the 5-phase pipeline:

Shannon Pipeline (5 phases, parallel where possible):
├─ Phase 1: Pre-Recon — Source code analysis + external scans (Nmap, Subfinder, WhatWeb)
├─ Phase 2: Recon — Live attack surface mapping via browser automation
├─ Phase 3: Vulnerability Analysis — 5 parallel agents (Injection, XSS, SSRF, Auth, AuthZ)
├─ Phase 4: Exploitation — Dedicated agents execute real attacks to validate findings
└─ Phase 5: Reporting — Executive summary with reproducible PoCs

---

Step 6: Read and Interpret Results

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" ]; then
  echo "Latest report: $LATEST"
  # Find the main report file
  find "$LATEST" -name "*.md" -type f | head -5
fi

Read the report and present a summary:

🔐 Shannon Pentest Report: {TARGET}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔴 Critical: {N} vulnerabilities
🟠 High:     {N} vulnerabilities
🟡 Medium:   {N} vulnerabilities
🔵 Low:      {N} vulnerabilities

Top Findings:
1. [CRITICAL] {Vuln type} — {location} — PoC: {brief description}
2. [HIGH] {Vuln type} — {location} — PoC: {brief description}
3. ...

Each finding includes a reproducible proof-of-concept exploit.

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.

---

Utility Commands

Check status

cd "$SHANNON_HOME" && ./shannon workspaces

View logs

cd "$SHANNON_HOME" && ./shannon logs ID={workflow-id}

Stop pentest

cd "$SHANNON_HOME" && ./shannon stop

Stop and clean up all data

# DESTRUCTIVE — confirm with user first
cd "$SHANNON_HOME" && ./shannon stop CLEAN=true

Resume a previous workspace

cd "$SHANNON_HOME" && ./shannon start URL={URL} REPO={REPO} WORKSPACE={name}

---

Targeting Local Apps

If the user's app runs on localhost, explain:

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:

Category	Examples
Injection	SQL injection, command injection, SSTI, NoSQL injection
XSS	Reflected, stored, DOM-based, via file upload
SSRF	Internal service access, cloud metadata, protocol smuggling
Broken Auth	Default creds, JWT flaws, session fixation, MFA bypass, CSRF
Broken AuthZ	IDOR, privilege escalation, path traversal, forced browsing

---

Integrated Security Tools (bundled in Docker)

• Nmap — port scanning and service detection
• Subfinder — subdomain enumeration
• WhatWeb — web technology fingerprinting
• Schemathesis — API schema-based fuzzing
• Chromium — headless browser for automated exploitation (Playwright)

---

Context Memory

For the rest of this conversation, remember:

• SHANNON_HOME: Path to Shannon installation
• TARGET_URL: The URL being tested
• REPO_NAME: Source code folder name
• WORKSPACE: Workspace name (if any)
• PENTEST_STATUS: running / completed / stopped

When the user asks follow-up questions:

• Check pentest status and report on progress
• Read and interpret new findings from audit-logs
• Help remediate discovered vulnerabilities with code fixes
• Explain PoC exploits and their impact

---

Security & Permissions

What this skill does:

• Clones/updates the Shannon repo from GitHub to ~/shannon (or $SHANNON_HOME)
• Creates symlinks from user's source code into ~/shannon/repos/
• Starts Docker containers (Temporal server, worker, optional router) via ./shannon CLI
• Reads pentest reports from ~/shannon/audit-logs/
• Optionally creates YAML config files in ~/shannon/configs/

What Shannon does (inside Docker):

• Executes real exploits against the target URL (SQL injection, XSS, SSRF, etc.)
• Scans with Nmap, Subfinder, WhatWeb, Schemathesis
• Automates browser interactions via headless Chromium
• Sends prompts to Anthropic API (or Bedrock/Vertex) for reasoning
• Writes reports to audit-logs/ directory

What this skill does NOT do:

• Does not target any system without user confirmation
• Does not store or transmit API keys beyond the configured provider
• Does not modify the user's source code
• Does not access production systems unless explicitly directed (which it warns against)
• Does not run without Docker — all attack tools are containerized

Review the Shannon source code before first use: https://github.com/KeygraphHQ/shannon