VulnClaw - 基于 AI Agent + MCP 工具链 + 渗透 Skill 编排， 配合大语言模型， 自然语言

项目说明

<di="center">

🦞

> *AI 驱动的渗透测试 CLI 工具 — 说人话，打漏洞。*

![Python 3.10+]()
![OpenAI Compatible]()
![MCP]()
![PyPI]()
![codecov]()
![Discord]()
![AtomGitStars]()
<picture>
<source media="(prefers-color-scheme: dark)" srcset="
<img alt="Kimi Open Source Friends" src="
</picture>
<br>

🌐 English : README_EN.md

本项目是可独立运行的 AI 渗透测试 Agent。
<br>
项目官网：
<br>

基于 LLM Agent + MCP 工具链 + 可选 Skill 参考资料，
配合 OpenAI / Anthropic / MiniMax / DeepSeek 等兼容模型，
自然语言输入 → 自动完成「信息收集 → 漏洞发现 → 漏洞利用 → 报告生成」全流程。

快速开始 · 架构 · 内置 Skill

</div>

---

它能做什么

输入自然语言，AI 自动执行渗透测试全流程：

<img width="1148" height="642" alt="image" src=" />

<img width="2521" height="1300" alt="image" src=" />

适用于已授权的渗透测试、CTF 竞赛、安全教学、红队演练等场景。

---

特性

---

快速开始

安装

Docker 运行（可选）

镜像已内置 Web UI 以及默认 MCP 服务所需的运行时（npx / uvx），所有状态持久化到 /data 数据卷。

也可用纯 docker 运行某条 CLI 命令：

> ⚠️ 容器内的 localhost 指向容器自身。扫描宿主机服务请使用 host.docker.internal，扫描其它容器请共享网络并用容器名访问。详见 DOCKER.md。

四步启动

环境检查

输出示例：

---

CLI 命令速查

| 命令 | 说明 | 示例 |
|------|------|------|
| | 默认打开原 CLI / REPL | |
| tui | 终端图形化工作台 | tui --target target.com |
| repl | 启动经典 REPL 交互界面 | repl |
| solve <target> | 目标驱动求解（无固定轮数，拿到目标即停） | sol.com --goal "拿到flag" |
| run <target> | 一键全流程渗透（默认走 solve 引擎） | run 192.168.1.1 |
| persistent <target> | 持续性渗透（100轮/周期） | persistent 192.168.1.1 |
| recon <target> | 仅信息收集（不利用漏洞） | recon target.com |
| scan <target> | 漏洞扫描阶段 | scan target.com --ports 80,443 |
| exploit <target> | 漏洞利用阶段 | exploit target.com --c |
| report <session> | 从会话 JSON 生成报告 | report session_xxx.json |
| config set <key> <value> | 设置配置项 | config set llm.api_key sk-xxx |
| config provider <name> | 切换 LLM 提供商 | config provider minimax |
| plugins list | 列出漏洞检测插件 | plugins list --stage discovery |
| plugins info <id> | 查看插件元信息 | plugins info builtin.web.headers |
| plugins run <id> | 运行插件（仅分析传入数据） | plugins run builtin.web.headers --input headers.json |
| code scan <path> | 本地源码安全扫描（L1 正则 / L2 结构 / L3 LLM 可选） | code scan ./src --format sarif |

---

使用方式

方式一：CLI / REPL（默认）

无参数启动会进入 🦞 交互界面，用自然语言对话：

REPL 内置命令：

| 命令 | 说明 |
|------|------|
| target <host> | 设置渗透测试目标 |
| status | 查看当前状态 |
| tools | 列出当前可用 MCP 工具 |
| think on/off | 切换推理过程显示 |
| mode [模式] | 查看或切换执行审批模式（ask / auto_review / full_access） |
| persistent | 启动持续性渗透测试 |
| clear | 清空当前会话 |
| help | 显示帮助信息 |
| exit / quit / q | 退出 |

自动渗透触发： 输入包含「渗透测试」「找 flag」「爆破」等关键词 + 目标地址时，自动进入多轮自主渗透循环。Ctrl+C 随时中断。

方式二：TUI 工作台

可选的终端图形化工作台，展示授权目标、检查模式、运行概览、安全边界，让用户先确认范围再启动任务。

Rust TUI 工作台支持可配置容器布局：左侧默认显示状态，右侧同时显示发现与子代理；中间显示代理输出，底部为输入框。子代理视图目前显示无数据提示。

鼠标捕获开启时，终端原生文字选择取决于终端提供的修饰键；复制单个视图可使用 Ctrl+Y。Windows 终端下 Ctrl+V / Shift+Insert / 鼠标右键直接读取系统剪贴板粘贴到输入框（Win32 API 直读，微秒级；该平台无 bracketed paste，不依赖终端是否合成击键）；Unix 终端粘贴走 bracketed paste。

常用菜单：

方式三：单命令模式

方式四：持续性渗透

适用于需要长时间深度渗透的场景，以周期循环方式运行：

特点： 跨周期状态保持 / 周期报告 / 灵活中断 / 增量发现 / 可配置

方式五：Web UI

通过浏览器操作渗透测试全流程。

PyPI wheel 不包含 React 构建产物或前端源码；完整 Web UI 需要按上面的源码方式安装。
若浏览器显示 Fallback Web Shell（无完整扫描界面），说明缺少
frontend/dist/index.html。按上式构建后重启 web 并强制刷新。
未构建前端时，/api/health 等 API 仍可用。

> ⚠️ 默认仅绑定本地回环地址。如需远程访问须显式指定 --host 0.0.0.0 --allow-remote。

---

架构

求解引擎

默认使用模型主导 solve 引擎（旧版固定轮数引擎可通过 config set session.engine rounds 回退）。

模型主导循环： 框架不再把任务拆成固定“研究方向”，也不再按阶段模板主动安排目录扫描、JS 收集或 SQLi 测试。solve 只给模型提供目标、历史上下文、证据记忆和可用工具清单，由模型自己决定下一步行动。

| 原语 | 含义 |
|------|------|
| 模型上下文 | 目标、用户约束、近期消息、证据摘要和已执行工具调用 |
| 工具清单 | fetch / 浏览器 / 目录枚举 / JS 收集 / 编解码 / Python / shell_command / source_extract / runtime_diff_probe / skill 读取等能力，仅作为可选手脚暴露给模型 |
| 工具 transcript | 工具调用后会把 assistant tool_calls 与 role=tool 观察结果追加进模型上下文；大输出使用高信号预览，避免 HTML/body/日志反复污染 acti |
| AgentState 证据 | 每个真实工具结果都会写入 AgentState.e；raw 原文完整保留并带 hash/size/证据号，模型可通过 e / e 按需回查 |
| 高信号记忆 | 源码 SQL、HTML 表单/input、PHP/API 链接、Ja endpoint、highlight_file 源码、unserialize/魔术方法/危险 sink 会被固定为长期可见事实，避免后续探测把真实入口淹没 |
| 轻量纠偏层 | 只观察工具生命周期，记录耗时、失败降级、重复调用、高信号目标事实和小步语义差异，作为提示信号注入下一轮上下文，不做阶段规划、不主动安排工具 |
| 证据闸门 | FINAL: 结论必须引用或命中真实证据；未被工具输出支撑的 flag/结论会被拒绝并继续探索 |
| 自动复盘报告 | 目标达成后自动生成 Markdown 报告，包含解题思路、关键证据、复现请求包、curl、响应片段和证据索引 |

上下文策略： solve 默认保留正常对话历史，不主动压缩。只有模型上下文接近上限、用户执行 /compact 或显式启用自动压缩时才压缩。工具输出会完整写入 AgentState.e，但大输出进入 acti 时只注入 bounded high-signal preview，包含状态、响应头/请求面、表单/参数、endpoint、源码 sink/filter、flag-like token、关键行号、raw size 和 hash；完整 body/stdout/stderr 可通过 e 搜索或 e 分页回看。fetch / http_probe_batch 的 max_body_chars、python_execute_max_output_chars 和 shell_command.max_output_chars 只有显式设为正数时才会在工具层裁剪 raw 输出；未显式裁剪时 raw e 仍完整保留。相同 raw 输出再次出现时，acti 只保留 same_as=eXXX 引用，不重复塞正文。终端回显只是人类显示层：长工具结果默认折叠为预览，完整内容保存在 e。从原始输出里提取出的高信号事实会独立固定，包括表单、参数、JS endpoint、PHP/API 链接、highlight_file 源码、危险 sink、请求面、same-body/响应差异和本地 proof 片段。e / e / e 用于回看历史证据，重复查看同一 e 覆盖范围会被短路，连续多轮只翻证据且没有新 e 会触发 stall guard，要求下一步改用非 e 工具、FINAL、ASK_USER 或 NO_PATH。工具调用执行后不会再强制追加一轮 Summarizing... LLM 调用；正常路径采用 Chat Completions 原生工具 transcript（assistant tool_calls + role=tool），让下一次模型采样基于真实观察继续。

证据级反幻觉闸门： 录制所有真实工具输出作为唯一可信证据。声称的 flag/结论必须在真实输出里逐字符出现或显式引用证据编号才会被采信，杜绝凭空编造。NO_PATH 也受近成功闸门约束：当证据中仍有未耗尽的高信号锚点时，会先把拒绝原因反馈给模型继续验证，而不是直接停止。

自动复盘报告： solve 达成目标后会基于 AgentState 确定性生成 Markdown 复盘报告并默认打印到终端。报告不会额外请求 LLM；复现请求包、curl 和响应片段来自真实 fetch / http_probe_batch e。

授权红队 Skill： codex-redteam-mode 的授权红队 detail packs 已作为 skill/知识库导入，供模型按需读取；jailbreak、拒绝绕过、会话 patch 等破限内容未导入。

核心模块

| 模块 | 文件 | 说明 |
|------|------|------|
| CLI/TUI 入口 | cli/main.py + cli/tui.py | Typer 命令 + REPL + TUI |
| Agent 核心 | agent/core.py | AgentCore 协调入口 |
| 求解引擎 | agent/solver.py + agent/agent_state.py | 模型主导循环 + AgentState 证据/步骤/完成闸门 |
| 推理/反思 | agent/reasoning_state.py + reflexion.py | 结构化事实/约束/攻击链 + L0-L4 升级 |
| 插件体系 | plugins/ | 低耦合漏洞检测插件运行时 |
| Skill 参考索引 | skills/loader.py + resolver.py | 只解析相关参考资料，不注入强制流程 |
| MCP 编排 | mcp/registry.py + lifecycle.py + router.py | 服务注册 + 生命周期 + 工具路由 |
| 配置管理 | config/schema.py + settings.py | Pydantic + YAML + 14 Provider 预设 |
| 报告生成 | report/generator.py + poc_builder.py | Markdown 报告 + PoC 脚本 |
| 安全知识库 | kb/store.py + retriever.py + ranking.py | JSON 存储 + 中文感知 BM25 检索 + 可选重排序 |

---

MCP 工具链

| MCP 服务 | 工具数 | 模式 | 用途 | 状态 |
|---|---|---|---|---|
| fetch | 1 | 本地 (httpx) | HTTP/HTTPS 请求、GET/POST/PUT 等方法、headers/params/cookies/body/json/form、API 测试 | 开箱即用 |
| memory | 2 | 本地 (JSON) | 上下文记忆、状态持久化 | 开箱即用 |
| chrome-de | 31+ | stdio MCP | 浏览器自动化、截图、JS 执行 | 需部署 |
| burp | 多个 | stdio MCP | HTTP 抓包、重放、漏洞扫描 | 需部署 |

> 另有内置 Agent 工具（http_probe_batch、python_execute、shell_command、source_extract、runtime_diff_probe、nmap_scan、crypto_decode、brute_force_login、load_skill_reference、e、e、e 等），无需 MCP 即可调用。

<details>
<summary><strong>Chrome De MCP 部署</strong></summary>

前置条件: Node.js LTS (v20+) + Chrome 浏览器

如需指定 Chrome 调试地址，编辑 ~/./config.yaml：

</details>

<details>
<summary><strong>Burp Suite MCP 部署</strong></summary>

前置条件: Java 11+ + Burp Suite Professional

建议配置：

</details>

> 详细部署说明参见 docs/mcp-deployment.md

---

内置 Skill

核心 Skill (7)

| Skill | 说明 |
|-------|------|
| pentest-flow | 渗透测试全流程编排 |
| recon | 信息收集流程 |
| | 漏洞发现流程 |
| exploitation | 漏洞利用流程 |
| post-exploitation | 后渗透流程 |
| reporting | 报告生成流程 |
| waf-bypass | WAF 绕过技巧库 |

专项 Skill (16)

| Skill | 参考文档数 | 说明 |
|-------|-----------|------|
| web-pentest | 3 | Web 应用渗透 |
| android-pentest | 9 | 安卓应用渗透 |
| client-reverse | 20 | 客户端逆向分析 |
| web-security-ad | 33 | Web 安全进阶（注入、绕过、利用链） |
| ai-mcp-security | 7 | AI/MCP 安全测试 |
| intranet-pentest-ad | 15 | 内网渗透进阶 |
| pentest-tools | 16 | 渗透工具速查 |
| rapid-checklist | 2 | 快速检查清单 |
| crypto-toolkit | 3 | 编解码/加解密（29 种操作） |
| ctf-web | 8 | CTF Web 攻击知识库 |
| ctf-crypto | 6 | CTF 密码学攻击知识库 |
| ctf-misc | 6 | CTF 杂项知识库 |
| osint-recon | 7 | OSINT 开源情报收集 |
| c | 1 | CVE 查询与三级评估 |
| hackerone | 1 | HackerOne 赏金 scope-guard |
| secknowledge-skill | 40 | Web+AI 安全测试知识库 |

Skill 会根据用户输入解析为“可选参考资料索引”，不会把 Skill 正文、阶段流程或方法论剧本自动塞进系统提示。专项 Skill 含 references/ 目录下的详细方法论文档，LLM 只有在自己判断有价值时才通过 load_skill_reference 按需加载。

内置编解码/加解密工具 (crypto_decode)

| 类别 | 操作 |
|------|------|
| 编解码 | base64, base32, base58, hex, url, html, unicode, rot13, caesar, morse（各有 encode/decode） |
| 哈希 | md5, sha1, sha256, sha512 |
| 加解密 | aes_encrypt, aes_decrypt（CBC 模式，PKCS7 填充） |
| JWT | jwt_decode, jwt_encode |
| 自动识别 | auto_decode — 尝试所有常见编码，返回匹配结果 |

---

配置管理

LLM 提供商

| 提供商 | 命令 | 默认模型 |
|--------|------|----------|
| OpenAI | provider openai | gpt-5.6-sol |
| Anthropic Claude | provider anthropic | claude-opus-5 |
| MiniMax | provider minimax | MiniMax-M3 |
| DeepSeek | provider deepseek | deepseek- |
| 智谱 GLM | provider zhipu | glm-5.3 |
| Kimi | provider moonshot | kimi-k3 |
| 通义千问 | provider qwen | qwen3.8-max |
| SiliconFlow | provider siliconflow | deepseek-ai/DeepSeek- |
| 豆包 | provider doubao | doubao-seed-e |
| 阶跃星辰 | provider stepfun | step-3.7-flash |
| 商汤 | provider sensetime | SenseNova-V6.5-Pro |
| OpenRouter | provider openrouter | anthropic/claude-opus-5 |
| Ollama (本地) | provider ollama | qwen3.5:9b |
| 自定义 | provider custom | 手动填写 |

命令行配置

执行审批（免确认执行）

危险工具（shell / python / PoC）每次执行前默认会弹出 Approve this execution? [y/N] 确认。三种调整方式：

| 模式 | 行为 |
|------|------|
| ask（默认） | 每次执行都询问 y/N，未响应 300 秒（safety.appro）自动拒绝 |
| auto_review | 只读命令白名单（ls / cat / nmap 扫描类等）直接执行，其余仍询问；可用 safety.trusted_commands 扩充前缀 |
| full_access | 全部直接执行，不再询问 |

> ⚠️ full_access 下，渗透目标返回的页面、响应体、报告内容都属于不可信输入，提示注入可能驱动无确认的任意命令执行。仅建议在隔离靶场、CTF 或一次性虚拟机中使用；真实环境推荐 auto_review + 自定义信任前缀。

可配置项

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| llm.provider | openai | LLM 提供商 |
| llm.api_key | 空 | API Key |
| llm.auth_mode | static | static 或 oauth |
| llm.chatgpt_auto_proxy | false | 自动启动内置 ChatGPT 后端桥接代理 |
| llm.base_url | 按 provider | API 基础 URL |
| llm.model | 按 provider | 模型名称 |
| llm.temperature | 0.1 | 采样温度 |
| llm.max_tokens | 4096 | 单次最大输出 token |
| session.engine | solve | solve（模型主导）/ team（角色团队）/ rounds（旧固定轮数） |
| session.sol | 240 | solve 防失控安全预算；不是计划轮数，正常由模型自主完成/询问/判定无路 |
| session.sol | 3 | 兼容旧配置；默认模型主导 solve 不再使用研究方向数量 |
| session.sol | 6 | 兼容旧配置；单个模型 turn 内连续工具 follow-up 的 runaway 安全上限，不是计划式工作流轮数 |
| session.context_auto_compact | true | 是否允许所有 LLM 调用路径自动压缩上下文 |
| session.context_compact_trigger_ratio | 0.70 | 自动压缩的上下文触发比例 |
| session.context_compact_target_ratio | 0.55 | 压缩完成后的目标上下文占用比例 |
| session.context_recent_message_groups | 12 | 每次压缩保留的最近完整消息组数量 |
| session.context_summary_max_tokens | 3500 | 长期结构化上下文摘要的最大 token 预算 |
| session.context_output_reser | 0 | 为模型输出预留的 token；0 时取 min(llm.max_tokens, 8192) |
| session.context_compaction_audit_enabled | true | 是否在持久化 AgentState 中记录压缩审计事件 |
| session.sol | true | solve 目标达成后自动生成 Markdown 复盘报告 |
| session.sol | true | 自动报告生成后在终端直接打印报告正文 |
| session.max_rounds | 15 | 最大轮数 |
| session.output_dir | ./ | 报告输出目录 |
| session.report_format | markdown | 报告格式（markdown / html） |
| session.poc_language | python | PoC 生成语言（python / bash） |
| session.language | auto | 界面语言（auto / zh / en），默认英文 |
| session.show_thinking | false | 显示 LLM 推理过程 |
| session.persistent_rounds_per_cycle | 100 | 持续性渗透每周期轮数 |
| session.persistent_max_cycles | 10 | 持续性渗透最大周期数（0=无限） |
| session.persistent_auto_report | true | 持续性渗透每周期自动生成报告 |
| session.stale_rounds_threshold | 5 | 死循环检测阈值 |
| safety.permission_mode | ask | 危险工具执行审批策略：ask（默认，每次执行需 y/N 确认）/ auto_review（只读命令白名单免确认，其余仍询问）/ full_access（全部直接执行，无确认） |
| safety.appro | 300 | 未响应的执行审批等待多少秒后自动拒绝 |
| safety.trusted_commands | 空 | auto_review 模式下的免审批命令前缀（如 nmap、git diff）；以禁用名开头的条目会被拒绝 |
| safety.enable_python_execute | true | 启用 python_execute 内置工具（关闭更安全） |
| safety.python_execute_max_lines | 50 | 单次 python_execute 允许的最大代码行数 |
| safety.python_execute_show_warning | true | 每次 python_execute 前显示安全警告 |
| safety.python_execute_audit_enabled | true | 将 python_execute 审计记录写入本地配置目录 |

环境变量

| 变量 | 说明 |
|------|------|
| | LLM 提供商名称 |
| | API Key |
| | static / oauth |
| O_PROXY | 内置 ChatGPT 代理 |
| | API 基础 URL |
| | 模型名称 |
| NDS | 最大轮数 |
| OUNDS_THRESHOLD | 死循环检测阈值 |
| NG_STATE_ENABLED | 结构化推理状态开关 |
| ON_ENABLED | 自适应反思引擎开关 |
| ON_MAX_SAME_ | 同类漏洞连败触发反思阈值 |
| ION_MAX_LEVEL | Payload 升级上限（0-4） |
| RUNTIME_ENABLED | 插件运行时开关 |
| MAX_REQUESTS_PER_TARGET | 单目标插件请求预算 |
| ON_MODE | 执行审批模式（ask / auto_review / full_access） |
| _TIMEOUT_SECONDS | 执行审批等待秒数 |
| COMMANDS | auto_review 免审批命令前缀（逗号分隔） |

优先级：环境变量 > 配置文件 > 内置默认值

配置文件位于 ~/./config.yaml。

---

更新日志

完整更新日志见 CHANGELOG.md。

---

贡献指南

欢迎参与开源贡献！提交 PR 前请阅读 CONTRIBUTING.md（中文）或 CONTRIBUTING_EN.md（英文）。

项目使用 dev 分支进行集成测试，所有 PR 请提交到 dev 分支。

---

安全声明

公开 Alpha 阶段： 是面向已授权安全测试、CTF、实验环境与可控研究场景的公开
Alpha 软件，不应作为生产环境的安全控制手段或授权机制。使用前请阅读
SECURITY.md。

仅用于已授权的安全测试。使用本工具前，请确保：

1. 你已获得目标系统的明确授权
2. 测试范围已与目标所有者书面确认
3. 你遵守当地法律法规

未经授权对系统进行渗透测试是违法行为。本工具作者不对滥用行为承担责任。

---

许可证

MIT License

---

加入社区

与更多安全爱好者一起交流、分享与成长

| 社区交流群 | 开发者群聊 |
|:--:|:--:|
| 欢迎加入讨论分享，获取最新产品动态与使用技巧 | 加入我们，参与开源贡献与技术深度探讨 |
| ! 社区交流群 | ! 开发者群聊 |
| QQ | QQ |

---

<di="center">

> 🦞 — 让每一次渗透都有章可循。

</div>

项目信息

开发语言：Python

Star 数：3489

技术要点

该项目属于CTF思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕基于 AI Agent + MCP 工具链 + 渗透 Skill 编排， 配合大语言模型， 自然语言输入 → 自动完成「信息收集 → 漏洞发现 → 漏洞利用 → 报告生成」全流程。展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。