pitimon/shannon-pentest

# Shannon Pentest — Claude Code 插件 [](CHANGELOG.md) [](https://github.com/pitimon/shannon-pentest/actions/workflows/validate.yml) [](LICENSE) [](https://github.com/pitimon/shannon-pentest) **从 Claude Code 编排自主渗透测试** —— 用自然语言描述你的目标，Shannon 会处理剩下的工作：配置、启动、监控和发现分析，并提供泰英双语输出。 ### 为什么选择 Shannon？ | 问题 | Shannon 的解决方案 | | ----------------------------------------------- | --------------------------------------------------------------------------- | | 手动渗透测试设置需要数小时配置 | **自然语言** —— 只需说“pentest my staging app” | | 因范围狭窄而遗漏漏洞类别 | **9 个并行 agent** —— XSS, SQLi, SSRF, auth bypass 等 | | 报告需要安全专业知识才能解读 | **自动分析** —— 包含 CVSS v4.0, OWASP Top 10, MITRE ATT&CK 映射 | | 工具上下文切换减慢你的速度 | **留在 Claude Code** —— 在一个地方配置、启动、监控、分析 | | 重复扫描浪费 API 预算 | **v1.2.0 优化** —— 通过更智能的预侦察节省 17.7% 成本 | ## 实证结果 | 指标 | 数值 | | ------------------ | --------------------------------------------------- | | 总时长 | **81.4 分钟** | | 总成本 | **$18.71** | | 预侦察节省 | 与前一版本相比便宜 **76%** | | 配置验证 | **一次成功**（3 步预验证） | | 发现 | 跨 3 个类别发现 **6 个已确认漏洞** | | Agent 成功率 | **9/9 agents** 完成 | ## 快速开始 ``` # 1. 安装插件 claude plugin marketplace add pitimon/shannon-pentest claude plugin install shannon-pentest@pitimon-shannon # 2. 启动渗透测试（只需描述您的目标） ``` 然后在 Claude Code 中： ``` "pentest my web app at https://staging.example.com" ``` Shannon 会引导你完成目标配置，启动扫描，自动监控进度，并在你的 Claude Code 会话中提供结构化的发现报告。 ## 工作原理 ``` Phase 0 Phase 1 Phase 2 Phase 3 Phase 4 Phase 4.5 Phase 5 Setup → Configure → Launch → Monitor → Analyze → Inline → Handoff Docker Target URL Config Auto-poll Parallel Defense Defensive Shannon Auth type validation every 2-5min Read calls IR checklist docs prompt API key YAML config Pre-flight Stall detect CVSS/OWASP Remediation Clipboard (auto) Web-only Safety confirm Auto-transition PDF/SARIF/HTML Compliance copy detection ./shannon start → Phase 4 Finding tags quick-map → cyber-pro ``` | 阶段 | 发生什么 | | ---------------- | ----------------------------------------------------------------------------------------------------------- | | **0. Setup** | 验证 Docker & Shannon，从你的 Claude Code 会话自动配置 API key | | **1. Configure** | 你提供目标 URL 和认证类型 → plugin 生成 YAML 配置，带有智能目标类型检测 | | **2. Launch** | 配置预验证 (YAML/schema/types) → 预检查 → 安全确认 → `./shannon start` | | **3. Monitor** | 每 2-5 分钟自动轮询，10 分钟时检测停滞，扫描完成时自动转换 | | **4. Analyze** | 并行读取 → 严重性摘要, CVSS v4.0, OWASP Top 10, PDF/SARIF/HTML 导出, 发现生命周期标签 | | **4.5. Defense** | 内联 IR 检查清单，每个发现的修复骨架，OWASP/NIST 合规性快速映射（无需 plugin） | | **5. Handoff** | 预生成 cybersecurity-pro 提示词，剪贴板复制，用于完整防御性文档的结构化清单 | ## 使用示例 ### 自然语言 输入 `/shannon-pentest` 或自然提问： ``` "pentest my web app at https://staging.example.com" "run Shannon against the staging environment" "security audit my application" "ทดสอบเจาะระบบ staging" "find vulnerabilities in my app" ``` ### 直接路由 跳转到特定阶段或参考： ``` "analyze Shannon report" → Phase 4 (report analysis) "export Shannon report as PDF" → Multi-format export (PDF/SARIF/HTML) "generate SARIF from findings" → SARIF export for GitHub Security tab "tag finding as false positive" → Finding lifecycle (status tagging) "show remediation status" → Remediation status report "list Shannon workspaces" → CLI workspace manager "inline defense from findings" → Phase 4.5 (IR checklist + remediation) "create tickets from findings" → Issue template generation (GitHub/Jira) "export SARIF report" → SARIF export for GitHub Security tab "integrate Shannon with CI/CD" → CI/CD pipeline templates "verify fix for stored XSS" → Remediation verification (retest) "save this scan config" → Scan templates (save/load profiles) "suppress this finding" → Finding suppression (whitelist) "correlate findings by root cause" → Finding correlation (grouping) "calculate risk scores" → Risk scoring (CVSS+Exploit+BizImpact) "scan multiple targets" → Multi-target campaign (sequential) "generate SOC 2 compliance report" → Compliance frameworks (7 standards) "show security metrics dashboard" → Security metrics (MTTR/density/cost) "assign owner to finding" → Team remediation (ownership/SLA) "SLA gating for deployment" → CI/CD gating strategies (advanced) "show risk posture score" → Executive reporting (risk posture + trends) "import Burp findings" → External tool import (Burp/ZAP/Nuclei/SARIF) "set up Slack notifications" → Notification hub (webhooks + SLA alerts) "schedule weekly pentest" → Scheduled scanning (cron/Actions/systemd) "benchmark this target" → Historical benchmarking (trends + forecasting) "generate HTML dashboard" → Standalone dashboard (self-contained HTML) "Shannon config for OAuth" → Config templates "validate my Shannon config" → Config pre-validation "Docker error in Shannon" → Troubleshooting guide "check Shannon status" → Monitoring with auto-poll "handoff to cybersecurity-pro" → Phase 5 (defensive docs prompt) "compare Shannon runs" → Session comparison (diff table) "Shannon stats" → Session analytics (cost/duration trends) "set up engagement context" → Engagement setup (client/project info) ``` ## 配置 Shannon 配置**仅使用 3 个根键**（根节点 `additionalProperties: false`）： | 根键 | 必需 | 用途 | | ---------------- | -------- | ------------------------------------------ | | `authentication` | anyOf | 登录凭据，流程，成功条件 | | `rules` | anyOf | 用于界定范围的聚焦/避开路径 | | `pipeline` | optional | 重试预设，并发限制 | ### 快速配置（无认证） ``` rules: focus: - description: "Focus on main application" type: path url_path: "/" pipeline: retry_preset: "subscription" max_concurrent_pipelines: "3" ``` ### 认证场景 | 认证类型 | 配置键 | 模板 | | -------------------- | ------------------------------------ | ------------------------------ | | 无认证（公开） | 仅 `rules` | `config-templates-basic.md` | | 基于表单的登录 | `authentication` (login_type: form) | `config-templates-basic.md` | | TOTP / 2FA | `authentication` (+ totp_secret) | `config-templates-basic.md` | | SSO (SAML/OIDC) | `authentication` (login_type: sso) | `config-templates-advanced.md` | | API Key / Basic Auth | `authentication` (login_type: api) | `config-templates-advanced.md` | | 范围测试 | `rules` (focus + avoid arrays) | `config-templates-advanced.md` | | 本地开发 | `rules` + `host.docker.internal` URL | `config-templates-advanced.md` | ### 预验证 (v1.2.0) 启动前，plugin 运行 3 步验证： 1. **YAML 语法** — `yaml.safe_load()` 检查 2. **根键验证** — 仅允许 `authentication`, `rules`, `pipeline` 3. **值类型检查** — 例如，`max_concurrent_pipelines` 必须是字符串 `"3"` 而不是整数 `3` ## CLI 快速参考 ``` # 开始渗透测试 ./shannon start URL= REPO= ./shannon start URL= REPO= CONFIG= WORKSPACE= # 监控 ./shannon logs # Real-time logs ./shannon query ID= # Query specific workflow ./shannon workspaces # List all workspaces # 停止 ./shannon stop # Graceful stop ./shannon stop CLEAN=true # Stop + cleanup ./shannon stop WORKSPACE= CLEAN=true ``` **Temporal UI:** `http://localhost:8233`（启动后可访问） ## 性能优化 基于实证测试的 v1.2.0 优化： | 优化 | 之前 | 之后 | 影响 | | ------------------------ | --------------------------------- | ---------------------------- | ---------------------- | | 智能目标检测 | 仅 Web 仓库需要 165+ LLM 轮次 | ~5-10 轮次 | 节省约 3-5 分钟 | | 配置模板拆分 | 始终加载约 2,500 tokens | 常见情况约 900 tokens | 减少 64% tokens | | 配置预验证 | 试错法（2-3 次尝试） | 启动前验证 | 零失败启动 | | 主动监控 | 手动状态检查 | 每 2-5 分钟自动轮询 | 减少 2-3 次交互 | | 停滞检测 | 用户在 20+ 分钟后发现 | 10 分钟时自动警告 | 更快恢复 | | 并行报告分析 | 顺序文件读取 | 并发 Read 调用 | 更快的 Phase 4 | ## 安装指南

前置条件

| 工具 | 版本 | 用途 | 安装 | | ------------------ | ----------- | ----------------------------------------------------------- | ---------------------------------------------------------------------- | | **Docker Desktop** | 24.0+ | 运行 Shannon 容器（Temporal, workers, browser agents） | [docker.com/get-docker](https://docs.docker.com/get-docker/) | | **Docker Compose** | v2 (plugin) | 编排多容器 Shannon 栈 | 包含在 Docker Desktop 中 | | **Git** | 2.30+ | 目标源代码的仓库管理 | `brew install git` / `apt install git` | | **Python 3** | 3.8+ | 配置验证，OAuth token 提取 | macOS/Linux 预装 | | **Claude Code** | Latest | Plugin 宿主环境 | [claude.ai/claude-code](https://claude.ai/claude-code) | | **Shannon** | Latest | 自主渗透测试引擎 | [github.com/KeygraphHQ/shannon](https://github.com/KeygraphHQ/shannon) | ### Shannon 安装 ``` git clone https://github.com/KeygraphHQ/shannon.git ~/shannon-tool cd ~/shannon-tool cp .env.example .env chmod +x ./shannon ``` ### API Key 配置 该 plugin 从你活跃的 Claude Code 会话**自动配置** API key —— 无需手动设置。 ``` Claude Code session → OAuth token → Shannon .env (automatic) ``` 如果自动检测失败，请手动设置 Anthropic API key： ``` echo 'ANTHROPIC_API_KEY=sk-ant-...' > ~/shannon-tool/.env ```

预检清单

在第一次渗透测试前运行这些检查： ``` # 1. Docker 运行中？ docker info > /dev/null 2>&1 && echo "✓ Docker running" || echo "✗ Docker not found" # 2. Shannon 已安装？ SHANNON_DIR="${SHANNON_DIR:-$HOME/shannon-tool}" ls "$SHANNON_DIR/shannon" 2>/dev/null && echo "✓ Shannon found" || echo "✗ Not found at $SHANNON_DIR" # 3. .env 已配置？ ls "$SHANNON_DIR/.env" 2>/dev/null && echo "✓ .env exists" || echo "✗ .env missing" # 4. Docker Compose v2？ docker compose version > /dev/null 2>&1 && echo "✓ Compose v2" || echo "✗ Compose not found" # 5. 目标可达？ curl -s -o /dev/null -w "✓ Target responded: %{http_code}" "https://your-staging.example.com" ``` ### 平台说明 | 平台 | 说明 | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **macOS (Apple Silicon)** | Docker Desktop 原生支持 ARM64。`host.docker.internal` 开箱即用。 | | **Linux** | 将用户添加到 docker 组：`sudo usermod -aG docker $USER`。对于本地目标，可能需要 `--add-host=host.docker.internal:host-gateway`。 | | **Windows (WSL2)** | 仅使用 WSL2。在 WSL2 文件系统（`/home/user/`）内克隆 Shannon，而不是 `/mnt/c/`。 |

## 故障排除

常见问题及快速修复

| 问题 | 原因 | 修复 | | --------------------------- | ------------------------------ | ------------------------------------------------------------------- | | `docker: command not found` | 未安装 Docker | 安装 Docker Desktop | | `Not a git repository` | 仓库目录缺少 `.git/` | `cd repos/ && git init && git commit --allow-empty -m "init"` | | 工作区恢复失败 | 缓存的失败状态 | 使用新的工作区名称 | | 配置 schema 错误 | 无效的根键 | 仅使用 `authentication`, `rules`, `pipeline` | | 无法访问 localhost | Docker 网络隔离 | 使用 `host.docker.internal` 代替 `localhost` | | 工作流停滞 (20+ 分钟) | Temporal/资源/速率限制 | 参见 `troubleshooting.md` — Workflow stalling 部分 | | API 速率限制 / 429 | 并发 pipeline 过多 | 设置 `max_concurrent_pipelines: "2"` |

## 相关插件 | Plugin | 描述 | 安装 | | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | **[cybersecurity-pro](https://github.com/pitimon/claude-cybersecurity-skill)** | 18 个领域的防御性安全知识 —— IR playbooks, 合规性, 漏洞管理, API 安全, 威胁建模 | `claude plugin install cybersecurity-pro@pitimon-cybersecurity` | | Shannon 发现类型 | cybersecurity-pro 领域 | 用例 | | -------------------------- | ----------------------------- | -------------------------------------- | | Auth/AuthZ 漏洞 | Domain 13: API Security | JWT, OAuth, BOLA 修复 | | XSS/SQLi/注入 | Domain 6: Code Security | Semgrep/CodeQL 规则，变体分析 | | OWASP Top 10 映射 | Domain 8: Threat Modeling | STRIDE/PASTA 风险评估 | | 漏洞清单 | Domain 14: Vulnerability Mgmt | CVSS+EPSS+KEV 优先级排序 | | 基础设施发现 | Domain 10: Cloud Security | CIS Benchmarks, CSPM 修复 | ## 项目结构 ``` shannon-pentest/ ├── .claude-plugin/ │ ├── marketplace.json # Marketplace registry entry │ └── plugin.json # Plugin manifest (name, version, skills) ├── skills/ │ └── shannon-pentest/ │ ├── SKILL.md # Core skill (~566 lines) — phases, safety, decision tree │ └── references/ │ ├── ci-cd-gating-strategies.md # CI/CD advanced gating: risk score, campaign, SLA, cost │ ├── ci-cd-integration.md # CI/CD severity gating policy (basic) │ ├── companion-tools-fingerprint.md # WhatWeb CMS detection + scanner routing (v3.4.0) │ ├── companion-tools-orchestration.md # Phase 1.5/3/4 workflow + parallel monitoring (v3.4.0) │ ├── companion-tools-overview.md # Kali tool catalog + concurrency + safety (v3.4.0) │ ├── companion-tools-parsers.md # WPScan/ffuf/testssl parsers → Shannon schema (v3.4.0) │ ├── companion-tools-ncsa.md # NCSA compliance mapping + VTS bulk scan (v3.5.0) │ ├── companion-tools-safety.md # Rate limiting + scope enforcement (v3.4.0) │ ├── companion-tools-scanners.md # Docker commands for all companion tools (v3.6.0) │ ├── ci-cd-templates.md # GitHub Actions + GitLab CI YAML templates │ ├── compliance-framework-reports.md # Compliance reports (OWASP/NIST/ISO/SOC2/PCI-DSS/HIPAA/GDPR) │ ├── config-templates-basic.md # No Auth, Form, TOTP (~900 tokens) │ ├── config-templates-advanced.md # SSO, API, Scoped, Pipeline, WordPress │ ├── config-validation.md # Phase 2 validation scripts + common fixes │ ├── defensive-handoff.md # Phase 5 handoff manifest + prompt generation │ ├── engagement-context.md # Engagement context: client, project, scope │ ├── evidence-packaging.md # Evidence archive + manifest schema │ ├── external-tool-import.md # Import Burp/ZAP/Nuclei/SARIF findings (v3.3.0) │ ├── finding-comparison.md # Finding comparison diff between sessions │ ├── finding-correlation.md # Root cause grouping, OWASP + endpoint correlation │ ├── finding-lifecycle.md # Finding status tags, transitions, tracking │ ├── finding-suppression.md # Cross-session finding whitelist management │ ├── historical-benchmarking.md # Date-range queries, trends, forecasting (v3.3.0) │ ├── inline-defense.md # IR checklist, remediation, compliance map │ ├── issue-templates.md # Finding → GitHub/Jira issue template generation │ ├── monitoring-guide.md # Phase 3 polling scripts + stall detection │ ├── multi-format-export.md # PDF/HTML export pipeline │ ├── multi-target-campaign.md # Campaign orchestration: multi-target + aggregate │ ├── notification-hub.md # Slack/Discord/webhook/email notifications (v3.3.0) │ ├── preflight-checks.md # 5-step pre-flight validation (v3.3.0) │ ├── remediation-verification.md # Targeted retest, before/after evidence, verification report │ ├── report-interpretation.md # CVSS v4.0, OWASP, MITRE ATT&CK mapping │ ├── report-templates.md # 3 report templates (executive/technical/compliance) │ ├── risk-scoring.md # Custom risk scoring (CVSS+Exploit+BizImpact) │ ├── sarif-export.md # SARIF v2.1.0 export + GitHub Security tab upload │ ├── scan-templates.md # Save/load reusable scan profiles │ ├── scheduled-scanning.md # Automated recurring scans + regression (v3.3.0) │ ├── security-metrics-dashboard.md # Security KPIs: MTTR, density, cost, risk posture, trends │ ├── session-analytics.md # Session analytics: cost estimation + basic stats │ ├── session-management.md # Session registry, auto-append logic │ ├── setup-automation.md # Phase 0 OAuth token extraction + .env config │ ├── standalone-dashboard.md # Self-contained HTML security dashboard (v3.3.0) │ ├── target-detection.md # Web-only vs source-available detection (v3.3.0) │ ├── team-remediation-dashboard.md # Enterprise workflow: ownership, SLA, audit trail │ ├── troubleshooting.md # Docker, Temporal, Network, Platform issues │ └── troubleshooting-shannon.md # Shannon app, config, API, workspace issues ├── hooks/ │ ├── hooks.json # Pre-validation hook config (PreToolUse) │ └── pre-shannon-start.sh # Config YAML validation before ./shannon start ├── tests/ │ ├── smoke-test-prompts.md # 162 test cases for 40 decision tree routes │ └── validate-plugin.sh # Structure + size + content validation (auto-counted checks) ├── .github/ │ └── workflows/ │ └── validate.yml # CI/CD: automated validation on push/PR ├── CHANGELOG.md # Version history (v1.0.0 → v3.6.0) ├── CLAUDE.md # Project instructions for Claude Code ├── LICENSE # MIT License └── README.md # This file ``` ## 人天成本估算 (v2.4.0)

传统开发 vs AI 辅助开发成本分析

### Plugin 范围 | 指标 | 数值 | | --------------- | -------------------------------- | | 文件总数 | 30 | | 总行数 | 5,140 | | 参考文件 | 46（领域特定内容） | | SKILL.md | 约 566 行（8 个阶段，40 条路由） | | 验证器 | 自动计数检查，7 个部分 | | 冒烟测试 | 162 个用例 | | 发布版本 | 23 (v1.0.0 → v3.6.0) | ### 传统估算（高级安全工程师） | 类别 | 范围 | 人天 | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | 架构与设计 | Plugin 架构，8 阶段工作流，决策树（20 条路由），安全框架，双语策略 | 2.5 | | 核心 SKILL.md | Phase 0-5 逻辑，配置生成，CLI 工作区管理器，内联防御触发器 | 3.5 | | 参考文件 (19) | session-management (拆分), troubleshooting (拆分), report-templates, config-templates, finding-lifecycle, multi-format-export, sarif-export, issue-templates 等 | 9.5 | | 测试与验证 | validate-plugin.sh（自动计数检查），smoke-test-prompts.md（64 个测试），实况 QA 运行 | 3.5 | | CI/CD & Hooks | GitHub Actions 工作流，PreToolUse hook，YAML 回退 | 1.0 | | 文档 | README, CHANGELOG (12 个版本), CLAUDE.md, PR/发布管理 | 2.5 | | 迭代与修复 | 配置 schema 修复，性能优化，质量打磨，跨 12 个版本的 CI 修复 | 2.5 | | **总计** | | **25 人天** | ### 成本比较 | 指标 | 传统 | AI 辅助 (Claude Code) | | -------------------- | ---------------------- | ------------------------- | | 经过时间 | 25 人天（约 5 周） | 约 3-4 小时 | | 成本（泰国费率） | 125,000-200,000 THB | API 成本约 $50-80 | | 质量保证 | 人工 | 自动计数检查 + CI | | 迭代速度 | 每版本数天 | 每版本数分钟 | | **节省时间** | — | **约 98%** | | **节省成本** | — | **约 99%** |

## 安全与许可 此 plugin 强制执行强制性安全规则：**切勿在生产环境运行**（仅限 staging/test），启动前**需要书面授权**，每次扫描前**确认目标 URL**，Shannon 配置之外**不存储凭据**，以及**严格的范围边界**（不扩展到指定目标之外）。 MIT License —— 详见 [LICENSE](LICENSE)。

标签：API 安全, CISA项目, Claude Code 插件, CVSS 评分, DevSecOps, FTP漏洞扫描, LNA, MITRE ATT&CK 映射, OWASP Top 10, PE 加载器, SQL 注入, SSRF 漏洞, XSS 检测, 上游代理, 云安全评估, 双语文本生成, 大模型安全工具, 安全编排, 应用程序安全, 泰语英语双语, 版权保护, 网络安全, 自动化安全评估, 自动化攻击模拟, 请求拦截, 逆向工具, 隐私保护