feat: add shannon pentesting skill and AGPL-3.0 license

Copy the shannon skill from unicodeveloper/shannon into the Agent Skills repo. Add proper full AGPL-3.0 license text to respect upstream licensing. Update CLAUDE.md to document the new skill. Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-04-02 13:54:37 +00:00
parent 39b1d0abc2
commit 1a6af44a73
6 changed files with 1234 additions and 1 deletions
@@ -0,0 +1,19 @@
+# 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
+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
@@ -0,0 +1,461 @@
+---
+name: shannon
+version: "1.0.0"
+description: "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'."
+argument-hint: 'shannon http://localhost:3000 myapp, shannon --workspace=audit1 http://staging.example.com myrepo'
+allowed-tools: Bash, Read, Write, AskUserQuestion, WebSearch
+homepage: https://github.com/KeygraphHQ/shannon
+repository: https://github.com/KeygraphHQ/shannon
+author: KeygraphHQ
+license: AGPL-3.0
+user-invocable: true
+metadata:
+  openclaw:
+    emoji: "🔐"
+    category: "security"
+    requires:
+      env:
+        - ANTHROPIC_API_KEY
+      optionalEnv:
+        - CLAUDE_CODE_OAUTH_TOKEN
+        - CLAUDE_CODE_USE_BEDROCK
+        - CLAUDE_CODE_USE_VERTEX
+        - AWS_REGION
+        - AWS_ACCESS_KEY_ID
+        - AWS_SECRET_ACCESS_KEY
+      bins:
+        - docker
+        - git
+    primaryEnv: ANTHROPIC_API_KEY
+    files:
+      - "scripts/*"
+    tags:
+      - 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:
+
+```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 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
+```bash
+cd "$SHANNON_HOME" && ./shannon workspaces
+```
+
+### View logs
+```bash
+cd "$SHANNON_HOME" && ./shannon logs ID={workflow-id}
+```
+
+### Stop pentest
+```bash
+cd "$SHANNON_HOME" && ./shannon stop
+```
+
+### Stop and clean up all data
+```bash
+# DESTRUCTIVE — confirm with user first
+cd "$SHANNON_HOME" && ./shannon stop CLEAN=true
+```
+
+### Resume a previous workspace
+```bash
+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
@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# setup-shannon.sh - Install or update Shannon pentester
+# Usage: bash scripts/setup-shannon.sh [SHANNON_HOME]
+set -euo pipefail
+
+SHANNON_HOME="${1:-${SHANNON_HOME:-$HOME/shannon}}"
+
+echo "🔐 Shannon Setup"
+echo "━━━━━━━━━━━━━━━━"
+
+# Check Docker
+if ! command -v docker &>/dev/null; then
+  echo "❌ Docker is required but not installed."
+  echo "   Install: https://docker.com/products/docker-desktop"
+  exit 1
+fi
+echo "✅ Docker: $(docker --version 2>/dev/null | head -1)"
+
+# Check git
+if ! command -v git &>/dev/null; then
+  echo "❌ Git is required but not installed."
+  exit 1
+fi
+echo "✅ Git: $(git --version)"
+
+# Clone or update Shannon
+if [ -d "$SHANNON_HOME" ] && [ -f "$SHANNON_HOME/shannon" ]; then
+  echo "✅ Shannon found at $SHANNON_HOME"
+  echo "   Updating..."
+  cd "$SHANNON_HOME" && git pull --ff-only 2>/dev/null || echo "   (already up to date or can't fast-forward)"
+else
+  echo "📥 Cloning Shannon to $SHANNON_HOME..."
+  git clone https://github.com/KeygraphHQ/shannon.git "$SHANNON_HOME"
+  echo "✅ Shannon cloned successfully"
+fi
+
+# Check API credentials
+echo ""
+echo "API Credentials:"
+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 detected. Set one of:"
+  echo "   export ANTHROPIC_API_KEY=sk-ant-..."
+  echo "   export CLAUDE_CODE_OAUTH_TOKEN=..."
+  echo "   export CLAUDE_CODE_USE_BEDROCK=1"
+  echo "   export CLAUDE_CODE_USE_VERTEX=1"
+fi
+
+echo ""
+echo "Recommended: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000"
+echo ""
+echo "Shannon is ready at: $SHANNON_HOME"
+echo "Run a pentest:  cd $SHANNON_HOME && ./shannon start URL=http://localhost:3000 REPO=myapp"
@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# sync.sh - Deploy shannon skill to all host locations
+# Usage: bash scripts/sync.sh  (run from repo root)
+set -euo pipefail
+
+SRC="$(cd "$(dirname "$0")/.." && pwd)"
+echo "Source: $SRC"
+
+TARGETS=(
+  "$HOME/.claude/skills/shannon"
+  "$HOME/.agents/skills/shannon"
+  "$HOME/.codex/skills/shannon"
+)
+
+for t in "${TARGETS[@]}"; do
+  echo ""
+  echo "--- Syncing to $t ---"
+  mkdir -p "$t/scripts"
+
+  cp "$SRC/SKILL.md" "$t/"
+
+  # Helper scripts
+  if ls "$SRC/scripts/"*.sh &>/dev/null; then
+    rsync -a "$SRC/scripts/"*.sh "$t/scripts/"
+  fi
+
+  echo "  Deployed to $t"
+done
+
+echo ""
+echo "Sync complete."