--- id: sm-shannon name: "shannon" url: https://skills.yangsir.net/skill/sm-shannon author: unicodeveloper domain: ai-skill-platform-ecosystem tags: ["product-strategy", "platform-development", "user-experience", "software-product", "market-analysis"] install_count: 2000 rating: 4.30 (20 reviews) github: https://github.com/unicodeveloper/shannon --- # shannon > shannon — AI Agent 技能工具，AI Agent Skill，提升工作效率和自动化能力 **Stats**: 2,000 installs · 4.3/5 (20 reviews) ## Before / After 对比 ### Web 应用与 API 渗透测试效率对比 | Metric | Before | After | Change | |---|---|---|---| | - | - | - | - | | - | - | - | - | | - | - | - | - | ## Readme # 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: - **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. - **Environment**: Confirm the target is a local, staging, or sandboxed environment — NEVER production. - **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: - **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" ] && [ -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 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](https://github.com/KeygraphHQ/shannon) Weekly Installs312Repository[unicodeveloper/shannon](https://github.com/unicodeveloper/shannon)GitHub Stars7First Seen9 days agoSecurity Audits[Gen Agent Trust HubWarn](/unicodeveloper/shannon/shannon/security/agent-trust-hub)[SocketPass](/unicodeveloper/shannon/shannon/security/socket)[SnykWarn](/unicodeveloper/shannon/shannon/security/snyk)Installed oncodex300opencode299cursor299kimi-cli298gemini-cli298github-copilot298 --- *Source: https://skills.yangsir.net/skill/sm-shannon* *Markdown mirror: https://skills.yangsir.net/api/skill/sm-shannon/markdown*