dsh-pentest

dsh-pentest — DSH 渗透测试模式

本仓库已归档，不再维护。

自 2026-10-09 起进入 GitHub archive（只读）状态：不再受理 issue / PR，不再发布新版本，
也不再适配新版 DSH 或修复缺陷。已发布的 npm 包与 Release 资产保持原样，仍然可以安装使用；
但 DSH 后续版本可能破坏兼容性，请自行评估，或 fork 后自维护（MIT）。

本项目只用于获得明确授权的资产范围。作者不对任何未经授权的使用负责，
也不对因此造成的任何后果承担责任。

面向 DeepSeek Harness（dsh）的渗透测试模式：
在授权范围内记录目标、探索线索、验证结果、资产与漏洞，并在 Web 中以探索链路、漏洞和资产视图展示。

本目录是自包含 bundle 包（@howmp/dsh-pentest）：宿主插件、Web 界面和 sqlite 后端通过包内 exports
一同分发。npm 上的 @howmp/dsh-pentest 与 Release 资产内容一致，两者都可由 dsh plugin add 安装。

安装

三种方式装的是同一个 bundle，默认从 npm 安装。

从 npm 安装（推荐）

dsh plugin --profile web add @howmp/dsh-pentest

需要旧版本时钉版本号，例如 @howmp/dsh-pentest@0.1.0-rc.32（见下文宿主版本要求）。

或从 Release URL 安装

dsh plugin --profile web add https://github.com/howmp/dsh-pentest/releases/latest/download/dsh-pentest.tar.gz

或下载后从本地文件安装

dsh plugin --profile web add file:C:\path\to\dsh-pentest.tar.gz

重启 dsh 后，在新会话中选择自动注册的「渗透模式」。

预设注册兼容当前 DSH 的 agentPresets.register() 接口及旧版 resolvedRoots 接口。
当前接口通过宿主 include loader 加载包内配置，关闭组件时释放预设注册。

宿主版本要求：DSH >= 0.1.6。发布包的 peer 范围覆盖 DSH 0.1.x，以及从 0.2.0-rc.1 开始的 0.2.x；
预设是宿主 standard 预设的拷贝，其中的宿主包名逐字生效；
DSH 0.1.6 把工作流引擎从 @deepseek-ai/dsh-workflow-worker-thread 改名为
@deepseek-ai/dsh-workflow-ptc，0.1.6 之前的宿主请钉 @howmp/dsh-pentest@0.1.0-rc.32
（bundle 的 peer 范围覆盖 0.1.x 和 0.2.x，但预设会显示「加载失败」）。

DSH 0.1.7 的 Web 页签使用 retainedBy.mainView 识别当前会话，并兼容旧版 sessions.list.current；
后台任务或侧栏打开的渗透会话不会让普通主会话显示渗透页签。

界面预览

模式选择

对话与执行

探索链路

漏洞视图

资产视图

测试报告

架构速览

• 领域模型（src/dsh-pentest/src/spec.ts）：storage domain pentest（version 2）——goals / intents /
  facts / findings / assets / edges 六张表。边即链路词汇：spawns(goal→intent)、yields(intent→fact)、
  derived_from(fact→intent)、proves(intent→finding)，资产关系用 parent(asset→asset)。finding 必填
  reproducibleSteps（至少一条）。
• 确定性 id（store.ts）：节点/边 id 为 <kind>-<n>（按会话计数，goal 重置后归零）——工具返回 id 供模型
  跨调用引用，会话投影从日志纯重放同一张图。
• 工具（tools.ts）：pentest_submit（子 agent 直写指定父 intent）/ pentest_add_goal（重置整图）/ pentest_add_intent（恰好一个锚点）/
  pentest_add_fact / pentest_add_finding（步骤必填，可关联影响资产）/ pentest_add_asset（可选 parentId，
  空字符串视为根资产）/ pentest_state / pentest_graph / pentest_report。
• 会话投影（projection.ts）：折叠宿主自己写入日志的 pentest_* 调用为 { goal, nodes, assets, edges, counts, truncated }，
  镜像 store 的引用拒绝；节点/资产窗口各 200 条（新记录优先，见「Web 图为窗口视图」）。本包不向任何会话日志追加事件（见「已知边界」），因此子 agent 经
  pentest_submit 提交的记录不进入父会话的 Web 图，只进存储层。另注册逐会话的 pentestMounted 标记单元：
  当该会话自身日志证明组合挂载了本插件（请求头组装出 pentest_* 工具 / 已记录调用 / 旧版
  pentest/submit 提交）时置真，供 Web 标签页判定。
• Web 标签页（src/dsh-client-ui-pentest）：按会话注册（当前会话或列表祖先链命中 pentest 预设名、
  pentest-* 复制预设名，或该会话带 pentestMounted 标记即显示；无证据的会话隐藏）；四个子标签——探索链路
  （@xyflow/react 图，边带关系胶囊：意图链/产出/推导自/证实）、漏洞（严重度/描述/可复现步骤/影响资产）、
  资产（列表/图两种模式）、报告（Markdown 渲染、复制与保存）。
• 协议（instructions.ts）：系统提示词段 pentest:protocol（order 50），沿链路推进、子 agent 通过
  pentest_submit 直写父 intent、资产先父后子、与用户交互一律中文。

已知边界

• 数据库：渗透记录写入 $DSH_HOME/storages/pentest-sessions.db（sqlite，经 bundle 补丁路由）。
  宿主其它域的存储不受影响（仍为宿主默认 json 后端）。
• 授权：只测试有授权的目标。pentest_add_goal 的 authorization 参数可填写授权说明（授权对象 /
  书面许可引用），会写入状态与最终报告留痕；它只是审计事实，不是门禁——扫描/利用动作仍受部署沙箱与
  审批约束。
• 记录按单会话作用域，无跨会话/项目续跑；重新开始一次 engagement 需新的 pentest_add_goal。
• 派生预设：预设不支持继承，按官方方式整目录复制 preset/pentest/ 后自改即可（工具、协议、投影都随行
  生效）。Web 标签页的判定与预设名解耦：复制时保留 pentest- 前缀（如 pentest-sec）会立即显示；改成
  任意名字的复制预设在该会话首次请求后由 pentestMounted（会话自身日志证据）置位显示——预设名不是能力，
  会话日志才是。
• Web 图为窗口视图：会话投影的节点与资产各保留最新 200 条，但不会因此丢掉链路——窗口按新→旧逐出，
  被保留记录仍指向的锚点（intent、父资产）优先留在窗口内，因此长会话里的意图与资产根不会在后续记录引用它之前
  先被逐出。边不是独立的窗口：边跟随两端点，端点离开窗口时边同步清理，所以保留的链路始终连得上。
  窗口装不下的部分通过 truncated 暴露：dropped 是窗口逐出的记录数，refused 是因锚点已不在窗口而被拒的
  写入数；两者都是累计值，据此才能分辨「图完整」与「图被截断」。UI 计数与图反映的是该窗口；完整记录以
  pentest_state / pentest_report（读存储层）为准。窗口选择规则变化会提升投影的 stateVersion，宿主据此
  拒绝旧 checkpoint 并从会话日志重放，既有会话升级后即按新规则重建（无写入副作用）。
• 不写会话日志（issue #32）：会话日志的词汇表归宿主所有。插件追加的结构事件（tool/call 等）会被
  0.2 读取端按整条生命周期校验（tool/call 必须落在当前打开的 turn/step，且对应 assistant/message
  公告的那次调用），自造事件会让整个会话永久无法打开；插件自有事件类型又需要 Session.append
  盖不上的 ignorable 标记，同样被拒。因此 pentest_submit 只写存储域：父会话的 Web 图只折叠决策
  agent 自己记录的 pentest_add_* 调用，子 agent 提交的 fact/asset/finding 需用 pentest_state /
  pentest_graph / pentest_report 查看。被旧版写坏的会话用随包发布的离线修复工具迁移（需先停掉宿主）：
  装好后用随包 bin dsh-pentest-repair，经 DSH CLI 走
  dsh plugin --profile web exec dsh-pentest-repair --apply（参数原样透传，无需 -- 分隔），
  或直接 node node_modules/@howmp/dsh-pentest/lib/repair-session-log.js。它默认预演、--apply 写回，目标
  可省略（按 --dsh-home → $DSH_HOME → ~/.dsh 顺序扫描 <home>/sessions），也可直接给出日志文件或
  会话目录；--json 输出机器可读报告。它把每条合成的 tool/call 就地改写为本包自己的 pentest/submit 事件并加 ignorable: true，行数、seq、
  时间戳都不变，未受影响的 zstd 帧保持原始字节，写回前留 .bak-<时间戳> 备份。修复后的会话可被
  DSH 0.2 正常加载与迁移，委派提交的 fact/asset/finding 会重新出现在渗透页的图里。（v3 日志在 0.2
  宿主上升级到 v4 时，宿主会把该类型改写为 plugin:pentest/submit；折叠器两种拼写都认。）
• 图布局为静态分层（可平移缩放，节点不可拖拽）。
• 运行时要求：sqlite 后端使用 Node.js node:sqlite，宿主运行时需 Node.js >= 22.5；
  宿主 DSH 需 >= 0.1.6（见「安装」一节）。

目录结构

dsh-pentest/                   # 项目根 = bundle 包 @howmp/dsh-pentest（自带 zod/schemastery 运行时依赖，其余宿主提供）
├── package.json               # bundle manifest：dsh.bundle.patch + dsh.client + exports 子路径
├── cordis.patch.yml           # 补丁层：UI、sqlite 后端与 storage-domain 路由
├── lib/                       # 构建产物（npm pack 的内容）
│   ├── index.js               #   包入口：空 apply
│   ├── pentest.js             #   宿主渗透插件：9 个 pentest_* 工具 + 协议注入 + 会话投影/挂载标记
│   ├── preset-root.js          #   注册包内「渗透模式」，源码为 src/preset-root.ts
│   ├── storage-sqlite.js      #   渗透记录专用的 sqlite 后端（node:sqlite）
│   ├── ui-pentest.js          #   Web 插件宿主半：空 apply（0.1.1 时代的子路径行座位；bundle 已改挂包根）
│   ├── ui-pentest.client.js   #   Web 插件浏览器半：渗透视图标签页（4 个子标签，@xyflow/react 内联）
│   └── invariant.js           #   探索图不变量伴生（与官方各包同构，生产环境不加载）
├── src/                       # 源码快照（继续开发/重新构建用）
│   ├── index.ts / invariant.ts
│   ├── dsh-pentest/               # host 包源码：src/ + tests/ + tsconfig + tsdown + README
│   └── dsh-client-ui-pentest/     # client 包源码：src/client/（视图/图布局/注册）+ tests/
├── tests/bundle.spec.ts       # bundle 补丁层测试
├── packages/                  # 三个构建好的子包（仅作构建源保留；bundle 不再依赖它们）
│   ├── dsh-pentest/               # host 插件源码构建产物
│   ├── dsh-client-ui-pentest/     # Web 界面插件源码构建产物
│   └── dsh-storage-sqlite/        # sqlite 后端构建产物（来自 dsh 仓库，无独立源码）
├── preset/pentest/            # 「渗透模式」agent 预设（由 bundle 自动注册）
├── images/                    # README 界面预览截图
└── README.md

参考项目

• ARTEX（原作者 Autumn-27）：本项目最初的灵感来源。
  该仓库已被作者删除（原地址 github.com/Autumn-27/ARTEX 现已 404），作者于 2026-10-08
  公开发布《ARTEX 安全声明》，说明工具被部分人用于未授权攻击，因此项目不再更新并转为闭源，
  后续不提供任何版本与维护支持。此处仅作来源记录，链接不再可用。