渗透测试工具集（@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。
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）。- 报告与台账包含敏感信息，按约定渠道保管。
二次开发须知
改动本包时请守住四条：
- 不引入任何非
node: 依赖，包括 @deepseek-ai/*。
- 不使用
defineTool（它由 @deepseek-ai/dsh-tools 导出）。本插件直接构造符合
ToolDefinition 契约的普通对象——parameters 是标准 JSON Schema，参数校验在
execute 内自行完成。
- 新增外部命令调用必须走
lib/probe.js#runCommand，参数做白名单校验；目标字符串
一律先过 assertTarget / assertScanTarget。新增可执行文件时，若存在同名不同物的风险，
要给它加 identity 正则。
- 改动阶段或门禁必须同步更新
verify.mjs、README 与 pentest-full-scope skill。
改完跑一次 node verify.mjs。
