deonmenezes/mantishack
GitHub: deonmenezes/mantishack
Mantishack 是一个 AI 驱动的自主渗透测试框架，用于自动化发现和验证软件漏洞。
Stars: 171 | Forks: 37
# Mantishack
`潜伏 · 待机 · 攻击 · 掌控`
**借助AI的力量，以道德的方式黑入并发现任何软件中的漏洞。**
[mantishack.com](https://mantishack.com) ·
上游项目：[github.com/gadievron/raptor](https://github.com/gadievron/raptor)
## 基于 RAPTOR 构建
**Mantishack 是 [RAPTOR](https://github.com/gadievron/raptor) 的一个分支** — 由 Gadi Evron、Daniel Cuthbert、Thomas Dullien (Halvar Flake)、Michael Bargury 和 John Cartwright 开发的递归自主渗透测试与观察机器人。其代理工作流、Semgrep + CodeQL 管道、多阶段验证方法、人设库和离线注册包均源自 RAPTOR。Mantishack 在此基础上继续前进，将面向用户的界面重新品牌化为 `/mantis-*` 斜杠命令词汇，新增了一条自动化的认证+日志审计通道（JWT、Cookie、审计日志覆盖），并以 MIT 许可证发布，同时保留两个版权。
如果您来这里寻找的是官方项目，请访问 [github.com/gadievron/raptor](https://github.com/gadievron/raptor) — 上游开发在那里进行。如果您想改进该框架，请在上游提交 PR。
## 什么是 Mantishack？
Mantishack 是一个基于 Claude Code 构建的自主安全研究框架（但不仅限于此 — 您也可以接入自己的分析层）。它将静态分析、二进制分析、LLM 驱动的漏洞验证、漏洞利用生成和补丁编写串联成一个单一的工作流，您可以针对一个代码库或二进制文件运行它。
它并非打磨完善的软件。上游项目依靠热情和胶带勉强维持，并且运行良好，以至于上游维护者们离不开它。这个分支也一样 — 可以在实地使用，但细节粗糙。请在上游 [gadievron/raptor](https://github.com/gadievron/raptor/issues) 提交问题。
## 快速开始
### 选项 1：手动安装
```
# 克隆仓库
git clone https://github.com/deonmenezes/mantishack.git
cd mantishack
# 安装 Python 依赖项
pip install -r requirements.txt
# 安装 Claude Code (必需)
npm install -g @anthropic-ai/claude-code
# 安装 Semgrep (扫描所需)
pip install semgrep
# 打开 Mantishack
claude
```
### 选项 2：Devcontainer（推荐）
所有内容已预安装。在 VS Code 中使用 **Dev Containers: Open Folder in Container** 打开，或手动构建：
```
docker build -f .devcontainer/Dockerfile -t mantishack:latest .
docker run --privileged -it mantishack:latest
```
`--privileged` 标志是 `rr` 确定性调试器所必需的。镜像很大（约 6 GB）。它基于 Microsoft Python 3.12 devcontainer 构建，并添加了静态分析、模糊测试和浏览器自动化工具。
进入容器后，只需说“hi”即可开始，或直接跳转到一个命令。
## Mantishack 的功能
| 命令 | 功能 | 状态 |
|------|------|------|
| `/mantis-agentic` | 完全自主的工作流：扫描、**认证+日志审计**、验证、漏洞利用、打补丁 | 稳定 |
| `/mantis-scan` | 使用 Semgrep 和 CodeQL 进行静态分析 | 稳定 |
| `/mantis-auth-audit` | **自动 JWT + Cookie + 审计日志安全检查** | 稳定（分支新增） |
| `/mantis-understand` | 绘制攻击面，追踪数据流，寻找漏洞变体 | 稳定 |
| `/mantis-validate` | 多阶段漏洞利用可行性验证管道（阶段 0–F） | 稳定 |
| `/mantis-codeql` | 仅使用 CodeQL 的深度分析，配合 SMT 数据流预筛选 | 稳定 |
| `/mantis-exploit` | 生成概念验证漏洞利用代码 | Beta |
| `/mantis-patch` | 为已确认的漏洞生成安全补丁 | Beta |
| `/mantis-fuzz` | 使用 AFL++ 进行二进制模糊测试和崩溃分析 | 稳定 |
| `/mantis-crash-analysis` | 针对 C/C++ 崩溃的自主根本原因分析 | 稳定 |
| `/mantis-oss-forensics` | 针对 GitHub 仓库的证据支持的取证调查 | 稳定 |
| `/mantis-project` | 命名的工作区，用于组织运行和长期跟踪发现结果 | 稳定 |
| `/mantis-sca` | 软件成分分析 | 稳定 |
| `/mantis-cve-diff` | 在已知 CVE 修复中比较扫描器运行结果 | 稳定 |
| `/mantis-web` | Web 应用扫描 | Alpha/桩 |
## 管道工作原理
首先创建一个项目，这样所有运行都会归集到一处：
```
/mantis-project create myapp --target /path/to/code # create a project first
/mantis-project use myapp # set it as active
/mantis-understand --map # map the attack surface
/mantis-agentic # scan, audit, validate, exploit, patch
/mantis-project findings # review everything in one place
```
在开始任何扫描之前，`/mantis-understand` 会构建一个上下文映射，包括入口点、信任边界和汇聚点。然后 `/mantis-agentic` 运行 Semgrep 和 CodeQL，**自动执行认证+日志审计通道**，对发现结果进行去重，并使用漏洞利用验证器方法论将每个发现分派进行验证：
- 阶段 A：该模式确实是漏洞，还是工具的模式匹配噪声？
- 阶段 B：攻击者需要什么才能触达它？有什么阻碍？
- 阶段 C：代码路径是否真实存在？能否从外部触达？
- 阶段 D：最终判定 — 这是测试代码吗？是否需要不现实的前提条件？模型是否在回避？
通过验证的发现将生成漏洞利用 PoC 和补丁。最后会进行跨发现分析，以找到共同的根本原因和攻击链。
如果您已有之前的扫描结果，`/mantis-validate` 可以作为独立步骤运行此相同管道。
## 认证 + 日志审计（分支新增）
Mantishack 在每次调用 `/mantis-agentic` 时都会自动运行一个 **认证+日志审计**。相同的检查也作为独立的 `/mantis-auth-audit` 斜杠命令暴露出来，以便进行更快、更有针对性的运行。
该通道使用标签为 `mantis_capability: auth-audit` 的 Semgrep 规则，以及 pytest fixtures 来在运行时断言审计日志覆盖。它查找的内容包括：
**JWT** — `engine/semgrep/rules/auth/jwt-misuse.yaml`
- 接受 `alg=none`（令牌伪造）
- 硬编码的 HMAC 密钥（暴力破解密钥恢复）
- 缺少 `exp` 声明（令牌永不过期）
- 无 audience / issuer 绑定（跨租户令牌接受）
**Cookie** — `engine/semgrep/rules/auth/cookie-security.yaml`
- 缺少 `HttpOnly`（可被 XSS 窃取）
- 缺少 `Secure`（通过明文 HTTP 暴露）
- 缺少 `SameSite`（CSRF）
- 会话 ID 通过 URL 查询参数传递（引用 / 日志泄漏）
**日志记录** — `engine/semgrep/rules/logging/missing-auth-audit.yaml`
- 认证失败分支无日志记录
- 特权操作（删除 / 角色变更 / `is_admin = True`）无审计日志
- 原始 JWT / bearer / `session_id` 被写入日志（凭证泄漏）
**Pytest 测试工具** — `conftest.py`
- `@pytest.mark.auth_audit` 标记 + `assert_audit_log_emitted` fixture：如果练习认证敏感代码路径的测试在 (a) 没有发出 INFO/WARN 日志，或 (b) 任何日志记录包含原始 JWT / session id / bearer token 时，将导致运行失败。
pytest hook 的用法示例：
```
import pytest
@pytest.mark.auth_audit
def test_login_logs_failure(client, assert_audit_log_emitted):
client.post("/login", data={"u": "alice", "p": "wrong"})
# fixture teardown asserts an audit log was emitted and no credential leaked
```
运行独立审计：
```
python3 mantishack.py scan --repo /path/to/code \
--rules engine/semgrep/rules/auth \
--rules engine/semgrep/rules/logging \
--tag auth-audit
```
## Z3 SMT 集成
Mantishack 继承了 RAPTOR 的两层 Z3 集成（`pip install z3-solver`）。它是可选的。没有它一切也能工作，但有了它结果会更好。
**数据流预筛选 (CodeQL)** — 当 CodeQL 产生路径结果时，在进行任何 LLM 调用之前会检查路径约束的可满足性。可证明不可达的路径会立即被丢弃。对于可达的路径，Z3 生成具体的候选输入，这些输入会进入分析提示。
**单 gadget 约束分析（二进制可行性）** — 在二进制漏洞利用可行性评估期间，Z3 检查一个 gadget 的寄存器和内存约束是否与具体的崩溃状态可满足。Gadgets 按实际可达性而不是启发式方法进行排名。
Z3 已在 devcontainer 中预安装。对于手动安装：`pip install z3-solver`。
## 在离线和气隙管道中运行
Semgrep 扫描完全离线工作。所有通常在扫描时从 semgrep.dev 获取的注册包都打包在仓库的 `engine/semgrep/rules/registry-cache/` 下。扫描器在调用 semgrep 之前将包 ID 解析到本地文件，因此不会发生网络调用。
缓存的包：`p/security-audit`, `p/owasp-top-ten`, `p/secrets`, `p/command-injection`, `p/jwt`, `p/default`, `p/xss`。
CodeQL 仅在初始设置期间需要网络访问以下载 CLI 和查询包。安装后即可离线运行。
## 使用不同的 LLM
Mantishack 继承了 RAPTOR 的两个独立模型层：
**编排层** 始终是 Claude Code。CLAUDE.md、技能和命令都作为 Claude Code 指令运行。要更改编排 Mantishack 的 Claude 模型，请使用 Claude Code 的 `--model` 标志或在会话中使用 `/model` 命令。
**分析分派层** 是分析单个漏洞发现结果的 LLM。这与编排层是分开的，可以是任何受支持的提供商。在 `~/.config/mantishack/models.json` 中进行配置：
```
{
"models": [
{
"provider": "anthropic",
"model": "claude-opus-4-6",
"api_key": "sk-ant-...",
"role": "analysis"
},
{
"provider": "openai",
"model": "gpt-5.4",
"api_key": "sk-...",
"role": "analysis"
},
{
"provider": "anthropic",
"model": "claude-sonnet-4-6",
"api_key": "sk-ant-...",
"role": "aggregate"
}
]
}
```
或者跳过配置文件，直接设置环境变量：
```
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...
export MISTRAL_API_KEY=...
export OLLAMA_HOST=http://localhost:11434
```
预算控制：
```
export MANTISHACK_MAX_COST=5.00 # cap analysis spend at $5 per run
```
## 架构
Mantishack 有两层。
**Python 执行层**（`mantishack.py`, `packages/`, `core/`, `engine/`）处理繁重的任务：运行 Semgrep 和 CodeQL、管理子进程、解析 SARIF、对发现结果去重、分派 LLM API 调用、跟踪成本、写入输出文件。它不做决策，只执行。
**Claude Code 决策层**（`.claude/`, `tiers/`, `CLAUDE.md`）做出调用：优先处理哪些发现、如何解释结果、攻击场景是什么、漏洞利用是否现实。实现为 Claude Code 技能、命令和代理，并渐进式加载。
```
CLAUDE.md always loaded — bootstrap, routing, security rules
.claude/commands/ slash commands (/mantis-agentic, /mantis-scan, …)
.claude/skills/ methodology detail, loaded on demand
tiers/ adversarial thinking, recovery, expert personas
.claude/agents/ specialist sub-agents (offsec, crash analysis, forensics)
```
这种分离意味着您可以从 CI 管道运行 Python 层（`python3 mantishack.py scan --repo ...`）并获得结构化的 SARIF 输出而无需 Claude Code，或者以交互方式运行完整的代理工作流。
## 许可证
MIT，双版权：
- **上游 RAPTOR 代码** — 版权所有 (c) 2025-2026 Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake), Michael Bargury, John Cartwright。见 [`LICENSE`](./LICENSE)。
- **分支修改**（mantishack 品牌化、`/mantis-*` 重命名、认证+日志审计规则、pytest fixtures、README/NOTICE）— 版权所有 (c) 2026 Deon Menezes。见 [`LICENSE-MANTISHACK`](./LICENSE-MANTISHACK)。
两个文件都是 MIT 许可证；分支修改许可证与上游 RAPTOR 许可证并列，不取代它。参见 [`NOTICE`](./NOTICE) 了解组合的归属信息和分支修改日志。商业使用前请审查所有依赖项的许可证 — **特别是 CodeQL 不允许商业使用**。
**上游：** https://github.com/gadievron/raptor — 请在上游提交框架级别问题和 PR。
**Mantishack 分支问题：** https://github.com/deonmenezes/mantishack/issues
## 项目历史
早期的 mantishack 版本是作为独立的 Rust 守护进程 + MCP 代理栈运行的，并且**借鉴了许多开源项目**。该架构已被弃用并从此仓库中删除；您在这里看到的代码库是 [RAPTOR](https://github.com/gadievron/raptor)（MIT）的完全品牌重塑。以下致谢是历史性的 — 当前代码树中不再包含这些项目的代码（RAPTOR 有自己的依赖集，列在 [`requirements.txt`](./requirements.txt) 中）— 但它们塑造了 mantishack 曾经的样子，我们在此诚实地予以致谢。
**主要衍生：**
- [vmihalis/hacker-bob](https://github.com/vmihalis/hacker-bob) (Apache-2.0) — 代理提示、角色提示、斜杠命令、能力手册惯例、链式尝试结果枚举、严重性梯度规则和 `bob-hunt` 工作流形态均衍生自 Hacker Bob。
**AI 模型和 LLM 生态系统：**
- [Nous Research — Hermes](https://huggingface.co/NousResearch) (Hermes 2/3 系列，各种许可证)
- [Anthropic Claude](https://www.anthropic.com/) (通过 API + Claude Code 的宿主 LLM)
- [OpenAI Codex CLI](https://github.com/openai/codex) (Apache-2.0)
- [OpenCode](https://opencode.ai/)
- [模型上下文协议 (MCP)](https://github.com/modelcontextprotocol) 规范 + [rmcp](https://github.com/modelcontextprotocol/rust-sdk) Rust SDK (MIT)
**操作系统和运行时：**
- [Linux 内核](https://kernel.org/) (GPL-2.0)
- [GNU 用户空间 / glibc / musl](https://www.gnu.org/)
- [Rust 工具链](https://www.rust-lang.org/) (Apache-2.0 / MIT)
- [Node.js](https://nodejs.org/)、[Bun](https://bun.sh/)、[Deno](https://deno.com/) (MIT)
- [Docker](https://www.docker.com/) / [OCI](https://opencontainers.org/) (Apache-2.0)
- [Homebrew](https://brew.sh/) (BSD-2-Clause)
**加密与完整性：**
- [BLAKE3](https://github.com/BLAKE3-team/BLAKE3)、[ed25519-dalek](https://github.com/dalek-cryptography/ed25519-dalek)、[ring](https://github.com/briansmith/ring)、[rustls](https://github.com/rustls/rustls)、[zeroize](https://github.com/RustCrypto/utils/tree/master/zeroize)
**Rust 异步生态系统和核心库：**
- [Tokio](https://tokio.rs/)、[Tower](https://github.com/tower-rs/tower)、[Hyper](https://hyper.rs/)、[reqwest](https://github.com/seanmonstar/reqwest)、[Serde](https://serde.rs/) + [serde_json](https://github.com/serde-rs/json) / [serde_yaml_ng](https://github.com/acatton/serde-yaml-ng) / [toml](https://github.com/toml-rs/toml)、[Tonic](https://github.com/hyperium/tonic) + [Prost](https://github.com/tokio-rs/prost)、[anyhow](https://github.com/dtolnay/anyhow)、[thiserror](https://github.com/dtolnay/thiserror)、[tracing](https://github.com/tokio-rs/tracing)、[clap](https://github.com/clap-rs/clap)、[schemars](https://github.com/GREsau/schemars)
**存储：**
- [RocksDB](https://rocksdb.org/) + [rust-rocksdb](https://github.com/rust-rocksdb/rust-rocksdb)
- [Supabase](https://supabase.com/) (着陆页认证 + Postgres)
**调用 / 集成的攻击性安全工具：**
- ProjectDiscovery: [subfinder](https://github.com/projectdiscovery/subfinder)、[httpx](https://github.com/projectdiscovery/httpx)、[katana](https://github.com/projectdiscovery/katana)、[nuclei](https://github.com/projectdiscovery/nuclei) + [nuclei-templates](https://github.com/projectdiscovery/nuclei-templates)、[chaos](https://github.com/projectdiscovery/chaos-client)、[dnsx](https://github.com/projectdiscovery/dnsx)、[interactsh](https://github.com/projectdiscovery/interactsh)、[notify](https://github.com/projectdiscovery/notify)
- [OWASP Amass](https://github.com/owasp-amass/amass) (Apache-2.0)
- [ticarpi/jwt_tool](https://github.com/ticarpi/jwt_tool) (GPL-3.0, 仅子进程)
- [OJ/gobuster](https://github.com/OJ/gobuster) (Apache-2.0)
- [Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright) (无头浏览器自动化)
- [Bearer](https://github.com/Bearer/bearer) (Elastic-2.0)
- [Trivy](https://github.com/aquasecurity/trivy) (Apache-2.0)
- [trufflehog](https://github.com/trufflesecurity/trufflehog) (AGPL-3.0)
- [hashcat](https://hashcat.net/) (MIT)
- [Hydra](https://github.com/vanhauser-thc/thc-hydra) (AGPL-3.0)
**标准、分类、报告格式：**
- [CVSS v3.1 / v4](https://www.first.org/cvss/) (FIRST.org)
- [CWE](https://cwe.mitre.org/) (MITRE)
- [SARIF v2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/) (OASIS)
- [OpenVEX](https://github.com/openvex/spec)
- [HackerOne 报告模式](https://api.hackerone.com/)
- [Bugcrowd VRT](https://bugcrowd.com/vulnerability-rating-taxonomy)
- [OWASP Top 10](https://owasp.org/Top10/)
**Web 技术栈（旧版着陆页和仪表板）：**
- [Vite](https://vitejs.dev/)、[React](https://react.dev/)、[TypeScript](https://www.typescriptlang.org/)、[Tailwind CSS](https://tailwindcss.com/)、[shadcn/ui](https://ui.shadcn.com/)、[Radix UI](https://www.radix-ui.com/)、[lucide-react](https://lucide.dev/)、[Supabase JS SDK](https://github.com/supabase/supabase-js)
**分发和 CI：**
- [GitHub Actions](https://github.com/features/actions)、[GitHub CLI](https://github.com/cli/cli)、[cargo-chef](https://github.com/LukeMathWalker/cargo-chef)、[cargo-deny](https://github.com/EmbarkStudios/cargo-deny)、[rustup](https://rustup.rs/)
如果我们借鉴了未在此列出的项目，请提交 issue — 我们希望此列表反映实际情况。
标签：AI驱动的安全, Exploit生成, JWT安全, LLM, Mantishack, Maven, RAPTOR分支, SQL查询, Unmanaged PE, 二进制分析, 云安全监控, 云安全运维, 人工智能, 审计日志, 情报收集, 漏洞研究, 漏洞验证, 用户模式Hook绕过, 系统运维工具, 结构化查询, 网络安全, 自主安全研究, 自动化安全, 补丁编写, 请求拦截, 逆向工具, 隐私保护, 静态分析