SKILL.md

$29

⚠️  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)

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" ] &#x26;&#x26; [ -f "$SHANNON_HOME/shannon" ]; then

  echo "Shannon found at $SHANNON_HOME"

  cd "$SHANNON_HOME" &#x26;&#x26; 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 &#x26;>/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" &#x26;&#x26; ./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" &#x26;&#x26; ./shannon workspaces

View logs

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

Stop pentest

cd "$SHANNON_HOME" &#x26;&#x26; ./shannon stop

Stop and clean up all data

# DESTRUCTIVE — confirm with user first

cd "$SHANNON_HOME" &#x26;&#x26; ./shannon stop CLEAN=true

Resume a previous workspace

cd "$SHANNON_HOME" &#x26;&#x26; ./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

authentication.login_url

URL

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:

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