Netw0rkNoob/VulnClaw

VulnClaw 🦞

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

🌐 English version: README_EN.md

本项目是可独立运行的 AI 渗透测试 Agent。
项目官网：https://unclecheng-li.github.io/vulnclaw.com/

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

快速开始 · 架构 · 内置 Skill

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

用户输入：帮我对 http://target.example.com 进行渗透测试

VulnClaw 自动执行：
  Round 1:  信息收集 → 指纹识别、端口扫描、目录枚举
  Round 2:  漏洞发现 → 检测注入点、已知 CVE、配置缺陷
  Round 3:  漏洞利用 → PoC 验证、权限获取
  Round 4:  报告生成 → 结构化报告 + Python PoC 脚本

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

• 模型主导求解引擎（默认） — 类似 Claude Code/Codex 的自主循环，模型自己决定下一步、何时调用工具、何时完成/询问/判定无路可走
• AgentState 证据记忆 — 工具结果统一写入 AgentState.evidence，raw 原文完整保留；active context 默认只注入高信号预览，evidence_search / evidence_view 用于按需回查原始证据
• 轻量纠偏层 — 工具调用前后记录重复调用、失败降级、耗时和新发现等信号；重复读取同一 evidence 范围会被抑制，连续证据空转会触发 stall guard，但不恢复旧阶段规划器
• 证据级反幻觉闸门 — 声称的 flag/结论必须在真实工具输出里逐字符出现才被采信，杜绝凭空编造 flag 的假胜利
• 自然语言驱动 — 用人话描述渗透意图，自动识别阶段和工具
• 13 个 LLM Provider — OpenAI / Anthropic / MiniMax / DeepSeek / 智谱 / Moonshot / 千问 / SiliconFlow / 豆包 / 阶跃星辰 / 商汤 / OpenRouter / 本地 Ollama，一键切换
• MCP 工具链 — 4 个 MCP 服务：fetch / memory 本地实现开箱即用，chrome-devtools / burp 对接外部 MCP 服务实现浏览器自动化和 HTTP 抓包重放
• 增强 fetch 请求工具 — 默认直接 GET 并返回完整响应 body，支持 HTTP/HTTPS、自定义 method/headers/params/cookies/body/data/form/json、timeout/redirect/TLS 控制；CTF/靶场 HTTPS 默认不校验证书
• 原生流量证据存储 — 按运行内作用域过滤后以追加式 JSONL 索引 + 每请求原始报文落盘于 evidence/traffic/，内置 traffic_list / traffic_view / traffic_repeat / traffic_sitemap 工具直接读写
• AI Agent 核心 — OpenAI 兼容协议 + Tool Calling + 自主渗透循环
• 结构化推理 + 自适应反思 — 已知事实/约束/攻击链结构化沉淀；失败自动归类并按 L0-L4 渐进升级 payload 绕过策略
• 漏洞检测插件体系 — 低耦合插件运行时 + 内置只读 Web 插件，结果自动汇入报告链路（vulnclaw plugins）
• 50 个专项 Skill — 覆盖 CTF、Web、内网、逆向、漏洞验证与授权红队知识库；Skill 只作为参考资料索引暴露给模型，正文需要模型主动调用 load_skill_reference 按需读取，不再作为强制剧本注入上下文
• 编解码/加解密工具 — 29 种操作（Base64/Hex/URL/AES/JWT/Morse 等），LLM 可精确调用，不再靠猜测
• 源码自动还原 — fetch / http_probe_batch 遇到 highlight_file、HTML 高亮源码或混杂 HTML/JS body 时会自动在 raw body 前追加 clean source；http_probe_batch 默认关闭 TLS 校验并记录完整响应头，避免丢失 X-Powered-By 等运行时证据；内置 source_extract 仍可用于按需重读历史 evidence，并固定危险 sink、表单与 endpoint 信号
• 本地命令验证 — 内置 shell_command，用于 php -r 反序列化验证、curl 精确请求、rg/Select-String 文件检索等 Codex-style 本地调试场景；raw stdout/stderr 完整写入 evidence，大输出进入模型时使用高信号预览
• 运行时差分探测 — 内置 runtime_diff_probe，用于正则/字符串过滤器与运行时解析器不一致的场景，帮助模型批量生成并验证“过滤器漏过、解析器接受”的候选；PHP 序列化模式会提示目标/本地运行时版本差异，并把 PHP5 signed length 候选标记为必须远程验证，避免被本地新版 PHP 误杀
• Python 代码执行 — 内置 python_execute 工具，适合 payload 构造和响应解析；当前仍属高风险实验能力，不应视为强隔离沙箱
• 批量 HTTP 探测 — 内置 http_probe_batch，用于一次比较多组 URL/参数/header/body/raw URL 变体，默认返回每个响应的完整 body，并在模型可见输出中展示实际请求面（method、URL、params、headers、cookies、body/json），减少重复 LLM 轮次和手写请求代码
• 近成功防误停 — solve 保留证据闸门，并新增通用 NO_PATH 闸门：当源码 sink、表单/参数、请求面、本地 proof 或响应差异等高信号尚未耗尽时，不接受模型因单次 payload 无回显/远端 same-body 就提前判死
• 持续性渗透测试 — 周期循环（默认 100 轮/周期 × 10 周期 = 1000 轮），每周期自动生成报告
• 推理过程显示控制 — think on/off 一键切换 LLM 思考过程的显示/隐藏
• 沙盒模式提示词 — 解锁 AI 安全测试能力，CTF / 授权渗透场景专用
• 自动报告 & PoC — 生成结构化 Markdown 报告和可运行的 Python PoC 脚本
• Web UI 模式 — vulnclaw web 启动本地 Web 界面，默认 127.0.0.1:7788
• 安全知识库 — 已内置知识库模块与基础种子数据，检索增强正在逐步接入主流程

# 从 PyPI 安装（推荐）
pip install vulnclaw

# 从源码安装
git clone https://github.com/Netw0rkNoob/VulnClaw.git
cd VulnClaw
pip install -e .

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

cp .env.example .env          # 填入 VULNCLAW_LLM_API_KEY 等
docker compose up --build      # 构建镜像并启动 Web UI
# 打开 http://127.0.0.1:7788

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

docker run --rm -it \
  -e VULNCLAW_LLM_API_KEY=sk-your-key-here \
  -v vulnclaw-data:/data \
  vulnclaw:latest scan <target>

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

# 1. 选择提供商（自动填充 Base URL 和模型名）
vulnclaw config provider minimax   (或 openai/anthropic/deepseek/zhipu/moonshot/qwen/siliconflow/ollama)

# 1.2（可选）自定义 Base URL 或模型名
vulnclaw config set llm.base_url https://your-own-api.example.com/v1 
vulnclaw config set llm.model your-model-name

# 2. 设置 API Key
vulnclaw config set llm.api_key sk-your-key-here
#    — 或改用 ChatGPT 订阅登录（无需 API Key）：
#      vulnclaw login   （浏览器登录；注意 ToS 风险）

# 3. 默认：打开原 CLI / REPL
vulnclaw

# 4. 可选：打开 TUI 工作台
vulnclaw tui

vulnclaw doctor

输出示例：

🦞 VulnClaw 环境检查

  Python: 3.14.4
  Node.js: v24.14.1
  npx: 已安装
  nmap: 已安装

LLM 配置:
  Provider: openai
  Auth Mode: static
  Credentials: configured
  Base URL: https://api.openai.com/v1
  Model: gpt-4o

MCP 服务:
  fetch: 已启用 [P0]
  memory: 已启用 [P0]
  ...

✅ 环境就绪，运行 vulnclaw 开始

$ vulnclaw --help

🦞 VulnClaw — AI-powered penetration testing CLI

 Usage: vulnclaw [OPTIONS] COMMAND [ARGS]...

 Commands:
   run           🚀 一键全流程渗透测试（默认使用 solve 引擎）
   solve         🧩 目标驱动求解（模型主导，无固定轮数）
   persistent    🔄 持续性渗透测试（100轮/周期）
   recon         🔍 仅信息收集阶段
   scan          🔎 执行漏洞扫描阶段
   exploit       💥 执行漏洞利用阶段
   report        📝 从会话记录生成报告
   repl          💬 启动经典 REPL 交互界面
   config        ⚙️  管理配置（set/get/list/provider）
   plugins       🧩 管理漏洞检测插件（list/info/run）
   init          🔧 初始化配置
   doctor        🏥  检查运行环境
   tui           🖥️  打开终端图形化工作台
   web           🌐 启动本地 Web UI
   code          🧬 本地源码安全扫描（无需网络目标）

vulnclaw

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

🦞 vulnclaw> 对 192.168.1.100 进行渗透测试，这是我授权的靶场

[*] 进入自主渗透模式，按 Ctrl+C 可随时中断
── Round 1 ──
  [+] 目标: 192.168.1.100
  [+] 开放端口: 22, 80, 443, 8080
  [+] Web 指纹: Apache/2.4.62
── Round 2 ──
  [+] 发现 /manager/html (Tomcat Manager)
  [+] 命中 CVE-202X-XXXX: Apache Tomcat 认证绕过
── Round 3 ──
  [+] 漏洞验证成功

🦞 192.168.1.100 | 报告> 生成渗透报告
[+] 报告已保存: ./reports/192.168.1.100_20260418.md
[+] PoC 脚本已保存: ./pocs/CVE-202X-XXXX.py

REPL 内置命令：

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

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

vulnclaw tui
vulnclaw tui --target https://target.example --mode quick --only-port 443
vulnclaw tui --dry-run --target https://target.example --mode deep --only-path /admin

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

• 拖动视图标题，可在两个侧栏之间移动，或在栏内重新排序；橙色预览框显示松开后的模块位置与大小。点击标题左侧 v / > 折叠或展开。
• 拖动容器或视图之间的分隔条调整尺寸；折叠视图需展开后再调高。拖动中按 Esc 取消。
• 滚轮滚动鼠标下方的视图内容；点击聚焦后可用方向键滚动，Ctrl+←/→ 切换视图，Ctrl+Y 复制当前视图。
• 辅助侧栏清空后自动收起，中间区域填满剩余空间。拖动模块到工作区右缘可显示橙色停靠预览，松开后重新展开；主侧栏始终至少保留一个模块。
• 布局自动保存到本地 VULNCLAW_HOME/tui/layout.json（默认 ~/.vulnclaw/tui/layout.json），下次启动恢复。底栏随命令面板自动增高；终端过小时提示所需尺寸，放大后恢复布局。

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

常用菜单：

• 菜单 3 — 设置测试范围（主机/端口/路径/允许动作/禁止动作）
• 菜单 7 — 环境诊断入口（完整详情运行 vulnclaw doctor）
• 菜单 8 — 模型/API 配置（切换 Provider、Base URL、Model、API Key）

vulnclaw run 192.168.1.100                    # 一键全流程
vulnclaw recon 192.168.1.100                   # 仅信息收集
vulnclaw scan 192.168.1.100 --ports 80,443     # 漏洞扫描
vulnclaw exploit 192.168.1.100 --cve CVE-2024-1234 --cmd id  # 漏洞利用
vulnclaw report session.json                   # 生成报告

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

┌──────────────────────────────────────────────┐
│  Cycle 1 (100轮) → 自动报告 → 继续          │
│  Cycle 2 (100轮) → 自动报告 → 继续          │
│  ...                                         │
│  直到 Ctrl+C 或达到最大周期数（默认10）      │
└──────────────────────────────────────────────┘

vulnclaw persistent 192.168.1.100              # 默认 100轮/周期 × 10周期
vulnclaw persistent 192.168.1.100 -r 200 -c 5  # 200轮/周期 × 5周期
vulnclaw persistent 192.168.1.100 --no-report   # 不自动生成报告

# TUI 方式
vulnclaw tui --target 192.168.1.100 --mode continuous

# REPL 方式
🦞 vulnclaw> persistent 192.168.1.100

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

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

git clone https://github.com/Netw0rkNoob/VulnClaw.git
cd VulnClaw
pip install -e '.[web]'       # 从源码检出安装 Web 依赖

# 首次使用：构建 React 前端（需要 Node.js 18+）
cd frontend
npm install
npm run build
cd ..

vulnclaw web                  # 启动（默认 127.0.0.1:7788）
vulnclaw web --port 8080      # 自定义端口

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

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

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

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

MODEL DECIDES → 可选工具调用 → AgentState 记录完整 raw evidence + active context 高信号预览 + 轻量纠偏信号
        │
继续推理 / 继续调用工具 / ASK_USER / NO_PATH / FINAL
        │
FINAL 经过证据闸门校验 → 通过才结束，否则把拒绝原因返回模型继续做

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

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

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

# Step 1: 启动 Chrome 远程调试
# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir=C:\tmp\chrome-debug
# Linux/Mac
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Step 2: 启用 VulnClaw 配置
vulnclaw config set mcp.servers.chrome-devtools.enabled true

mcp:
  servers:
    chrome-devtools:
      enabled: true
      transport:
        type: stdio
        command: npx
        args: ["-y", "chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"]

# Step 1: 克隆并构建
git clone https://github.com/PortSwigger/mcp-server.git burp-mcp
cd burp-mcp
./gradlew embedProxyJar    # Windows: gradlew.bat embedProxyJar

# Step 2: 加载到 Burp Suite → Extensions → Add → Type: Java → 选择 burp-mcp-all.jar

# Step 3: 在 Burp 的 MCP 标签页勾选 "Enabled"

# Step 4: 启用 VulnClaw 配置
vulnclaw config set mcp.servers.burp.enabled true

mcp:
  servers:
    burp:
      enabled: true
      transport:
        type: stdio
        command: java
        args: ["-jar", "~/.vulnclaw/tools/burp-mcp-all.jar", "--sse-url", "http://127.0.0.1:9876"]

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

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

vulnclaw config provider --list    # 查看所有提供商
vulnclaw config provider minimax   # 一键切换

vulnclaw config list                          # 查看所有配置
vulnclaw config get llm.model                 # 查看单项
vulnclaw config set llm.api_key sk-xx         # 设置 API Key
vulnclaw config set session.max_rounds 30     # 设置最大轮数（默认 15）
vulnclaw config set session.show_thinking false # 隐藏推理过程

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

# ① 永久写入配置（推荐）
vulnclaw config set safety.permission_mode full_access

# ② 仅当前 REPL 会话生效（重启后回到配置文件的模式）
mode full_access          # 切换；不带参数则查看当前模式

# ③ 单次运行生效
VULNCLAW_SAFETY_PERMISSION_MODE=full_access vulnclaw solve <target>

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

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

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

完整更新日志见 CHANGELOG.md。

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

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

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

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

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

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

MIT License

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

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