shannon

Shannon：面向 Web 应用和 API 的自主 AI 渗透测试工具

权限概览： 此技能会编排 Shannon，这是一款基于 Docker 的渗透测试工具，会主动对目标应用执行攻击。它会在本地克隆或更新 Shannon 仓库、运行 Docker 容器并读取渗透测试报告。**Shannon 会执行真实漏洞利用——只能对你拥有或已获得明确书面授权的应用进行测试。**切勿对生产系统运行。

Shannon 会分析你的源代码、识别攻击向量，并执行真实漏洞利用，以便在漏洞进入生产环境前验证它们。它在 XBOW 安全基准测试中的漏洞利用成功率为 96.15%。涵盖 OWASP Top 10：注入、XSS、SSRF、身份验证失效、授权失效等。

---

关键：安全检查（务必首先执行）

在进行任何操作之前，你必须确认：

1. 授权： 询问用户：“你是否拥有对此目标进行渗透测试的明确授权？”如果用户回答没有或不确定，请停止，并说明他们需要获得系统所有者的书面许可。
2. 环境： 确认目标是本地、预发布或沙盒环境——绝不能是生产环境。
3. 范围： 明确用户希望测试的内容（完整渗透测试还是特定类别）。

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

每次渗透测试前都要显示此警告。如果用户已在本次会话中确认授权，简短提醒即可。

---

解析用户意图

从用户输入中提取：

1. TARGET_URL：要进行渗透测试的网址（例如，http://localhost:3000、http://staging.example.com）
2. REPO_NAME：源代码文件夹名称（位于 Shannon 内的 ./repos/ 中）
3. SCOPE：完整渗透测试（默认）或特定类别（injection、xss、ssrf、auth、authz）
4. WORKSPACE：用于恢复测试的命名工作区（可选）
5. CONFIG：自定义 YAML 配置文件路径（可选，用于身份验证流程、聚焦/避开规则）

常见调用方式：

• /shannon http://localhost:3000 myapp → 对本地应用进行完整渗透测试
• /shannon --workspace=audit1 http://staging.example.com backend-api → 指定命名工作区以便恢复测试
• /shannon --scope=xss,injection http://localhost:8080 frontend → 针对指定类别进行测试
• /shannon status → 检查正在运行的渗透测试
• /shannon results → 显示最新报告
• /shannon stop → 停止正在运行的渗透测试

显示解析出的意图：

🔐 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)

---

步骤 0：确保已安装 Shannon

检查本地是否已克隆 Shannon：

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

如果尚未安装 Shannon，请克隆并告知用户。如果缺少 Docker，请停止并告知用户安装 Docker。

SHANNON_HOME 默认为 ~/shannon。用户可通过 SHANNON_HOME 环境变量覆盖此设置。

---

步骤 1：准备源代码

Shannon 需要将目标的源代码放在 $SHANNON_HOME/repos/{REPO_NAME}/ 中。

询问用户源代码所在位置：

# 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

如果用户提供的是 GitHub URL：

cd "$SHANNON_HOME/repos"
git clone "$GITHUB_URL" "$REPO_NAME"

---

步骤 2：配置身份验证（如有需要）

如果目标需要登录，请协助用户创建 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

**只有目标需要身份验证或有特定范围规则时才创建配置。**对于开放或无需身份验证的目标，无需配置。

---

步骤 3：验证 API 凭据

检查是否已提供 AI 服务商凭据：

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

如果未找到凭据，请说明可选方案：

• 直接 API（推荐）：export ANTHROPIC_API_KEY=sk-ant-...
• OAuth：export CLAUDE_CODE_OAUTH_TOKEN=...
• AWS Bedrock：export CLAUDE_CODE_USE_BEDROCK=1 + AWS 凭据
• Google Vertex：export CLAUDE_CODE_USE_VERTEX=1 + ./credentials/ 中的服务账号

另建议设置：export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

---

步骤 4：启动渗透测试

**关键：启动前先征得用户确认。**显示完整命令并等待批准。

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)"

用户确认后，在后台运行：

cd "$SHANNON_HOME" && ./shannon start URL={TARGET_URL} REPO={REPO_NAME} {EXTRA_FLAGS}

设置 run_in_background: true，超时时间为 600000ms（初始设置需要 10 分钟）。渗透测试本身会在 Docker 中运行，并独立持续执行。

---

第 5 步：监控进度

渗透测试运行期间，用户可以查看状态：

cd "$SHANNON_HOME"

# List active workspaces
./shannon workspaces

# View logs for a specific workflow
./shannon logs ID={workflow-id}

说明 5 阶段流水线：

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

---

第 6 步：读取并解读结果

报告保存在 $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

读取报告并提供摘要：

🔐 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.

重要：Shannon 的“没有利用就没有报告”策略意味着每个发现都有可用的 PoC。 但请提醒用户，LLM 生成的内容需要人工审核。

---

实用命令

查看状态

cd "$SHANNON_HOME" && ./shannon workspaces

查看日志

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

停止渗透测试

cd "$SHANNON_HOME" && ./shannon stop

停止并清理所有数据

# DESTRUCTIVE — confirm with user first
cd "$SHANNON_HOME" && ./shannon stop CLEAN=true

恢复之前的工作区

cd "$SHANNON_HOME" && ./shannon start URL={URL} REPO={REPO} WORKSPACE={name}

---

针对本地应用

如果用户的应用在 localhost 上运行，请说明：

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

在命令中自动将 localhost URL 转换为 host.docker.internal。

---

配置参考

环境变量

变量	必需	描述
ANTHROPIC_API_KEY	其中之一	直接使用的 Anthropic API 密钥
CLAUDE_CODE_OAUTH_TOKEN	必需	Anthropic OAuth 令牌
CLAUDE_CODE_USE_BEDROCK		设置为 1 以使用 AWS Bedrock
CLAUDE_CODE_USE_VERTEX		设置为 1 以使用 Google Vertex AI
CLAUDE_CODE_MAX_OUTPUT_TOKENS	建议	设置为 64000
SHANNON_HOME	可选	Shannon 安装目录（默认：~/shannon）

YAML 配置选项

部分	字段	描述
authentication.type	form / sso	登录方式
authentication.login_url	URL	登录页面
authentication.credentials	object	用户名、密码、totp_secret
authentication.flow	string	自然语言登录说明
authentication.success_condition	object	url_contains 或 element_present
rules.avoid	list	要跳过的路径/子域名
rules.focus	list	优先处理的路径/子域名
pipeline.retry_preset	subscription	针对受速率限制的方案延长退避时间
pipeline.max_concurrent_pipelines	1-5	并行 Agent 数量（默认：5）

---

漏洞覆盖范围

Shannon 会针对 5 个 OWASP 类别测试 50 多个具体案例：

类别	示例
注入	SQL 注入、命令注入、SSTI、NoSQL 注入
XSS	反射型、存储型、基于 DOM、通过文件上传
SSRF	访问内部服务、云元数据、协议混淆
身份验证失效	默认凭据、JWT 漏洞、会话固定、绕过 MFA、CSRF
授权失效	IDOR、权限提升、路径遍历、强制浏览

---

集成的安全工具（打包在 Docker 中）

• Nmap — 端口扫描和服务检测
• Subfinder — 子域名枚举
• WhatWeb — Web 技术指纹识别
• Schemathesis — 基于 API 架构的模糊测试
• Chromium — 用于自动化利用的无头浏览器（Playwright）

---

上下文记忆

在本次对话的剩余时间内，请记住：

• SHANNON_HOME：Shannon 的安装路径
• TARGET_URL：正在测试的 URL
• REPO_NAME：源代码文件夹名称
• WORKSPACE：工作区名称（如有）
• PENTEST_STATUS：running / completed / stopped

当用户提出后续问题时：

• 检查渗透测试状态并汇报进展
• 从 audit-logs 读取并解读新的发现
• 通过代码修复帮助修复已发现的漏洞
• 说明 PoC 漏洞利用及其影响

---

安全与权限

此技能的用途：

• 从 GitHub 克隆或更新 Shannon 仓库到 ~/shannon（或 $SHANNON_HOME）
• 将用户的源代码创建符号链接到 ~/shannon/repos/
• 通过 ./shannon CLI 启动 Docker 容器（Temporal 服务器、工作进程、可选的路由器）
• 从 ~/shannon/audit-logs/ 读取渗透测试报告
• 可选：在 ~/shannon/configs/ 中创建 YAML 配置文件

Shannon 的功能（在 Docker 内）：

• 针对目标 URL 执行真实攻击（SQL 注入、XSS、SSRF 等）
• 使用 Nmap、Subfinder、WhatWeb、Schemathesis 进行扫描
• 通过无头 Chromium 自动执行浏览器交互
• 向 Anthropic API（或 Bedrock/Vertex）发送提示词以进行推理
• 将报告写入 audit-logs/ 目录

此技能不会执行的操作：

• 未经用户确认，不会针对任何系统
• 不会在已配置的提供商之外存储或传输 API 密钥
• 不会修改用户的源代码
• 除非用户明确指示，否则不会访问生产系统（并会对此发出警告）
• 不会在没有 Docker 的情况下运行——所有攻击工具都在容器中运行

首次使用前，请检查 Shannon 源代码： https://github.com/KeygraphHQ/shannon