KeygraphHQ / shannon

17,1661,811+4,144 todayTypeScript

Fully autonomous AI hacker to find actual exploits in your web apps. Shannon has achieved a 96.15% success rate on the hint-free, source-aware XBOW Benchmark.

💡 Use Cases

最适合需要持续、自动化安全测试的Web应用开发团队，特别是在快速迭代的开发环境中。

持续集成安全测试

Problem: 开发团队频繁发布新功能，但传统渗透测试一年才做一次，导致新代码中的安全漏洞长期暴露。

Solution: 将Shannon集成到CI/CD流水线中，每次代码提交或部署前自动运行，像单元测试一样持续检测安全漏洞。

Example: 在GitHub Actions或Jenkins中配置Shannon，每次合并请求到主分支时自动扫描Web应用，发现并报告注入、XSS等漏洞。

新功能上线前验证

Problem: 开发人员完成新功能开发后，缺乏快速验证安全性的工具，只能依赖有限的手动测试。

Solution: 在功能部署到生产环境前，用Shannon进行自主渗透测试，提供可复现的漏洞证明，避免带病上线。

Example: 开发团队完成用户认证模块重构后，运行Shannon测试登录、会话管理等接口，发现并修复认证绕过漏洞。

第三方代码安全审计

Problem: 引入开源组件或第三方库时，难以快速评估其安全性，可能存在隐藏的漏洞风险。

Solution: 使用Shannon对包含第三方代码的完整应用进行源码感知的动态测试，识别实际可利用的漏洞。

Example: 在集成新的支付SDK后，用Shannon扫描整个支付流程，发现并验证SSRF漏洞，避免数据泄露。

合规性证据收集

Problem: 为满足SOC 2等合规要求，需要定期提供应用安全测试证据，但手动渗透测试成本高、周期长。

Solution: 利用Shannon自动生成包含可复现漏洞的渗透测试报告，作为合规审计的持续性证据。

Example: 每月运行Shannon对生产应用进行测试，生成详细报告证明已识别并修复了OWASP Top 10中的关键漏洞。

📊 Project Info

Language: TypeScript
Stars: ⭐ 17,166
Forks: 1,811
Today: +4,144
Ranking: #1
Collection: Overall
Trending Date: February 9, 2026
Last Push: 2/9/2026

🏷️ Topics

TypeScript自动化安全测试自主渗透测试源码感知企业级安全开发团队

📸 Screenshots

5分钟上手Shannon AI渗透测试

本指南将帮助你在5分钟内安装并运行Shannon Lite，对示例Web应用进行首次自动化安全测试

🖥️ OS

macOSLinuxWindows (WSL2推荐)

⚙️ Runtime

Node.js>= 18.0

Docker>= 20.10

🔧 Tools

Git— 克隆项目代码

📝 Steps

克隆项目并安装依赖

获取Shannon源代码并安装必要的Node.js依赖包

克隆Shannon仓库

$ git clone https://github.com/KeygraphHQ/shannon.git

进入项目目录

$ cd shannon

安装项目依赖

$ npm install

✓Expected: 看到依赖安装完成，没有错误信息

💡如果遇到权限问题，可以尝试使用sudo或检查Node.js版本

启动测试目标应用

使用Docker启动一个易受攻击的Web应用作为测试目标（OWASP Juice Shop）

启动Juice Shop容器

$ docker run -d -p 3000:3000 bkimminich/juice-shop

✓Expected: 返回容器ID，表示容器已启动

💡确保3000端口未被占用，或使用其他端口如-p 3001:3000

配置Shannon

创建配置文件，指定目标应用地址和测试范围

复制环境配置文件

$ cp .env.example .env

✓Expected: 创建.env配置文件成功

💡可以编辑.env文件自定义配置，首次使用保持默认即可

运行Shannon渗透测试

启动Shannon对目标应用进行自动化安全测试

启动Shannon测试本地Juice Shop应用

$ npm start -- --target http://localhost:3000

✓Expected: 看到Shannon开始分析代码、执行攻击测试的日志输出

💡首次运行可能需要几分钟时间，Shannon会自动完成所有测试步骤

✅ 验证成功

当Shannon完成测试后，会生成详细的渗透测试报告

✓看到'Pentest completed'或类似完成信息
✓在reports目录下找到生成的HTML报告文件
✓报告中包含发现的漏洞详情和利用证明

⚡ Quick Tips

配置首次运行建议使用Juice Shop作为目标，这是专门的安全测试应用

调试测试过程中可以访问http://localhost:3000查看目标应用状态

配置使用--help参数查看所有可用选项：npm start -- --help

🔍 Troubleshooting

❓ Docker命令报错或容器无法启动

→ 确保Docker服务正在运行，尝试重启Docker：sudo systemctl restart docker

❓ npm install失败，依赖安装错误

→ 检查Node.js版本是否符合要求，清理缓存：npm cache clean --force，然后重试

❓ Shannon启动后没有输出或卡住

→ 检查目标应用是否可访问：curl http://localhost:3000，确保端口正确

❓ 权限不足错误

→ 在Linux/macOS上可能需要sudo权限，或检查当前用户是否在docker组中

🎯 Next Steps

查看详细报告

打开reports目录下的HTML报告，查看发现的漏洞详情

测试自己的应用

修改--target参数指向你自己的Web应用进行测试

探索高级配置

查看.env配置文件和命令行选项，自定义测试范围和深度

Difficulty

初级

Est. Time

2-3小时

Target Audience

对Web应用安全感兴趣的开发者、安全测试初学者、希望将自动化安全测试集成到开发流程中的团队

🎯 What You'll Learn

学会使用Shannon Lite对Web应用进行自动化白盒渗透测试，理解其工作原理，并能解读生成的漏洞报告。

📋 Prerequisites

Docker基础了解

Shannon通过Docker容器运行，需要知道如何安装Docker、运行容器和挂载目录。

命令行操作熟悉

需要在终端中执行命令来启动和监控Shannon。

Web应用基础概念了解(optional)

了解什么是Web应用、HTTP协议、以及常见的漏洞类型（如注入、XSS）有助于理解测试结果。

TypeScript/JavaScript了解(optional)

项目使用TypeScript编写，但作为使用者，只需了解基础语法即可，主要用于理解配置和可能的代码调整。

📚 Resources

必看

GitHub README

项目最核心的文档，包含了所有安装、使用、配置、架构说明。

🗺️ Learning Phases

环境准备与项目理解

⏱ 30分钟

安装Docker

根据你的操作系统（Windows/macOS/Linux）安装Docker Desktop或Docker Engine。确保安装后能在终端运行 `docker --version` 命令。

💡Windows用户建议使用WSL2以获得更好的体验。

获取AI API密钥

前往Anthropic控制台注册并获取一个Claude API密钥。这是Shannon的“大脑”，用于分析代码和规划攻击。

💡这是必选项。准备好你的API密钥，后续运行命令时需要设置环境变量。

理解项目定位

仔细阅读README的“What is Shannon?”和“Features”部分，明确Shannon是一个“白盒”测试工具，需要访问源代码，目标是执行真实的攻击来证明漏洞。

💡记住：Shannon Lite是AGPL开源版本，适用于测试自己的应用。

快速启动与首次测试

⏱ 1小时

准备测试目标

准备一个用于测试的Web应用源代码。最简单的方法是使用一个已知的漏洞练习靶场，如OWASP Juice Shop（一个Node.js应用）。将其代码克隆到本地。

💡使用 `git clone https://github.com/juice-shop/juice-shop.git` 可以快速获得一个完美的测试目标。

运行Shannon测试命令

在终端中，导航到你的测试应用代码根目录。运行README中提供的Docker命令，注意替换 `ANTHROPIC_API_KEY` 和源代码路径。命令格式通常为：`docker run -v $(pwd):/src -e ANTHROPIC_API_KEY='your-key' ...`

💡确保 `-v` 参数正确地将你的源代码目录挂载到容器的 `/src` 路径。Windows的PowerShell中 `$(pwd)` 可能需替换为 `${PWD}`。

监控运行过程

命令执行后，观察终端输出。Shannon会依次进行“侦察”、“漏洞分析”、“利用”和“报告”阶段。这个过程可能需要一些时间（取决于应用复杂度）。

💡首次运行可能会下载较大的Docker镜像，请保持网络通畅。运行日志会显示当前进行的阶段和发现的线索。

结果分析与报告解读

⏱ 30分钟

定位并查看报告

测试完成后，Shannon会在源代码目录下生成一个 `audit-logs` 文件夹。根据README，最终的详细报告位于 `deliverables/comprehensivesecurityassessmentreport.md`。

💡在 `audit-logs` 目录中，会按主机名和会话ID组织多次运行的结果，方便对比。

学习解读报告内容

打开生成的Markdown报告。重点关注：发现的漏洞类型（如Injection, XSS）、严重等级、漏洞位置（代码文件、行号）、以及最重要的——可复现的概念验证（PoC）步骤。

💡报告中的PoC是Shannon的核心价值，它展示了如何真实地利用这个漏洞。尝试按照步骤手动验证，加深理解。

进阶探索与配置

⏱ 30分钟

尝试不同配置（可选）

阅读README的“Configuration (Optional)”部分。尝试通过环境变量调整Shannon的行为，例如指定目标URL端口 (`SHANNON_TARGET_URL`)、设置代理或调整超时。

💡首次测试建议使用默认配置。在对工具有基本了解后，再根据测试环境需要进行调整。

理解架构与流程

查看README中的架构图，了解Shannon“侦察->并行漏洞分析->利用->报告”的工作流程。这有助于你理解工具运行时的输出信息。

💡明白这是一个“代码感知”的动态测试工具，它既分析你的源码，又会对运行中的应用发起真实攻击。

⚠️ Common Mistakes

❌ 未正确挂载源代码目录

✅ 确保 `docker run -v` 参数中本地路径正确，且挂载到容器内的 `/src` 目录。在目标应用根目录下执行命令并使用 `$(pwd)` 是最稳妥的方式。

❌ API密钥未设置或格式错误

✅ 确保 `ANTHROPIC_API_KEY` 环境变量已正确设置，且密钥有效（没有多余空格或引号错误）。可以通过 `echo $ANTHROPIC_API_KEY` 检查。

❌ 测试目标应用未运行

✅ Shannon测试的是“运行中”的应用。在启动Shannon前，请确保你的Web应用（如Juice Shop）已经在另一个终端或后台启动并监听端口（如 http://localhost:3000）。Shannon默认会尝试连接 `http://host.docker.internal:3000`，你可能需要根据情况配置 `SHANNON_TARGET_URL`。

❌ Windows Defender误报

✅ 如README所述，生成的报告或日志中可能包含攻击载荷代码，会被Windows Defender误报为病毒。将Shannon的工作目录（包含 `audit-logs` 的目录）添加到Windows Defender的排除列表，或使用WSL2/Docker Desktop的WSL2后端运行。

🚀 Next Steps

学完基础后可以继续探索的方向：1. 将Shannon集成到你的CI/CD流水线中，实现每次构建的自动安全测试。2. 深入研究其架构，了解如何扩展或定制漏洞检测模块。3. 对比使用Shannon Lite和手动/其他自动化工具测试同一应用，评估其效率和准确性。4. 关注项目的Roadmap，了解即将支持的漏洞类型和新功能。5. 如果需要企业级功能（如高级代码分析、CI/CD集成、支持），可以探索Shannon Pro。