DSH VulnClaw Penetration Mode
把 VulnClaw 的渗透测试工具链接入
DeepSeek Harness，在 Harness 的模式列表里
新增一个「渗透测试」Agent 模式。
选中该模式后，VulnClaw 的 37 个工具（nmap_scan、http_probe_batch、dir_enum、js_recon、
crypto_decode、source_extract、evidence_*、traffic_*、cve_lookup、attack_map …）
会作为原生 Harness 工具出现，由 Harness 自己的模型与 Agent 循环驱动。
English · 安装 · 设计 · 实测修复 · 排障
这是什么 / 不是什么
是：一个 DSH 插件包（bundle）。它给 Harness 加一个模式，并把 VulnClaw 的能力接进来。
不是：VulnClaw 的分支、包装脚本或替代品。本仓库不含任何 VulnClaw 源码——
它在首次使用时把 VulnClaw 装进一个私有环境（见 Python 环境）。
⚠️ 仅限授权测试。 本项目面向已授权的渗透测试、CTF 竞赛、安全教学与红队演练。
使用前请确认你已获得目标系统的明确书面授权，并遵守当地法律法规。
未经授权对系统进行渗透测试是违法行为。
ℹ️ 需要 DeepSeek Harness。 这不是独立程序。没有 Harness，本插件无处运行。
特性
| 特性 | 说明 |
|---|
| 单一模型 | Harness 拥有模型，VulnClaw 只提供能力。VulnClaw 自己的 Agent 循环不会启动——不需要为它再配 API Key，也不会出现两个 Agent 抢工具调用。 |
| 不改 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 自建模型连接，避免残留凭据让某条路径悄悄开出第二个 Agent。可用环境变量显式打开。 |
| 自动准备环境 | 首次用到工具时自动检测/创建 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 启动不会被拖慢）
按以下顺序解析解释器：
VULNCLAW_PYTHON —— 你显式指定的解释器，直接使用；失败就报错，不会偷偷换一个；$DSH_HOME/vulnclaw-bridge/venv —— 已备好的托管环境；- 用
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。
