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

YAML Config Options

---

Vulnerability Coverage

Shannon tests 50+ specific cases across 5 OWASP categories:

---

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

Shannon Skill

Claude Code skill for autonomous AI pentesting via Shannon. Wraps the Docker-based Shannon pentester as a /shannon slash command.

Structure

• SKILL.md — skill definition (deployed to ~/.claude/skills/shannon/)
• scripts/setup-shannon.sh — installer/updater for Shannon
• scripts/sync.sh — deploy to ~/.claude, ~/.agents, ~/.codex

Commands

bash scripts/sync.sh  # Deploy to all skill locations

Rules

• ALWAYS confirm authorization before running pentests
• NEVER target production systems
• After edits: run bash scripts/sync.sh to deploy

Shannon Skill for Claude Code

Autonomous AI pentester as a Claude Code skill. Wraps KeygraphHQ/Shannon — the white-box security testing framework that analyzes 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 (100/104 exploits).

Install

npx skills add unicodeveloper/shannon

Or install globally:

npx skills add unicodeveloper/shannon -g -y

Quick Start

Once installed, run from Claude Code:

/shannon http://localhost:3000 myapp

Shannon will: 1. Confirm you have authorization to test the target 2. Clone/update the Shannon framework if not already installed 3. Link your source code into Shannon's workspace 4. Check Docker and API credentials 5. Launch a full autonomous pentest across 5 OWASP categories 6. Report findings with reproducible proof-of-concept exploits

Usage Examples

Full pentest of a local app

/shannon http://localhost:3000 myapp

Pentest a staging environment with a named workspace

/shannon --workspace=audit-q1 http://staging.example.com backend-api

Target specific vulnerability categories

/shannon --scope=xss,injection http://localhost:8080 frontend

Check running pentests

/shannon status

View latest report

/shannon results

Stop a running pentest

/shannon stop

Prerequisites

Required

• Docker (or Podman) — Shannon runs entirely in containers
• Install: docker.com/products/docker-desktop
• Git — to clone the Shannon framework
• AI provider credentials (one of the following):

Recommended

export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

What Shannon Tests

Shannon covers 50+ vulnerability types across 5 OWASP categories, all tested with real exploits:

How It Works

Shannon operates as a multi-agent system with 5 phases:

Shannon Pipeline
━━━━━━━━━━━━━━━━

Phase 1: Pre-Recon
├── Static source code analysis
└── External scans (Nmap, Subfinder, WhatWeb)

Phase 2: Recon
└── Live attack surface mapping via headless browser

Phase 3: Vulnerability Analysis (5 parallel agents)
├── Injection agent
├── XSS agent
├── SSRF agent
├── Authentication agent
└── Authorization agent

Phase 4: Exploitation (parallel)
├── Each vuln agent spawns an exploitation agent
└── Real attacks executed to validate findings

Phase 5: Reporting
├── Executive summary
└── Reproducible PoC for every finding

No exploit, no report — Shannon only reports vulnerabilities it can prove with a working proof-of-concept. This minimizes false positives.

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/Playwright — headless browser for automated exploitation

Runtime

• Duration: ~1–1.5 hours for a full pentest
• Cost: ~$50 using Claude Sonnet

Authentication Configuration

For targets that require login, the skill helps you create a YAML config:

# configs/target-config.yaml
authentication:
  type: form                    # "form" or "sso"
  login_url: "http://localhost:3000/login"
  credentials:
    username: "testuser"
    password: "testpass123"
    totp_secret: "BASE32SECRET"  # optional, for 2FA
  flow: "Navigate to login page, enter username and password, click Sign In"
  success_condition:
    url_contains: "/dashboard"

rules:
  avoid:
    - "/logout"
    - "/admin/dangerous-action"
  focus:
    - "/api/"
    - "/auth/"

pipeline:
  max_concurrent_pipelines: 5   # 1-5, default 5
  retry_preset: subscription    # extended backoff for rate-limited API plans

Testing Local Applications

Shannon runs inside Docker, so localhost on your machine isn't reachable from the container. The skill automatically handles this, but for reference:

Skill Structure

shannon-skill/
├── SKILL.md                    # Skill definition (metadata + Claude instructions)
├── CLAUDE.md                   # Project contributor instructions
├── README.md                   # This file
└── scripts/
    ├── setup-shannon.sh        # Installs/updates Shannon, checks prerequisites
    └── sync.sh                 # Deploys skill to ~/.claude, ~/.agents, ~/.codex

Development

Deploy locally after edits

bash scripts/sync.sh

This syncs the skill to:

• ~/.claude/skills/shannon/
• ~/.agents/skills/shannon/
• ~/.codex/skills/shannon/

Run the setup script standalone

bash scripts/setup-shannon.sh

Checks Docker, Git, clones Shannon, and validates API credentials.

Safety

Shannon executes real attacks against targets. The skill enforces safety at every step:

• Authorization gate — asks for confirmation before every pentest
• Environment check — warns against production targets
• Scope control — lets you limit which vulnerability categories to test
• Avoid rules — config option to exclude sensitive paths (e.g., /logout, /admin/delete)
• Containerized — all attack tools run inside Docker, not on your host

Never run Shannon against systems you don't own or have explicit written authorization to test.

Credits

• Shannon by KeygraphHQ — the autonomous pentesting engine (AGPL-3.0)
• Skill wrapper — converts Shannon into a Claude Code /shannon slash command

License

AGPL-3.0 — same as Shannon itself.