shannon

What this skill does

# 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:

```bash
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:

```bash
# 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:
```bash
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:

```yaml
# $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:

```bash
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.

```bash
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:
```bash
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:

```bash
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}/`.

```bash
cd "$SHANNON_HOME"

# Find the latest repor