授权渗透测试工具集 bzaics666/dsh-pentest-toolkit

渗透测试工具集（@local/dsh-pentest-toolkit）

给 DeepSeek Harness 用的授权渗透测试工具集：按 PTES 的八个阶段推进一次全量渗透测试，把攻击面测绘、漏洞台账、报告成稿做成模型可以直接调用的工具，并且用状态机把阶段顺序锁死。

- 零运行时依赖：只使用 Node 内置模块，不 import 任何 @deepseek-ai/ 包。
这一点是刻意的：profile 的 node_modules 里通常解析不到 dsh 的包，一旦引入就会整份 bundle 装载失败。
- 纯 Host 插件：插入一行，注册 7 个工具；不发布服务、不需要 isolate realm。
- 能力边界：只做侦察与记录。不含漏洞利用、口令爆破、权限提升、横向移动或写入目标系统的动作——见下文「边界与合规」。

七个工具

| 工具 | 作用 |
| pentest_workflow | 总控台：八阶段状态机。start 登记授权并开始，status 看进度与门禁，note 留结论，complete 推进，skip 跳过（要理由），reset 重来。 |
| pentest_env_check | 体检本机安全工具链（20 项目录），报告可用性与版本，并标注同名但身份不符的可执行文件。只读。 |
| pentest_recon | 单目标侦察：DNS 记录、常见端口 TCP 连通性、开放 Web 端口的 HTTP 指纹，结果写入资产台账。可追加一次本地 nmap -Pn -sT 复核。 |
| pentest_scan | 阶段 4 的受控检测：fingerprint(httpx) / template(nuclei) / content(ffuf)。返回候选，不是漏洞。 |
| pentest_assets | 资产台账查询与维护：list / get / remove / clear。 |
| pentest_findings | 漏洞台账增删改查：add / list / get / update / remove / stats，含等级、状态、CVSS、CWE、证据与修复建议。 |
| pentest_report | 出报告（Markdown / JSON）：授权声明、执行摘要、风险统计、阶段执行记录、资产清单、漏洞详情、修复优先级。 |

八阶段与完成门禁

顺序由 pentest_workflow 强制：每个阶段只有在门禁满足时才能 complete 推进，所以阶段跳不过去。确实不适用某阶段时，必须用 skip 给出理由，而不是默默略过。

| 阶段 | 完成门禁 |
| 0 授权与准备 | 授权信息齐全（被测方 / 范围 / 授权依据 / 周期），start 时校验 |
| 1 信息收集与攻击面测绘 | 资产台账 ≥ 1 条 |
| 2 威胁建模 | 阶段 2 至少 1 条结论 |
| 3 漏洞发现与验证 | 漏洞台账 ≥ 1 条，或显式声明 noFindings: true |
| 4 受控利用与权限提升 | 阶段 4 至少 1 条结论，或 skip |
| 5 后渗透与影响评估 | 阶段 5 至少 1 条结论，或 skip |
| 6 清理与恢复 | 阶段 6 至少 1 条记录，或声明 noCleanupNeeded: true |
| 7 报告与复测 | 必须已生成过至少一份报告 |

阶段 6 的门禁最值得强调：遗漏清理是真实事故的常见来源，这里用状态机挡住「没写清理记录就出报告」的情况。

数据落在哪

全部状态写在发起调用的那个会话的工作区下的 .pentest/：

<会话工作区>/.pentest/ ├── workflow.json # 八阶段状态机：当前阶段、各阶段结论与跳过理由 ├── project.json # 项目与授权信息（start 时登记，出报告时回填） ├── assets.json # 资产台账（一次 pentest_recon 一条，按 target upsert） └── findings.json # 漏洞台账

文件名固定，不接受模型传入任意路径；pentest_report 的 outPath 与 pentest_scan 的 wordlist 都会被限制在工作区内，越界直接拒绝。

安装

本包可以放在任意目录（本仓库内、桌面、其它工程目录都行）。下文用 <包目录> 指代它的绝对路径。

1. Web UI 插件管理面板（推荐）

打开 DSH Web 的插件管理面板 → 安装本地 bundle → 选择 <包目录>。

2. 命令行

dsh plugin --profile web add link:<包目录>

如果当前目录已经是包目录，可以直接写 dsh plugin --profile web add "link:$PWD"。

3. 手动接入已有 bundle

把 cordis.patch.yml（与本 README 同目录）里的 insert 内容并入你正在用的 bundle patch：

- insert:
- id: pentest-toolkit
name: '@local/dsh-pentest-toolkit'

安装后新开会话即可看到这 7 个工具。若面板里显示的标题/描述不对，检查同目录下 locale/zh.json、locale/en.json 的 meta 字段是否被正确导出。

配套 skill

pentest-full-scope 负责把「为什么这么排、每阶段该调什么、门禁被拒怎么办」讲给模型听。工具负责强制，skill 负责解释，两者配合才是一次可复现的流程。

本仓库的 skills/pentest-full-scope/SKILL.md 就是它的源码；装到 DSH 时复制到用户技能目录即可：

把 <包目录> 换成实际路径 Copy-Item -Recurse "<包目录>\skills\pentest-full-scope" "$env:USERPROFILE\.dsh\skills\"

说「做一次全量渗透测试」「按流程渗透」时，skill 会被自动加载。

外部工具链

pentest_env_check 与 pentest_scan 会用到本机的外部安全工具（nmap / nuclei / httpx / ffuf 等共 20 项）。不装也能用——pentest_recon 的 DNS / 端口 / Web 指纹探测是内置实现，不依赖任何外部工具；工具缺失一律优雅降级为 skipped。

- 清单、用途、分平台安装方式与两个已知陷阱：TOOLCHAIN.md
- 一键检测（默认只报告，不安装）：

powershell -ExecutionPolicy Bypass -File scripts\install-toolchain.ps1 # Windows
bash scripts/install-toolchain.sh # Linux / macOS

- 真正安装：Windows 加 -Apply，Linux/macOS 加 --apply

两个脚本的检测逻辑都调用 lib/probe.js 的 detectTools，所以工具清单只有一份来源，不会和插件跑偏。

复验

包内自带自检，不需要安装、不需要框架：

cd <包目录>
node verify.mjs

43 项检查，覆盖：装载契约、工具链体检与身份校验、流程前置约束、逐阶段门禁 （每一次「被拒绝」都作为断言验证）、扫描输入校验、侦察与 upsert、台账增删改查、报告内容与路径越界、reset 语义。全绿时自动清理 ./.pentest-verify 沙箱，有失败则保留现场。

运行环境适配（真实环境踩过的两个坑）

- 同名不同物：httpx 既可能是 ProjectDiscovery 的扫描器，也可能是 Python 的 HTTP 客户端。目录里给这类可执行文件配了 identity 正则做身份校验，不匹配就标成不可用， pentest_scan 绝不误用。本机实测就拦下了 Python 版的 httpx。
- 中文 Windows 的 GBK 输出：nslookup、whois 等按控制台代码页输出 GBK，而 Node 默认按 UTF-8 解码，版本串会变成 Ĭ�Ϸ����� 这类乱码。lib/probe.js#decodeOutput 先做严格 UTF-8 试探，失败再回退 gb18030 / gbk / big5 / shift_jis，并把残留的替换字符剔掉。

目录结构

dsh-pentest-toolkit/
├── index.js # 插件入口：七个工具的定义与实现 ├── lib/workflow.js # 八阶段定义、状态机、阶段门禁 ├── lib/probe.js # 网络探测原语（DNS / TCP / HTTP）与受控子进程调用 ├── lib/workspace.js # 工作区定位与台账持久化 ├── verify.mjs # 自检脚本（43 项） ├── TOOLCHAIN.md # 外部工具链清单与安装说明 ├── skills/ # 配套 skill：pentest-full-scope ├── scripts/ # 工具链安装脚本（install-toolchain.ps1 / .sh） ├── cordis.patch.yml # bundle patch：插入插件行 ├── locale/{zh,en}.json # 显示元数据 ├── icon.svg # 图标 └── package.json # bundle 清单（dsh.bundle.patch）

边界与合规

- 仅可用于已获得书面授权的目标。工具完全合法，用途不一定。
- 阶段 4/5 不会被自动化：这两阶段在插件里的形态是「记录结论与证据 + 门禁校验」，执行由授权的测试人员完成。这是设计选择，不是能力缺口。
- 所有目标字符串先过白名单：pentest_recon 只接受主机名 / IP / CIDR（拒绝 URL）， pentest_scan 接受 http(s) URL 但会经 new URL() 解析后重建。
- 所有外部命令走 execFile(argv)，不存在 shell 拼接。
- pentest_scan 只调用检测类工具、不接受任意参数、并禁用反连（nuclei -no-interactsh）。
- 报告与台账包含敏感信息，按约定渠道保管。

二次开发须知

改动本包时请守住四条：

1. 不引入任何非 node: 依赖，包括 @deepseek-ai/。
2. 不使用 defineTool（它由 @deepseek-ai/dsh-tools 导出）。本插件直接构造符合 ToolDefinition 契约的普通对象——parameters 是标准 JSON Schema，参数校验在 execute 内自行完成。
3. 新增外部命令调用必须走 lib/probe.js#runCommand，参数做白名单校验；目标字符串一律先过 assertTarget / assertScanTarget。新增可执行文件时，若存在同名不同物的风险，要给它加 identity 正则。
4. 改动阶段或门禁必须同步更新 verify.mjs、README 与 pentest-full-scope skill。

改完跑一次 node verify.mjs。