shannon v3.1.0
Shannon 是一款面向 Web 应用程序和 API 的自主白盒 AI 渗透测试工具。它会分析你的源代码，识别攻击向量，并执行真实的漏洞利用，从而在漏洞进入生产环境之前证明其存在。
[!NOTE] Shannon 3.0 已发布： 更深入的安全代码分析、更彻底验证的发现、重建的 CLI、原生 CI/CD、专业 PDF 报告以及 SARIF。
Shannon 是一款面向 Web 应用程序和 API 的自主 AI 渗透测试工具。
它会分析你的源代码，识别攻击路径，并执行真实漏洞利用，以在漏洞进入生产环境之前加以证明。没有漏洞利用，就没有报告。
本仓库是 Shannon 开源版：完整的智能体，可从你的命令行本地运行。
启动 Shannon
```bash npx @keygraph/shannon@latest ``` 交互式启动器将引导你完成设置和首次渗透测试。
[!TIP] AI 智能体与 LLM： 请先阅读 llms.txt 以获取本仓库的简明地图，或使用 llms-full.txt 获取合并为一个文件的 README 和文档。
目录
什么是 Shannon？
Shannon 是由 Keygraph 开发的自主 AI 渗透测试工具。它通过将源代码分析与实时漏洞利用相结合，对 Web 应用程序及其底层 API 进行安全测试。
Shannon 分析你的 Web 应用程序源代码以识别潜在攻击向量，然后使用浏览器自动化和命令行工具对运行中的应用程序及其 API 执行真实漏洞利用。只有具备可用概念验证（PoC）的漏洞才会被纳入最终报告。
Shannon 是智能体。本仓库是 Shannon 开源版，即你可以自行运行的独立渗透测试工具。同一个 Shannon 也为 Keygraph 平台提供支持，这是 Keygraph 的商业渗透测试产品。请参阅版本了解两者的对比。
Shannon 为何存在
得益于 Claude Code 和 Cursor 等工具，你的团队可以不停地交付代码。但你的渗透测试呢？一年才做一次。这造成了巨大的安全缺口。在其余 364 天里，你可能在不知不觉中把漏洞交付到生产环境。
Shannon 通过提供按需、自动化的渗透测试来弥合这一缺口，可针对每次构建或发布运行。
为什么叫 "Shannon"？
它以信息论之父 Claude Shannon 命名。从本质上讲，渗透测试是一个信息问题：每一次探测都会减少关于系统状态的不确定性。最好的工具会最大化每次请求所获得的信息量，将这些知识片段转化为漏洞利用路径。
另外，我们也希望你能说出："嘿 Claude，运行 Shannon"，来找出你那个凭感觉写出来的应用中的所有安全缺陷。
不能替代人类渗透测试人员
Shannon 旨在与专业渗透测试人员和红队成员协同工作，而非取代他们。优秀的渗透测试人员了解业务，能以无人预料到的方式串联攻击，并带来当前模型无法匹敌的多年判断力。
Shannon 解决的是另一个问题：需要测试的软件远远多于安全团队有时间覆盖的范围。关键系统会定期接受专家评估，而内部应用、API 和快速迭代的服务这一长尾则几乎从未被测试过。
Shannon 将渗透测试左移进入软件开发生命周期（SDLC）。用它按照实际交付节奏对预发布环境和发布版本运行有漏洞利用支撑的测试，并将专家人力时间留给那些需要了解组织情况的人来处理的风险。
Shannon 实战
这些报告来自 Shannon 开源版对 Photoview 2.4.0 的扫描，该应用是 Doyensec 对 Aikido 和 XBOW 对比研究中的应用之一。我们针对同一应用版本运行了 Shannon，并独立评估其结果。阅读 Doyensec 研究以及我们的 Shannon 后续对比，了解方法论、局限性、成本和结果。
快速开始
前置条件
- Docker：worker 容器所需。
- Node.js 18+：推荐的
npx工作流所需。 - AI 提供商凭据：Shannon 可运行在 Anthropic、OpenAI、xAI、AWS Bedrock 以及 harness 目录中的任何其他提供商上——其中每一个都可以通过自定义 base URL 指向代理或 LLM 网关。你自带密钥，Keygraph 绝不会代理你的模型流量。Shannon 与提供商无关。有关建议的模型 ID，请参阅 AI 提供商。
- 已与你的提供商完成网络安全保障措施：Anthropic 和 OpenAI 会对网络安全工作负载应用实时保障措施，这可能会在扫描运行中途中断。在首次运行前完成他们针对合法安全测试人员的指引——请参阅 AI 提供商。
运行 Shannon
[!WARNING] Shannon 会主动执行漏洞利用。仅针对你拥有或已获得明确书面授权测试的应用程序和环境运行它。不要对生产系统运行 Shannon。```bash
Configure credentials with the interactive wizard.
npx @keygraph/shannon@latest setup
Run a pentest against a source-available target.
npx @keygraph/shannon@latest start
-u https://your-app.com
-r /path/to/your/repo
Shannon 从 Docker Hub 拉取 worker 镜像，启动所需的本地基础设施，将目标仓库以只读方式挂载到临时 worker 容器内，并将结果写入本地工作区。
关于源码构建、认证扫描、特定提供商配置以及平台说明，请参阅[文档](#documentation)。
> [!TIP]
> **更倾向于使用订阅而非 API 额度？**
>
> - **OpenAI Codex：** 最新版本的 Shannon 支持 ChatGPT Plus 和 Pro 订阅。请按照 [OpenAI Codex 订阅设置指南](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#openai-codex-chatgpt-pluspro-subscription) 开始使用。
> - **xAI (Grok)：** 最新版本的 Shannon 支持 xAI 订阅。请按照 [xAI 订阅设置指南](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#xai-grok-subscription) 开始使用。
> - **Claude Code：** 最新版本的 Shannon 不支持 Claude Code 订阅。请按照 [Claude Code 订阅设置指南](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#claude-code-subscription) 使用版本 `1.9.0`，这是基于 Claude Agent SDK 构建的最终版本。
## 核心能力
- **无利用，不报告**：仅报告已通过可复现的概念验证确认的漏洞，减少推测性扫描器噪声。
- **高级代码分析**：在将可信攻击路径发送给实时渗透测试代理之前，先梳理架构、信任边界、接口、数据流和关键资产。
- **自主执行**：通过单条命令运行侦察、分析、利用和报告。
- **实时终端体验**：简化扫描设置，展示代理进度和结果，同时不暴露编排日志。
- **认证测试**：通过配置支持凭据、登录流程、TOTP、电子邮件认证、重点领域和交战规则。
- **聚焦 OWASP 的覆盖范围**：测试可利用的注入、XSS、SSRF、身份验证失效和授权失效。
- **可恢复工作区**：恢复中断的扫描，无需重复已完成的工作。
- **原生 CI/CD 集成**：通过官方 GitHub Action 或 GitLab CI/CD 组件运行，保留产物、发布发现结果，并基于已证实的漏洞对发布进行门禁。
- **多格式报告**：生成证据丰富的 PDF 和 Markdown 报告，以及 JSON 和 SARIF 2.1.0。对于利用模式扫描，SARIF 默认启用。
- **提供商无关且支持 BYOK**：支持 Anthropic、OpenAI、xAI、AWS Bedrock、兼容 API 和 LLM 网关，以及通过 Ollama、vLLM 或 LM Studio 提供的本地模型。
- **设计上保护隐私**：在你的基础设施中运行，将结果存储在本地，并将模型请求直接发送到你选择的端点。本地端点可将数据保留在你的环境内。
## CI/CD 集成
Shannon 可以通过 [GitHub Actions](https://github.com/KeygraphHQ/shannon-action) 和 [GitLab CI/CD](https://gitlab.com/KeygraphHQ/shannon-ci) 的官方集成，持续针对已部署的预发布和开发环境运行。
两种集成均可：
- 在攻击正在运行的目标的同时，分析已检出的源码仓库；
- 将 PDF、Markdown 和 SARIF 报告保留为流水线产物；
- 保留扫描和代理日志以便调试，包括未完成的运行；
- 支持拉取请求、发布和定时渗透测试；
- 区分未完成的评估与已完成但无发现结果的扫描；并且
- 可选地在 Shannon 利用达到或超过配置严重性阈值的漏洞时使流水线失败。
代码分析假设不会使流水线失败。严重性门禁仅统计具有 `status: exploited` 的发现结果。
### GitHub Actions```yaml
name: Shannon Pentest
on:
workflow_dispatch:
permissions:
security-events: write
jobs:
pentest:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Shannon
uses: KeygraphHQ/shannon-action@v1
with:
url: https://staging.example.com
api-key: ${{ secrets.SHANNON_AI_API_KEY }}
fail-on-severity: high
upload-sarif: true
该 Action 默认将 repo 设置为已检出的 GitHub 工作区。它会上传一个包含安全评估报告和 SARIF 的工件，以及一个包含扫描和代理日志的独立运行工件。启用 upload-sarif 会将受支持的发现结果发布到 GitHub 代码扫描。
要求：
- 一个私有仓库；
- 一个带有 Docker 和 Docker Compose v2 的运行器；
- 对正在运行的预发布或开发目标的访问权限；以及
- 作为 GitHub Actions secret 存储的模型提供商凭据。
请参阅 Shannon GitHub Action 文档 和 GitHub Marketplace 列表。
版本
Shannon 开源版 是一个完整的自主渗透测试工具，特别适合在本地或 CI/CD 中运行针对性安全测试的个人开发者和小型团队。
Keygraph 企业平台 适用于需要在多个团队、仓库和环境之间进行持续代理式渗透测试/应用安全的共享平台的组织。它集中提供更深入的分析、漏洞管理、修复、验证、治理和报告，使团队无需自行组装和维护这些工作流。
架构
Shannon 将多阶段安全代码分析与实时侦察和利用相结合：```mermaid flowchart TD S["Source code"] --> EXISTING["Recon + vulnerability analysis"] S --> SAST["Agentic security code analysis"]
EXISTING -- "Pentest candidates" --> REC["Finding reconciliation<br/>(merge + deduplicate)"]
SAST -- "SAST candidates" --> REC
REC -- "Reconciled exploitation queue" --> EXP["Exploitation agents"]
APP["Running application"] --> EXP
EXP -- "Exploit demonstrated" --> REPORT["Reporting<br/>PDF · Markdown · SARIF"]
EXP -- "No exploit demonstrated" --> DROP["Discard"]
REPORT --> CICD["CI/CD gate"]
分阶段说明：
1. **侦察与漏洞分析**：探查正在运行的应用程序，将运行时行为与源代码关联起来，并针对注入、XSS、SSRF、身份验证和授权运行专门的 agent。
2. **Agentic 安全代码分析**：梳理应用程序的架构、信任边界、暴露的接口、依赖项、数据流和高风险资产，然后针对它们展开有针对性的调查。
3. **发现项对账**：合并两路候选发现，对重叠部分去重，并将剩余部分归入利用队列。
4. **利用 agent**：针对正在运行的应用程序尝试真实的概念验证攻击。
5. **验证**：剔除所有 Shannon 无法复现的候选发现。
6. **报告**：生成附带证据的 PDF 和 Markdown 报告，以及供下游系统使用的结构化 JSON 和 SARIF。
只有经过实时验证的漏洞才会成为 Shannon 渗透测试发现项，或计入 CI/CD 严重性门禁。
每次扫描都在一个临时 Docker 容器中运行，具有隔离的工作区和按调用进行的编排。
## 文档
使用以下指南了解操作细节：
| 指南 | 用途 |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [源码构建和 CLI 命令](https://github.com/keygraphhq/shannon/blob/main/docs/development.md) | 克隆、构建、常用命令、输出路径和本地开发。 |
| [配置](https://github.com/keygraphhq/shannon/blob/main/docs/configuration.md) | 经过身份验证的测试、登录流程、交战规则和报告过滤器。 |
| [AI 提供商](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md) | 选择模型、支持的提供商（Anthropic、OpenAI、xAI、AWS Bedrock 以及任何其他 Pi 支持的提供商）和自定义 LLM 网关。 |
| [平台和网络](https://github.com/keygraphhq/shannon/blob/main/docs/platforms.md) | Windows/WSL2、Linux、macOS、Docker 网络、本地应用和自定义主机名。 |
| [工作区和恢复](https://github.com/keygraphhq/shannon/blob/main/docs/workspaces.md) | 命名工作区、恢复中断的扫描和工作区存储。 |
| [安全性和限制](https://github.com/keygraphhq/shannon/blob/main/docs/safety.md) | 授权使用要求、非生产环境指导、变更性影响、成本和模型注意事项。 |
| [覆盖范围和路线图](https://github.com/keygraphhq/shannon/blob/main/docs/coverage-roadmap.md) | 当前的漏洞覆盖范围和计划中的工作。 |
| [Keygraph 企业平台](https://github.com/keygraphhq/shannon/blob/main/docs/keygraph-platform.md) | 穷尽式 agentic SAST、持续渗透测试、全生命周期发现项管理、修复、定向验证、企业治理和本地部署。 |
## 安全性、范围和限制
Shannon 不是被动扫描器。它的利用 agent 可以创建用户、提交表单、变更应用程序状态、触发出站请求，并以其他方式影响目标系统。请使用沙箱、预发布或本地开发环境以及可丢弃的数据。
您有责任以合法且合乎道德的方式使用 Shannon。不要将 Shannon 指向您不拥有或没有明确授权测试的系统、代码仓库或应用程序。
重要限制：
- Shannon 开源版针对日常开发和 CI/CD 中快速、代码驱动的渗透测试进行了调优。穷尽式 agentic SAST、更广泛的扫描器覆盖范围、集中式治理和全生命周期漏洞管理通过 Keygraph 企业平台提供。
- 发现项仍需要人工审查。LLM 生成的报告可能包含支持不足或不正确的细节。
- Anthropic、OpenAI、xAI 和 AWS Bedrock 是内置提供商，harness 目录中的任何其他提供商也可使用——每个都可以通过自定义 base URL 访问，将其指向代理或 LLM 网关。模型能力各不相同，如果模型不能可靠地遵循 Shannon 的指令或工具使用约束，将产生较弱的结果。
- 完整运行大约需要 1 到 1.5 小时，并且可能根据模型定价和应用程序复杂性产生 LLM API 费用。
- 不要扫描不受信任或对抗性的代码库。读取源代码的 AI 驱动工具可能会受到提示注入的影响。
在新的环境中运行 Shannon 之前，请阅读完整的[安全性和限制](https://github.com/keygraphhq/shannon/blob/main/docs/safety.md)指南。
## 许可证
Shannon 开源版根据 [GNU Affero 通用公共许可证 v3.0](https://github.com/keygraphhq/shannon/blob/main/LICENSE) 授权。
对于需要不同许可条款、商业支持、私有再分发、托管服务使用或更广泛部署选项（包括 Keygraph 平台）的组织，可提供商业和企业许可。
如需商业许可，请联系 [[email protected]](mailto:[email protected])。
## 致谢
感谢 [Pi](https://github.com/earendil-works/pi)、
[Playwright CLI](https://github.com/microsoft/playwright-cli)
和 [Mantis](https://github.com/google/mantis)。
有关许可和署名详情，请参阅 [THIRD_PARTY_NOTICES.md](https://github.com/keygraphhq/shannon/blob/main/THIRD_PARTY_NOTICES.md)。
## 关于 Keygraph
**Keygraph** 是 Shannon 背后的公司。它还构建了 **Keygraph 平台**，这是商业化的 agentic 渗透测试产品，覆盖完整的 AppSec 生命周期，并运行 Shannon 的增强版本作为其渗透测试引擎。
## 社区和支持
**社区办公时间**可用于获得有关 bug、部署和配置问题的实操帮助。
- 美国/欧盟：周四，太平洋时间上午 10:00
- 亚洲：周四，印度标准时间下午 2:00
- [预约时段](https://cal.com/george-flores-keygraph/shannon-community-office-hours)
[加入 Discord](https://discord.gg/cmctpMBXwE) 提问、分享反馈并与其他 Shannon 用户交流。
目前，Keygraph 不接受外部代码贡献。欢迎提交 issue 来报告 bug 和请求功能：
- [报告 bug](https://github.com/KeygraphHQ/shannon/issues)
- [建议功能](https://github.com/KeygraphHQ/shannon/discussions)
保持联系：
- [Keygraph 网站](https://keygraph.io)
- [Twitter/X：@KeygraphHQ](https://twitter.com/KeygraphHQ)
- [LinkedIn：Keygraph](https://linkedin.com/company/keygraph)
## 常见问题
### 我可以自行托管 Shannon 吗？
可以。Shannon 开源版在您的基础设施内以临时 worker 容器运行。它以只读方式挂载代码仓库，并将结果写入本地工作区。
Keygraph 永远不会接收您的源代码，也永远不会代理您的模型流量。您的模型请求会直接发送到您配置的提供商或端点，并且这些请求会携带源代码和应用程序上下文。将 Shannon 指向本地托管的端点，该流量也会留在您的环境内。
### Shannon 支持自带密钥（BYOK）吗？
是的，始终支持。在每种部署中，无论是开源版还是商业版，您都提供 Shannon 用于运行渗透测试的 LLM 凭据。Keygraph 永远不会代理您的模型流量。
### Shannon 会输出 SARIF 吗？
会。Shannon 会输出 SARIF 2.1.0，这是静态分析结果的 OASIS 标准格式，同时还会输出结构化 JSON。任何 SARIF 消费者都可以读取它：代码扫描服务、漏洞管理平台、安全仪表板和 CI/CD 流水线。在 exploit-mode 扫描中默认写入；在配置文件中将 `report.sarif` 设置为 `"false"` 可选择退出。
### Shannon 支持哪些 AI 提供商？
Anthropic、OpenAI、xAI 和 AWS Bedrock 是内置的，并直接通过提供商 ID 配置。除此之外，Shannon 可运行在 Pi harness 目录中的任何提供商上，并以相同的 `<provider>:<model-id>` 方式命名。任何提供商都可以通过自定义 base URL 指向代理或 LLM 网关，这只会覆盖端点，并保留该提供商的 API 方言。Shannon 在整个渗透测试中使用单一的统一模型设置。
### 我可以在本地或自托管模型上运行 Shannon 吗？
Shannon 可与通过 Ollama、vLLM 或 LM Studio 提供的本地模型配合使用，这些模型暴露 OpenAI 兼容端点，也可与 OpenRouter 等路由器和 LiteLLM 等 LLM 网关配合使用。使用自定义 base URL 将 Shannon 指向该端点。能力各不相同，如果模型不能可靠地遵循 Shannon 的指令或工具使用约束，将产生比前沿模型更弱的渗透测试结果，因此只有在您了解所选模型的行为时才采用此路径。请参阅 [AI 提供商](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#custom-base-url)。
### Shannon 实际上会利用漏洞，还是只是扫描？
Shannon 会执行真实利用。只有当它生成了可工作的概念验证时，才会报告发现项，并丢弃无法证明的假设。它是渗透测试器，不是被动扫描器。
**由 [Keygraph](https://keygraph.io) 构建**