渗透测试模式 R1145141919810/dsh-vulnclaw-pentest

DSH VulnClaw 渗透模式

把 VulnClaw 的渗透测试工具链接入 DeepSeek Harness，在 Harness 的模式列表里新增一个「渗透测试」智能体模式。

选中该模式后，VulnClaw 的 37 个工具（nmap_scan、http_probe_batch、dir_enum、js_recon、 crypto_decode、source_extract、evidence_、traffic_、cve_lookup、attack_map …）
会作为原生 Harness 工具出现，由 Harness 自己的模型与智能体循环驱动。

English · 安装 · 设计 · 实测修复 · 排障

这是什么 / 不是什么

是：一个 DSH 插件包（bundle）。它给 Harness 加一个模式，并把 VulnClaw 的能力接进来。

不是：VulnClaw 的分支、包装脚本或替代品。本仓库不含任何 VulnClaw 源码——它在首次使用时把 VulnClaw 装进一个私有环境（见 Python 环境）。

⚠️ 仅限授权测试。 本项目面向已授权的渗透测试、CTF 竞赛、安全教学与红队演练。
使用前请确认你已获得目标系统的明确书面授权，并遵守当地法律法规。
未经授权对系统进行渗透测试是违法行为。

ℹ️ 需要 DeepSeek Harness。 这不是独立程序。没有 Harness，本插件无处运行。

特性

| 特性 | 说明 |
| 单一模型 | Harness 拥有模型，VulnClaw 只提供能力。VulnClaw 自己的智能体循环不会启动——不需要为它再配 API Key，也不会出现两个智能体抢工具调用。 |
| 不改 VulnClaw 源码 | 全部通过公开模块调用：AgentCore 构造、build_openai_tools() 取 schema、execute_mcp_tool() 执行——与 VulnClaw 自己的循环用的是同一套分发。 |
| 证据链完整 | 每个工具结果都写入 VulnClaw evidence，返回文本带 [evidence:eNNN] 前缀，因此 evidence_view / evidence_search / traffic_ / 报告生成都能看到完整历史。 |
| 按作用域注册 | 工具只在该模式内存在。standard / ptc / minimal / cordis 四个模式一个工具都不会多；移除 bundle 时模式与工具一起消失。 |
| 模型接缝默认关闭 | 默认禁止 VulnClaw 自建模型连接，避免残留凭据让某条路径悄悄开出第二个智能体。可用环境变量显式打开。 |
| 自动准备环境 | 首次用到工具时自动检测/创建 Python 环境并安装 VulnClaw，并补齐其工具描述承诺的执行库。 |

前置条件

| 依赖 | 说明 |
| DeepSeek Harness | 宿主。本插件是它的 bundle。 |
| Python 3.10+ | 能 import vulnclaw 的解释器。装不了也没关系——安装步骤会用 uv 自动准备一个。 |
| uv（推荐） | 用于自动创建环境。已存在可用解释器时不需要。 |
| nmap（可选） | 只有 nmap_scan 需要。未安装时该工具会明确报错，不影响其它工具。 |

安装

1. 取得代码

git clone https://github.com/R1145141919810/dsh-vulnclaw-pentest.git
cd dsh-vulnclaw-pentest

路径建议用纯 ASCII。 安装器会把包目录交给 pnpm，非 ASCII 路径（如中文目录名）在编码转换时可能被破坏，导致 profile 里出现一条不存在的 link: 路径。
放在 D:\dsh-vulnclaw-pentest 这类路径下最稳妥。

2. 安装 bundle，然后链接依赖（顺序不能颠倒）

plugin_manager(action: "install_bundle", target: "<仓库的绝对路径>")

安装完成后必须链接 Harness 自己的包：

npm run link-deps

为什么需要这一步：install_bundle 用 pnpm 把本地包以符号链接方式链入 profile。
Node 会跟随符号链接到插件的真实目录，再从那里向上寻找 node_modules——那条路径走不到 Harness 自己的包，于是插件激活时报 ERR_MODULE_NOT_FOUND: @deepseek-ai/dsh-tools。
link-deps.mjs 从 profile 解析出这两个包的真实位置并建立目录联接（Windows 用 junction，无需管理员权限），不下载、不复制、不硬编码机器路径。脚本可重复执行，Harness 升级后重跑即可。

若 Harness 装在非默认位置：

DSH_HOME=/path/to/.dsh DSH_PROFILE=desktop npm run link-deps

3. Python 环境

通常不用做任何事。 插件在首次用到工具时（不是激活时，所以 Harness 启动不会被拖慢）按以下顺序解析解释器：

1. VULNCLAW_PYTHON —— 你显式指定的解释器，直接使用；失败就报错，不会偷偷换一个；
2. $DSH_HOME/vulnclaw-bridge/venv —— 已备好的托管环境；
3. 用 uv 新建一个，并 uv pip install "vulnclaw[web]"。
随后它会检查 VulnClaw 工具描述里承诺的执行库（requests 等）是否真的可导入，缺失就补上——详见实测发现。

手动指定解释器：

export VULNCLAW_PYTHON=/usr/bin/python3 # 该解释器需已能 import vulnclaw

4. 重启 Harness

插件的新 JavaScript 模块需要新进程才能加载。重启后新建会话，在模式列表里选「渗透测试」。

5. 验证安装

export TEST_PYTHON="<装了 vulnclaw 的解释器>"

node dev-verify-activation.mjs # 31 项：导出形态 / 工具注册 / 目录裁剪 / 首调回归
node dev-regression.mjs # 9 项：真实会话暴露过的缺陷
node dev-verify-schema.mjs # 37 个 schema 逐个过 Harness 真实编译器
node dev-test.mjs # 25 项：桥接客户端与工具面冒烟

四个套件全绿即安装正确。dev-regression.mjs 与 dev-verify-schema.mjs 会调用 Harness 真实的 schema 编译器；装在非默认位置时用 DSH_APP_NODE_MODULES 指路。

配置

在 bundle patch 相应行的 config 里设置：

| 键 | 默认 | 说明 |
| pythonPath | 空 | 能 import vulnclaw 的解释器；留空则自动解析或准备。 |
| sourcePath | 空 | 本地 VulnClaw 检出目录，首次准备时以可编辑模式安装；留空装 PyPI 发行版。 |
| exposeTools | true | 是否在本插件作用域注册工具。宿主行设 false，预设行设 true。 |
| toolPrefix | 空 | 给所有注册的工具名加前缀，避免与其它插件撞名。 |
| callTimeoutMs | 600000 | 单次工具调用超时。 |
| permissionMode | full_access | VulnClaw 内部的 safety.permission_mode。 |
| keepDefaultDeny | true | 隐藏与渗透无关的桌面自动化工具族。 |
| denyTools | [] | 额外要隐藏的工具名。 |

环境变量

| 变量 | 说明 |
| VULNCLAW_PYTHON | 指定解释器，跳过自动准备。 |
| VULNCLAW_BRIDGE_PERMISSION_MODE | 覆盖 permissionMode。 |
| VULNCLAW_BRIDGE_MAX_RESULT_CHARS | 单次结果回传上限，默认 120000。 |
| VULNCLAW_BRIDGE_LLM_BASE_URL / _API_KEY | 打开模型接缝（见 设计）。 |
| DSH_HOME / DSH_PROFILE | link-deps.mjs 定位 Harness 用。 |
| DSH_APP_NODE_MODULES | 验证脚本定位 Harness 的 schema 编译器用。 |

权限与审批

危险工具（shell_command、python_execute、PoC）在 VulnClaw 里默认弹 Approve this execution? [y/N]。桥接是无头子进程，没有这个交互通道，所以 permissionMode 默认 full_access——否则这些工具会一律以 no_channel 被拒绝。

审批没有消失，只是上移了：shell_command / python_execute 在 Harness 里等同于执行本机命令，归 Harness 的权限系统管。请用 Harness 的权限预设控制它——不要把它当成一块无审批的任意代码执行入口。

VulnClaw 命令行侧的改动（可选）

仓库内的 python/vulnclaw_dsh_mode.py 与 python/dsh-vulnclaw.py 提供两处运行时定制（不改已安装的包）：TUI 模式列表新增「渗透测试」，以及隐藏 AI 管理命令（config / login / logout / doctor / init）。细节见设计文档。

python python/dsh-vulnclaw.py --help
python python/dsh-vulnclaw.py tui --target https://target.example

直接跑裸 vulnclaw 完全不受影响——这层定制只在该进程内生效。

若你的 Harness 会话已经提供了模型与工具，这一节可以完全跳过。

项目结构

.
├── package.json 插件清单（dsh.bundle.patch + 展示元数据 + icon） ├── cordis.patch.yml 两行：宿主行 + preset-pentest 预设（含人设与环境契约） ├── index.js 宿主插件：注册动态工具、会话级工具、裁剪目录、schema 翻译 ├── bridge.js Python 桥的 JSON-RPC 客户端（单进程长驻） ├── tools.js 3 个会话级工具的定义 ├── python-runtime.js 解释器解析、首次准备、执行库补齐 ├── llm-offline.js 模型主权约束的说明与诊断 ├── link-deps.mjs 从 profile 解析并联接 Harness 依赖 ├── icon.svg 插件图标 ├── locale/{en,zh}.json 展示文案 ├── docs/DESIGN.md 架构与设计取舍 ├── docs/FINDINGS.md 实测发现的缺陷与修复（含回归测试说明） ├── python/ │ ├── vulnclaw_bridge.py stdio JSON-RPC 桥，暴露 VulnClaw 工具面 │ ├── vulnclaw_dsh_mode.py CLI 定制：渗透模式 + 隐藏 AI 管理命令 │ └── dsh-vulnclaw.py 带定制的 VulnClaw CLI 启动器 └── dev-.mjs 验证与回归测试（不随 npm 包发布）

排障

| 现象 | 原因与处理 |
| failed to import / ERR_MODULE_NOT_FOUND: @deepseek-ai/dsh-tools | 忘了跑 npm run link-deps；跑完后必须重启 Harness。 |
| 工具列表里没有 nmap_scan 等 | 没选「渗透测试」模式；工具是按作用域注册的。 |
| VulnClaw tools unavailable: ... uv is not available | 装 uv，或设 VULNCLAW_PYTHON 指向已装 vulnclaw 的解释器。 |
| 工具报 no_channel 被拒 | permissionMode 被改成了 ask / auto_review；无头进程没有审批通道。 |
| nmap_scan 报未安装 nmap | VulnClaw 需要外部 nmap 二进制；装好并加进 PATH。 |
| python_execute 报 ModuleNotFoundError: requests | 会自动补齐；若仍出现说明 uv 不可用，手动 uv pip install --python <venv> requests。 |
| python_execute 报 lab mode blocked operation | 代码里用了 __import__() / importlib / exec()；改成普通 import 语句。 |
| 看不到桌面自动化工具 | 默认隐藏（56 个与渗透无关）；keepDefaultDeny: false 可恢复。 |
| 非 ASCII 路径下安装后 profile 里出现坏掉的 link: 路径 | 把仓库移到纯 ASCII 路径后重新安装。 |
| 想确认 Python 侧状态 | 直接问桥：initialize 返回版本、工具数、model_seam、llm_refusals。 |

贡献

欢迎 Issue 与 PR。改插件行为时请一并跑第 5 节的四个验证套件——它们会调用 Harness 真实的 schema 编译器，能挡住大部分「看起来对但激活时失败」的改动。

致谢与许可

本项目基于 VulnClaw （作者 UncleC，MIT 许可，官方网站 unclecheng-li.github.io/vulnclaw.com）。

VulnClaw 提供了本插件的全部渗透测试能力——工具实现、证据与流量存储、报告与 PoC 生成、 Skill 知识库。本插件只做一件事：把这些能力以原生 Harness 工具的形式接进来，并让 Harness 的模型来驱动它们。没有 VulnClaw，这个插件没有意义。

本仓库不含 VulnClaw 源码；VulnClaw 由本插件的准备器安装到私有环境。
VulnClaw 的版权声明与 MIT 许可全文见 THIRD-PARTY-NOTICES.md。

同时依赖 DeepSeek Harness 的 @deepseek-ai/dsh-tools 与 @deepseek-ai/schemastery （运行时从 Harness 安装中解析，不在本仓库分发）。

本插件以 MIT 许可发布，见 LICENSE。