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 的假胜利
• 自然语言驱动 — 用人话描述渗透意图，自动识别阶段和工具
• 14 个 LLM Provider — OpenAI / Anthropic / MiniMax / DeepSeek / 智谱 / Moonshot / 千问 / SiliconFlow / 豆包 / 百川 / 阶跃星辰 / 商汤 / 零一万物 / 本地 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/Unclecheng-li/VulnClaw.git
cd VulnClaw
pip install -e .

Docker 运行（可选）

镜像已内置 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   （浏览器登录；详见 docs/keyless-auth.md，注意 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 开始

CLI 命令速查

$ 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

使用方式

方式一：CLI / REPL（默认）

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 随时中断。

方式二：TUI 工作台

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

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

常用菜单：

• 菜单 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 per