KeygraphHQ/shannon

## 🎯 什么是 Shannon？ Shannon 是一款能够提供真实 Exploit（漏洞利用）而不仅仅是告警的 AI 渗透测试工具。 Shannon 的目标是在其他人之前攻破您的 Web 应用。它会自主在您的代码中搜寻攻击向量，然后使用其内置浏览器执行真实的 Exploit，例如注入攻击和身份认证绕过，以证明该漏洞确实可被利用。 **Shannon 解决了什么问题？** 得益于 Claude Code 和 Cursor 等工具，您的团队在不停地交付代码。但是您的渗透测试呢？一年才做一次。这造成了一个*巨大*的安全缺口。在其他的 364 天里，您可能在不知不觉中将漏洞发布到了生产环境。 Shannon 通过作为您的按需白盒渗透测试工具来弥补这一差距。它不仅发现潜在问题，还执行真实的 Exploit，提供漏洞的具体证据。这让您能够自信地进行交付，因为您知道每一次构建都是安全的。 ## 🎬 观看 Shannon 实战 **真实成果**：Shannon 在 OWASP Juice Shop 中发现了 20 多个关键漏洞，包括完全的身份认证绕过和数据库泄露。[查看完整报告 →](sample-reports/shannon-report-juice-shop.md)  ## ✨ 功能特性 - **全自主运行**：仅需一条命令即可启动渗透测试。AI 会处理一切，从高级 2FA/TOTP 登录（包括使用 Google 登录）和浏览器导航，到最终报告，全程零干预。 - **渗透测试级报告与可复现的 Exploit**：交付一份专注于已验证、可利用发现的最终报告，附带可复制粘贴的概念验证（Proof-of-Concepts），以消除误报并提供可落地的结果。 - **关键 OWASP 漏洞覆盖**：当前识别并验证以下关键漏洞：Injection（注入）、XSS、SSRF 和失效的身份认证/授权，更多类型正在开发中。 - **代码感知的动态测试**：分析您的源代码以智能地指导其攻击策略，然后对运行中的应用程序执行基于浏览器和命令行的实时 Exploit，以确认真实世界中的风险。 - **由集成安全工具驱动**：通过利用主流的侦察和测试工具——包括 **Nmap、Subfinder、WhatWeb 和 Schemathesis**——增强其发现阶段，对目标环境进行深度分析。 - **并行处理以获得更快结果**：更快地获取您的报告。该系统将最耗时的阶段并行化，同时运行所有漏洞类型的分析和利用。 ## 📦 产品线 Shannon 提供两个版本： | 版本 | 许可证 | 适用场景 | |---------|---------|----------| | **Shannon Lite** | AGPL-3.0 | 安全团队、独立研究人员、测试您自己的应用程序 | | **Shannon Pro** | 商业版 | 需要高级功能、CI/CD 集成和专属支持的企业 | [查看功能对比](./SHANNON-PRO.md) ## 📑 目录 - [什么是 Shannon？](#-what-is-shannon) - [观看 Shannon 实战](#-see-shannon-in-action) - [功能特性](#-features) - [产品线](#-product-line) - [安装与使用说明](#-setup--usage-instructions) - [前置条件](#prerequisites) - [快速开始](#quick-start) - [监控进度](#monitoring-progress) - [停止 Shannon](#stopping-shannon) - [使用示例](#usage-examples) - [工作空间与恢复](#workspaces-and-resuming) - [配置（可选）](#configuration-optional) - [[实验性 - 不支持] Router 模式（替代提供商）](#experimental---unsupported-router-mode-alternative-providers) - [输出与结果](#output-and-results) - [示例报告](#-sample-reports) - [架构](#️-architecture) - [覆盖范围与路线图](#-coverage-and-roadmap) - [免责声明](#️-disclaimers) - [许可证](#-license) - [社区与支持](#-community--support) - [联系我们](#-get-in-touch) ## 🚀 安装与使用说明 ### 前置条件 - **Docker** - 容器运行时 ([安装 Docker](https://docs.docker.com/get-docker/)) - **AI 提供商凭证**（选择其一）： - **Anthropic API key**（推荐） - 从 [Anthropic Console](https://console.anthropic.com) 获取 - **Claude Code OAuth token** - **[实验性 - 不支持] 通过 Router 模式使用替代提供商** - 通过 OpenRouter 使用 OpenAI 或 Google Gemini（参见 [Router 模式](#experimental---unsupported-router-mode-alternative-providers)) ### 快速开始 ``` # 克隆 Shannon git clone https://github.com/KeygraphHQ/shannon.git cd shannon # 配置凭证（选择一种方法） # 选项 A：导出环境变量 export ANTHROPIC_API_KEY="your-api-key" # or CLAUDE_CODE_OAUTH_TOKEN export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000 # recommended # 选项 B：创建 .env 文件 cat > .env << 'EOF' ANTHROPIC_API_KEY=your-api-key CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000 EOF # 运行一次 pentest ./shannon start URL=https://your-app.com REPO=your-repo ``` Shannon 将构建容器，启动工作流，并返回一个工作流 ID。渗透测试在后台运行。 ### 监控进度 ``` # 查看实时 worker 日志 ./shannon logs # 查询特定 workflow 的进度 ./shannon query ID=shannon-1234567890 # 打开 Temporal Web UI 进行详细监控 open http://localhost:8233 ``` ### 停止 Shannon ``` # 停止所有容器（保留 workflow 数据） ./shannon stop # 完全清理（删除所有数据） ./shannon stop CLEAN=true ``` ### 使用示例 ``` # 基础 pentest ./shannon start URL=https://example.com REPO=repo-name # 使用配置文件 ./shannon start URL=https://example.com REPO=repo-name CONFIG=./configs/my-config.yaml # 自定义输出目录 ./shannon start URL=https://example.com REPO=repo-name OUTPUT=./my-reports # 命名 workspace ./shannon start URL=https://example.com REPO=repo-name WORKSPACE=q1-audit # 列出所有 workspace ./shannon workspaces ``` ### 工作空间与恢复 Shannon 支持**工作空间**，允许您恢复中断或失败的运行，而无需重新运行已完成的 Agent。 **工作原理：** - 每次运行都会在 `audit-logs/` 中创建一个工作空间（默认自动命名，例如 `example-com_shannon-1771007534808`） - 使用 `WORKSPACE=` 为您的运行指定一个自定义名称，以便于引用 - 要恢复任何运行，通过 `WORKSPACE=` 传递其工作空间名称 —— Shannon 会检测哪些 Agent 已成功完成，并从断点继续 - 每个 Agent 的进度通过 Git commits 进行 Checkpoint，因此恢复的运行从干净、已验证的状态开始 ``` # 使用命名 workspace 启动 ./shannon start URL=https://example.com REPO=repo-name WORKSPACE=my-audit # 恢复同一 workspace（跳过已完成的 agent） ./shannon start URL=https://example.com REPO=repo-name WORKSPACE=my-audit # 从之前的运行中恢复自动命名的 workspace ./shannon start URL=https://example.com REPO=repo-name WORKSPACE=example-com_shannon-1771007534808 # 列出所有 workspace 及其状态 ./shannon workspaces ``` ### 准备您的代码库 Shannon 期望目标代码库放置在项目根目录下的 `./repos/` 目录中。`REPO` 标志指的是 `./repos/` 内部的文件夹名称。将要扫描的代码库复制到 `./repos/` 中，或直接在那里克隆： ``` git clone https://github.com/your-org/your-repo.git ./repos/your-repo ``` **对于 Monorepo：** ``` git clone https://github.com/your-org/your-monorepo.git ./repos/your-monorepo ``` **对于多代码库应用程序**（例如，前端/后端分离）： ``` mkdir ./repos/your-app cd ./repos/your-app git clone https://github.com/your-org/frontend.git git clone https://github.com/your-org/backend.git git clone https://github.com/your-org/api.git ``` ### 特定平台说明 **对于 Windows：** *原生 (Git Bash)：* 安装 [Git for Windows](https://git-scm.com/install/windows) 并从 **Git Bash** 运行 Shannon，需安装 Docker Desktop。 *WSL2（推荐）：* **步骤 1：确保使用 WSL 2** ``` wsl --install wsl --set-default-version 2 # 检查已安装的 distro wsl --list --verbose # 如果你没有 distro，安装一个（推荐 Ubuntu 24.04） wsl --list --online wsl --install Ubuntu-24.04 # 如果你的 distro 显示 VERSION 1，将其转换为 WSL 2： wsl --set-version 2 ``` 参见 [WSL 基本命令](https://learn.microsoft.com/en-us/windows/wsl/basic-commands) 以供参考。 **步骤 2：在 Windows 上安装 Docker Desktop** 并在 *Settings > General > Use the WSL 2 based engine* 下启用 **WSL2 后端**。 **步骤 3：在 WSL 内克隆并运行 Shannon。** 在 PowerShell 或 CMD 中输入 `wsl -d ` 并按 Enter 打开 WSL 终端。 ``` # 在 WSL 终端内 git clone https://github.com/KeygraphHQ/shannon.git cd shannon cp .env.example .env # Edit with your API key ./shannon start URL=https://your-app.com REPO=your-repo ``` 要访问 Temporal Web UI，在 WSL 内运行 `ip addr` 找到您的 WSL IP 地址，然后在 Windows 浏览器中导航到 `http://:8233`。 Windows Defender 可能会将报告中的 Exploit 代码标记为误报；请参阅下文的 [杀毒软件误报](#6-windows-antivirus-false-positives)。 **对于 Linux（原生 Docker）：** 根据您的 Docker 设置，您可能需要使用 `sudo` 运行命令。如果遇到输出文件的权限问题，请确保您的用户有权访问 Docker socket。 **对于 macOS：** 安装 Docker Desktop 后即可开箱即用。 **测试本地应用程序：** Docker 容器无法访问您主机上的 `localhost`。请使用 `host.docker.internal` 代替 `localhost`： ``` ./shannon start URL=http://host.docker.internal:3000 REPO=repo-name ``` ### 配置（可选） 虽然您可以在没有配置文件的情况下运行，但创建一个可以启用经过认证的测试和自定义分析。将您的配置文件放置在 `./configs/` 目录内 —— 此文件夹会自动挂载到 Docker 容器中。 #### 创建配置文件 复制并修改示例配置： ``` cp configs/example-config.yaml configs/my-app-config.yaml ``` #### 基本配置结构 ``` authentication: login_type: form login_url: "https://your-app.com/login" credentials: username: "test@example.com" password: "yourpassword" totp_secret: "LB2E2RX7XFHSTGCK" # Optional for 2FA login_flow: - "Type $username into the email field" - "Type $password into the password field" - "Click the 'Sign In' button" success_condition: type: url_contains value: "/dashboard" rules: avoid: - description: "AI should avoid testing logout functionality" type: path url_path: "/logout" focus: - description: "AI should emphasize testing API endpoints" type: path url_path: "/api" ``` #### 2FA 的 TOTP 设置 如果您的应用程序使用双因素认证，只需将 TOTP secret 添加到您的配置文件中。AI 将在测试期间自动生成所需的代码。 #### 订阅计划速率限制 Anthropic 订阅计划在**滚动 5 小时窗口**内重置使用量。默认的重试策略（最大 30 分钟退避）会在窗口重置前耗尽重试次数。将此添加到您的配置中： ``` pipeline: retry_preset: subscription # Extends max backoff to 6h, 100 retries max_concurrent_pipelines: 2 # Run 2 of 5 pipelines at a time (reduces burst API usage) ``` `max_concurrent_pipelines` 控制同时运行多少个漏洞流水线（1-5，默认值：5）。较低的值可降低触发速率限制的几率，但会增加实际耗时。 ### [实验性 - 不支持] Router 模式（替代提供商） Shannon 可以在实验性地通过 claude-code-router 将请求路由到替代的 AI 提供商。此模式非官方支持，主要用于： * **模型实验** — 尝试将 Shannon 与 GPT-5.2 或 Gemini 3 系列模型一起使用 #### 快速设置 1. 将您的提供商 API key 添加到 `.env`： ``` # 选择一个 provider： OPENAI_API_KEY=sk-... # 或 OPENROUTER_API_KEY=sk-or-... # 设置默认 model： ROUTER_DEFAULT=openai,gpt-5.2 # provider,model format ``` 2. 使用 `ROUTER=true` 运行： ``` ./shannon start URL=https://example.com REPO=repo-name ROUTER=true ``` #### 实验性模型 | Provider | Models | |----------|--------| | OpenAI | gpt-5.2, gpt-5-mini | | OpenRouter | google/gemini-3-flash-preview | #### 免责声明 此功能是实验性的且不受支持。输出质量很大程度上取决于模型。Shannon 构建在 Anthropic Agent SDK 之上，并针对 Anthropic Claude 模型进行了优化和主要测试。根据模型和路由设置，替代提供商可能会产生不一致的结果（包括在 Recon 等早期阶段失败）。 ### 输出与结果 所有结果默认保存到 `./audit-logs/{hostname}_{sessionId}/`。使用 `--output ` 指定自定义目录。 输出结构： ``` audit-logs/{hostname}_{sessionId}/ ├── session.json # Metrics and session data ├── agents/ # Per-agent execution logs ├── prompts/ # Prompt snapshots for reproducibility └── deliverables/ └── comprehensive_security_assessment_report.md # Final comprehensive security report ``` ## 📊 示例报告 通过行业标准易受攻击应用程序的渗透测试结果，观看 Shannon 的实战能力： #### 🧃 **OWASP Juice Shop** • [GitHub](https://github.com/juice-shop/juice-shop) *由 OWASP 维护的一个出了名不安全的 Web 应用程序，旨在测试工具发现各种现代漏洞的能力。* **表现**：在单次自动化运行中，在目标 OWASP 类别中识别出 **20 多个高危漏洞**。 **主要成果**： - **实现了完全的身份认证绕过**，并通过 Injection 攻击泄露了整个用户数据库 - **通过绕过注册流程创建新的管理员账户，执行了完全的权限提升** - **识别并利用了系统性的授权缺陷（IDOR）**，以访问和修改任何用户的私有数据和购物车 - **发现了 Server-Side Request Forgery (SSRF) 漏洞**，从而能够进行内网侦察 📄 **[查看完整报告 →](sample-reports/shannon-report-juice-shop.md)** #### 🔗 **c{api}tal API** • [GitHub](https://github.com/Checkmarx/capital) *来自 Checkmarx 的一个故意设计为易受攻击的 API，旨在测试工具发现 OWASP API Security Top 10 的能力。* **表现**：识别出 **近 15 个严重和高危漏洞**，导致应用程序完全沦陷。 **主要成果**： - **通过在隐藏的调试端点中利用命令链绕过拒绝列表，执行了 Root 级别的 Injection 攻击** - **通过发现并针对遗留的、未修补的 v1 API 端点，实现了完全的身份认证绕过** - **通过利用用户配置文件更新功能中的 Mass Assignment 漏洞，将普通用户提升为完全的管理员权限** - **展示了高准确性**，通过正确确认应用程序强大的 XSS 防御，报告了零误报 📄 **[查看完整报告 →](sample-reports/shannon-report-capital-api.md)** #### 🚗 **OWASP crAPI** • [GitHub](https://github.com/OWASP/crAPI) *来自 OWASP 的一个现代、故意设计为易受攻击的 API，旨在根据 OWASP API Security Top 10 基准测试工具的有效性。* **表现**：识别出 **超过 15 个严重和高危漏洞**，实现了应用程序的完全沦陷。 **主要成果**： - **使用多种高级 JWT 攻击绕过了身份认证**，包括算法混淆、alg:none 和弱密钥 注入 - **通过 Injection 攻击实现了完全的数据库沦陷**，从 PostgreSQL 数据库中泄露了用户凭证- **执行了关键的 Server-Side Request Forgery (SSRF) 攻击**，成功地将内部认证令牌转发到外部服务 - **展示了高准确性**，通过正确识别应用程序强大的 XSS 防御，报告了零误报 📄 **[查看完整报告 →](sample-reports/shannon-report-crapi.md)** *这些结果展示了 Shannon 超越简单扫描的能力，能够以极少的误报和可落地的概念验证执行深度上下文利用。* ## 🏗️ 架构 Shannon 使用复杂的多 Agent 架构模拟人类渗透测试员的方法论。它将白盒源代码分析与黑盒动态利用相结合，分为四个不同的阶段： ``` ┌──────────────────────┐ │ Reconnaissance │ └──────────┬───────────┘ │ ▼ ┌──────────┴───────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Vuln Analysis │ │ Vuln Analysis │ │ ... │ │ (Injection) │ │ (XSS) │ │ │ └─────────┬───────┘ └─────────┬───────┘ └─────────┬───────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Exploitation │ │ Exploitation │ │ ... │ │ (Injection) │ │ (XSS) │ │ │ └─────────┬───────┘ └─────────┬───────┘ └─────────┬───────┘ │ │ │ └─────────┬─────────┴───────────────────┘ │ ▼ ┌──────────────────────┐ │ Reporting │ └──────────────────────┘ ``` ### 架构概述 Shannon 旨在模拟人类渗透测试员的方法论。它利用 Anthropic 的 Claude Agent SDK 作为其核心推理引擎，但其真正的优势在于围绕它构建的复杂多 Agent 架构。该架构将**白盒源代码分析**的深度上下文与**黑盒动态利用**的真实世界验证相结合，由编排器通过四个不同的阶段进行管理，以确保专注于最小的误报和智能的上下文管理。 #### **阶段 1：侦察** 第一阶段构建应用程序攻击面的全面地图。Shannon 分析源代码并集成 Nmap 和 Subfinder 等工具以了解技术栈和基础设施。同时，它通过浏览器自动化进行实时应用程序探索，将代码级洞察与真实世界行为相关联，为下一阶段生成所有入口点、API 端点和身份认证机制的详细地图。 #### **阶段 2：漏洞分析** 为了最大化效率，此阶段并行运行。使用侦察数据，针对每个 OWASP 类别的专业化 Agent 并行搜寻潜在缺陷。对于 Injection 和 SSRF 等漏洞，Agent 执行结构化数据流分析，追踪用户输入到危险 Sinks 的路径。此阶段产生一个关键交付物：传递给验证阶段的**假设的可利用路径**列表。 #### **阶段 3：利用** 继续并行工作流以保持速度，此阶段完全致力于将假设转化为证据。专用的 Exploit Agent 接收假设路径，并尝试使用浏览器自动化、命令行工具和自定义脚本执行真实世界的攻击。此阶段执行严格的**“无利用，不报告”**策略：如果无法成功利用假设来证明影响，则将其作为误报丢弃。 #### **阶段 4：报告** 最后阶段将所有已验证的发现汇编成一份专业、可落地的报告。一个 Agent 整合侦察数据和成功的 Exploit 证据，清理任何噪音或幻觉产生的伪影。仅包含已验证的漏洞，附带**可复现、可复制粘贴的概念验证**，交付一份专注于已验证风险的最终渗透测试级报告。 ## 📋 覆盖范围与路线图 有关 Shannon 安全测试覆盖范围和开发路线图的详细信息，请参阅我们的 [覆盖范围与路线图](./COVERAGE.md) 文档。 ## ⚠️ 免责声明 ### 重要使用指南与免责声明 在使用 Shannon (Lite) 之前，请仔细阅读以下指南。作为用户，您应对自己的行为负责并承担所有责任。 #### **1. 变更性影响的可能性与环境选择** 这不是一个被动扫描器。利用 Agent 旨在**主动执行攻击**以确认漏洞。此过程可能对目标应用程序及其数据产生变更性影响。 #### **2. 法律与合规使用** Shannon 仅设计用于合法的安全审计目的。 #### **3. LLM 与自动化注意事项** - **需要验证**：尽管我们在“利用即证明”方法上投入了大量工程工作以消除误报，但底层 LLM 仍可能在最终报告中产生幻觉或弱支持的内容。**人工监督至关重要**，以验证所有报告发现的合法性和严重性。 - **全面性**：由于 LLM 上下文窗口的固有限制，Shannon Lite 中的分析可能不是详尽的。为了对您的整个代码库进行更全面、基于图的分析，**Shannon Pro** 利用其高级数据流分析引擎确保更深层次和更彻底的覆盖。 #### **4. 分析范围** - **目标漏洞**：当前版本的 Shannon Lite 专门针对以下类别的*可利用*漏洞： - 失效的身份认证与授权 (Broken Authentication & Authorization) - 注入 (Injection) - 跨站脚本攻击 (XSS) - 服务端请求伪造 (SSRF) - **Shannon Lite 未覆盖的内容**：此列表并未涵盖所有潜在的安全风险。Shannon Lite 的“利用即证明”模型意味着它不会报告它无法主动利用的问题，例如易受攻击的第三方库或不安全的配置。这些类型的深度静态分析发现是 **Shannon Pro** 高级分析引擎的核心关注点。 #### **5. 成本与性能** - **时间**：截至当前版本，一次完整测试运行通常需要 **1 到 1.5 小时**才能完成。 - **成本**：使用 Anthropic 的 Claude 4.5 Sonnet 模型运行完整测试可能会产生约 **50 美元**的费用。费用因模型定价和应用程序复杂性而异。 #### **6. Windows 杀毒软件误报** Windows Defender 可能会将 `xben-benchmark-results/` 或 `deliverables/` 中的文件标记为恶意软件。这些是由报告中的 Exploit 代码引起的误报。请在 Windows Defender 中为 Shannon 目录添加排除项，或使用 Docker/WSL2。 ## 📜 许可证 Shannon Lite 根据 [GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE) 发布。 Shannon 是开源的 (AGPL v3)。此许可证允许您： - 自由将其用于所有内部安全测试。 - 私下修改代码以供内部使用，而无需共享您的更改。 AGPL 的共享要求主要适用于将 Shannon 作为公共服务或托管服务（例如 SaaS 平台）提供的组织。在这些特定情况下，对核心软件所做的任何修改都必须开源。 ## 👥 社区与支持 ### 社区资源 **贡献：** 目前，我们不接受外部代码贡献（PR）。 欢迎提交 Issue 用于错误报告和功能请求。 - 🐛 **报告错误** 通过 [GitHub Issues](https://github.com/KeygraphHQ/shannon/issues) - 💡 **建议功能** 在 [Discussions](https://github.com/KeygraphHQ/shannon/discussions) 中 - 💬 **加入我们的 [Discord](https://discord.gg/KAqzSHHpRt)** 获取实时社区支持 ### 保持联系 - 🐦 **Twitter**: [@KeygraphHQ](https://twitter.com/KeygraphHQ) - 💼 **LinkedIn**: [Keygraph](https://linkedin.com/company/keygraph) - 🌐 **官网**: [keygraph.io](https://keygraph.io) ## 💬 联系我们 ### 对 Shannon Pro 感兴趣？ Shannon Pro 专为认真对待应用程序安全的组织而设计。它提供企业级功能、专属支持和无缝的 CI/CD 集成，全部由我们最先进的基于 LLM 的分析引擎驱动。在复杂的漏洞深入您的代码库之前，发现并修复它们。 有关功能、技术差异和企业用例的详细细分，请参阅我们的 [完整对比指南](./SHANNON-PRO.md)。

**或直接联系我们：** 📧 **邮箱**: [shannon@keygraph.io](mailto:shannon@keygraph.io)

由 Keygraph 团队用 ❤️ 构建
让应用程序安全触手可及

标签：CISA项目, CTI, DevSecOps, Web安全, 上游代理, 人工智能, 多语言支持, 大模型安全, 安全测试框架, 数据展示, 数据窃取, 注入攻击, 用户模式Hook绕过, 白盒测试, 红队, 网络安全, 自动化利用, 自动化攻击, 自动化攻击, 自动化攻击, 蓝队分析, 请求拦截, 逆向工具, 鉴权绕过, 隐私保护