skills/shannon/SKILL.md

name, version, description, argument-hint, allowed-tools, homepage, repository, author, license, user-invocable, metadata

name	version	description	argument-hint	allowed-tools	homepage	repository	author	license	user-invocable	metadata
shannon	1.0.0	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 http://localhost:3000 myapp, shannon --workspace=audit1 http://staging.example.com myrepo	Bash, Read, Write, AskUserQuestion, WebSearch	https://github.com/KeygraphHQ/shannon	https://github.com/KeygraphHQ/shannon	KeygraphHQ	AGPL-3.0	true	openclaw emoji category requires primaryEnv files tags 🔐 security env optionalEnv bins ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL ANTHROPIC_MODEL ANTHROPIC_SMALL_FAST_MODEL CLAUDE_CODE_OAUTH_TOKEN CLAUDE_CODE_USE_BEDROCK CLAUDE_CODE_USE_VERTEX AWS_REGION AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY docker git ANTHROPIC_API_KEY scripts/* security pentesting pentest vulnerability exploit owasp xss sqli ssrf authentication authorization white-box appsec

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 AI provider credentials
if [ -n "${ANTHROPIC_API_KEY:-}" ]; then
  echo "✅ ANTHROPIC_API_KEY is set"
elif [ -n "${ANTHROPIC_AUTH_TOKEN:-}" ] && [ -n "${ANTHROPIC_BASE_URL:-}" ]; then
  echo "✅ MiniMax mode: ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL are set"
  echo "   Base URL: $ANTHROPIC_BASE_URL"
  echo "   Model: ${ANTHROPIC_MODEL:-MiniMax-M2.7}"
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, ANTHROPIC_AUTH_TOKEN+ANTHROPIC_BASE_URL (MiniMax), 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-...
• MiniMax: Set ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL (see MiniMax section below)
• 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.

---

Using MiniMax as AI Provider

Shannon supports MiniMax as an alternative AI backend via the Anthropic SDK compatibility layer. MiniMax provides the MiniMax-M2.7 model through an Anthropic-compatible API endpoint.

MiniMax Setup

1. Get a MiniMax API key from platform.minimax.io.

2. Configure environment variables — either export them directly or add to ~/.claude/settings.json:

# Export directly
export ANTHROPIC_AUTH_TOKEN="your-minimax-api-key"
export ANTHROPIC_BASE_URL="https://api.minimax.io/anthropic"   # International
# export ANTHROPIC_BASE_URL="https://api.minimaxi.com/anthropic"  # China

# Set model (all model slots use the same MiniMax model)
export ANTHROPIC_MODEL="MiniMax-M2.7"
export ANTHROPIC_SMALL_FAST_MODEL="MiniMax-M2.7"
export ANTHROPIC_DEFAULT_SONNET_MODEL="MiniMax-M2.7"
export ANTHROPIC_DEFAULT_OPUS_MODEL="MiniMax-M2.7"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="MiniMax-M2.7"

Or in ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-minimax-api-key",
    "ANTHROPIC_BASE_URL": "https://api.minimax.io/anthropic",
    "ANTHROPIC_MODEL": "MiniMax-M2.7",
    "ANTHROPIC_SMALL_FAST_MODEL": "MiniMax-M2.7",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "MiniMax-M2.7",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "MiniMax-M2.7",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "MiniMax-M2.7",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

3. Clear conflicting env vars — ensure ANTHROPIC_API_KEY is not set when using MiniMax, as it takes precedence:

unset ANTHROPIC_API_KEY

4. Run Shannon normally — the MiniMax credentials are passed through to Shannon's Docker containers via the Anthropic SDK compatibility layer:

cd "$SHANNON_HOME" && ./shannon start URL=http://localhost:3000 REPO=myapp

MiniMax Notes

• MiniMax uses ANTHROPIC_AUTH_TOKEN (not ANTHROPIC_API_KEY) for authentication
• The ANTHROPIC_BASE_URL routes requests to MiniMax's Anthropic-compatible endpoint
• Set API_TIMEOUT_MS=3000000 for extended timeouts (recommended for pentesting workloads)
• Set CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 to reduce non-essential API calls
• MiniMax provides a single model (MiniMax-M2.7) that is used for all model slots

---

Configuration Reference

Environment Variables

Variable	Required	Description
ANTHROPIC_API_KEY	One of these	Direct Anthropic API key
ANTHROPIC_AUTH_TOKEN	required	MiniMax (or compatible) auth token
ANTHROPIC_BASE_URL		API base URL (for MiniMax: https://api.minimax.io/anthropic)
ANTHROPIC_MODEL		Model override (e.g., MiniMax-M2.7)
ANTHROPIC_SMALL_FAST_MODEL		Small/fast model override
CLAUDE_CODE_OAUTH_TOKEN		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
API_TIMEOUT_MS	Optional	Request timeout in ms (MiniMax: 3000000)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC	Optional	Set to 1 to reduce non-essential calls
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