dsh-pentest

一句话定位

把 DeepSeek Harness 切换成"渗透模式"：决策 agent 沿 goal → intent → fact → finding 这条探索链路推进，子 agent 把发现回写进持久化记录，Web 端以可缩放的探索图、漏洞卡、资产关系图与最终 Markdown 报告实时呈现。

核心能力

• 在授权范围内记录渗透目标、授权声明与每次 engagement 的目的，作为整张图的根节点
• 按"goal → intent → fact → derived intent → finding"链条推进，所有节点与边持久化，子 agent 通过专用工具实时回写发现
• 记录资产（根域名、子域名、IP、服务、应用、端点）并支持父子归属关系，形成资产图
• Web 端"渗透"标签页实时呈现目标摘要、探索链路、漏洞、资产与最终报告
• 漏洞记录强制要求可复现步骤（命令/请求/动作的有序列表），可关联影响资产
• 最终可一键生成 Markdown 报告，含授权声明、探索链路、漏洞详情与可复现步骤、资产列表，支持复制和下载

技术实现

• 语言: TypeScript（宿主侧 ESM）与 React + CSS Modules（Web 端），打包为单一 bundle 包 @howmp/dsh-pentest
• 关键依赖: zod（持久化记录校验）、@xyflow/react（探索图与资产图渲染）、@deepseek-ai/schemastery（sqlite 后端表结构）、React 18（Web 端运行时）
• 架构模式: Cordis patch 层 bundle——cordis.patch.yml 同时插入 Web UI 行（ui-pentest）、sqlite 后端行（storage-sqlite，路径 $DSH_HOME/storages/pentest-sessions.db）以及 storage-domain 路由覆写（仅 pentest 域走 sqlite，其它域维持宿主默认 json），并挂载一个 pentest-preset-root 自动注册"渗透模式"预设；宿主侧注入 pentest:protocol 系统提示词段并注册八个 pentest_* 工具，客户端侧按当前会话所属的 agent 预设动态挂载"渗透"标签页
• 入口文件: src/index.ts（宿主占位）、src/dsh-pentest/src/index.ts（真正的插件 apply）、src/dsh-client-ui-pentest/src/client/index.ts（浏览器端会话感知标签页注册）

适用场景

安全工程师在 DSH 里跑授权内的渗透测试时，希望主 agent 围绕一个目标有结构地推进侦察、收集事实、确认漏洞，并把每一步记录下来以便随时复盘、出报告，而不需要手工整理日志或在多个工具之间切换。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:howmp/dsh-pentest

配置项

本插件无需额外配置。安装完成后 DSH 会自动注册"渗透模式"预设，并把 sqlite 后端、storage-domain 路由、Web 标签页一次性挂好；新会话选择"渗透模式"即可使用。

常见问题

Q: 谁真正负责把发现写入持久化记录？是主 agent 还是子 agent？

A: 主 agent（决策 agent）通过 pentest_add_goal、pentest_add_intent、pentest_add_fact、pentest_add_finding、pentest_add_asset 这五个写工具维护整张图；执行/探索子 agent 只能调用 pentest_submit，服务端从父子会话关系反查父会话并写入，主 agent 不会重复转录。

Q: 渗透记录存在哪里？其它功能的数据会被改吗？

A: 全部走 bundle 自带的 sqlite 后端，文件落在 $DSH_HOME/storages/pentest-sessions.db；storage-domain 路由只把 pentest 域切到 sqlite，其它存储域保留宿主默认的 json 后端，聊天/技能等数据不受影响。

Q: 漏洞不写可复现步骤能提交吗？

A: 不能。pentest_add_finding 和 pentest_submit 都要求 reproducibleSteps 至少一条，少于一条会在持久化层被 schema 拒掉；这是为了避免把"未经确认的猜测"记成漏洞。

Q: 可以跨会话续跑同一份渗透记录吗？

A: 不可以。记录的物理键是 sessionId:id，且同一会话内每次调用 pentest_add_goal 都会清空该会话的整张图并把 id 计数器归零；想保留结果请先用 pentest_state / pentest_graph / pentest_report 导出。

Q: 插件本身会替我拦截"未授权目标"吗？

A: 不会。pentest_add_goal 的 authorization 字段是写进 goal 的声明性信息，会出现在最终报告里留痕，但插件自身不做门禁；真正的扫描/利用拦截要靠部署侧的沙箱、审批或网络隔离。

Q: Web 上的"渗透"标签页什么时候会出现？普通会话也会看到吗？

A: 不会。标签页只在当前会话（或其会话列表中的祖先）使用了 pentest agent 预设时才注册；普通会话即使装上 bundle 也不会出现这个标签页。

Q: 我在 Windows 上能用吗？shell 工具是怎么处理的？

A: 可以。bundle 本身跨平台，但预设里把 bash 工具禁用、把 pwsh 工具启用，所以 Windows 用户直接用 PowerShell；sqlite 后端同样可用，因为宿主 Node >= 22.5 已带 node:sqlite。

Q: 想彻底卸掉这个插件，记录怎么办？

A: 用 dsh plugin --profile web remove howmp/dsh-pentest 卸载插件即可；sqlite 数据库文件 $DSH_HOME/storages/pentest-sessions.db 不会自动删除，需要手动清掉。

上手难度

进阶 — 需要熟悉 DSH 的 agent 预设、子 agent 委派以及"提案 → 决策 → 执行"的工作方式；首次启用前先选定授权目标和目的，后续子 agent 的委派模板由预设内置，使用门槛较低，但要真正跑通仍需理解 DSH 的会话与存储概念。

已知问题与限制

• 每个会话只能保留最新 200 个节点 / 200 条边 / 200 个资产，超出后最旧的会被逐出并连带清理悬挂边；Web 端看到的只是窗口视图，完整记录以 pentest_state / pentest_report 读取持久化层为准（来源：src/dsh-pentest/src/projection.ts:88-90、README.md:78-79）
• pentest_add_goal 是会话内的特权操作，任何拿到工具的 agent 调用一次就会清空整张图并把 id 计数器归零；运行中误调等同于删除本会话全部渗透数据（来源：src/dsh-pentest/src/store.ts:241-256、docs/goal-reset.md:1-9）
• 不支持跨会话或跨项目续跑同一份记录——记录按会话隔离，重新开始一次 engagement 只能新建 goal（来源：src/dsh-pentest/README.md:115-118、README.md:77）
• 插件不做授权门禁：authorization 仅作为审计字段写入 goal 与最终报告，沙箱/审批仍由部署侧负责（来源：src/dsh-pentest/src/spec.ts:42-46、README.md:74-76）
• 子 agent 的回写目前没有任何机制校验主 agent 是否把发现"完整转录"，依赖决策 agent 自觉（来源：src/dsh-pentest/README.md:121）
• Web 端的探索图与资产图使用静态分层布局，只支持平移缩放，节点不可拖拽（来源：README.md:80、src/dsh-client-ui-pentest/README.md:55-56）
• sqlite 后端在多 agent 同时写同一会话时只靠 storage-domain 的单域串行保证，并发多 agent 写入同一会话不会被额外排队（来源：src/dsh-pentest/README.md:122-123）
• 持久化后端依赖 Node 自带 node:sqlite，因此宿主 Node 必须 ≥ 22.5；老版本 Node 上 sqlite 行会在打开数据库时失败（来源：packages/dsh-storage-sqlite/lib/index.js:3、docs/storage.md:4）
• Web "渗透"标签页是只读视图，暂停、重置、继续 engagement 仍要回到主 agent 的 pentest_* 工具或未来的命令面（来源：src/dsh-client-ui-pentest/README.md:50-52）

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

本目录是自包含 bundle 包（@howmp/dsh-pentest）：宿主插件、Web 界面和 sqlite 后端通过包内 exports 一同分发。Release 资产可直接由 dsh plugin add 安装。

安装

从 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 后，在新会话中选择自动注册的「渗透模式」。

界面预览

模式选择

对话与执行

探索链路

漏洞视图

资产视图

测试报告

架构速览

• 领域模型（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 }， 镜像 store 的引用拒绝；上限各 200。
• Web 标签页（src/dsh-client-ui-pentest）：按会话注册（当前会话或列表祖先链含 pentest 预设即显示， 非渗透会话隐藏）；四个子标签——探索链路（@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。
• Web 图为窗口视图：会话投影各保留最新 200 个节点/资产/边（超出后最旧被逐出，悬挂边同步清理）。 UI 计数与图反映的是该窗口；完整记录以 pentest_state / pentest_report（读存储层）为准。
• 图布局为静态分层（可平移缩放，节点不可拖拽）。
• 运行时要求：sqlite 后端使用 Node.js node:sqlite，宿主运行时需 Node.js >= 22.5。

目录结构

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             #   宿主渗透插件：8 个 pentest_* 工具 + 协议注入 + 会话投影
│   ├── preset-root.js          #   注册包内只读「渗透模式」预设目录（兼容 DSH rc.6）
│   ├── storage-sqlite.js      #   渗透记录专用的 sqlite 后端（node:sqlite）
│   ├── ui-pentest.js          #   Web 插件宿主半：空 apply
│   ├── ui-pentest.client.js   #   Web 插件浏览器半：渗透视图标签页（3 个子标签，@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