# dsh-pentest

> 为 DeepSeek Harness 提供"渗透模式"：在授权范围内记录目标、探索链路、漏洞与资产，并把整张图在 Web 端以可缩放视图实时展示。

## Metadata

- Author: [@howmp](https://github.com/howmp)
- Repo: <https://github.com/howmp/dsh-pentest.git>
- GitHub: [howmp/dsh-pentest](https://github.com/howmp/dsh-pentest)
- Stars: 141
- Language: JavaScript
- Topics: `deepseek-harness`, `dsh-plugin`, `dsh-plugins`, `pentest`
- Forks: 18
- Open Issues: 1
- Last push: 2026-08-20T05:28:37.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

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

## Wiki

## 一句话定位
把 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 围绕一个目标有结构地推进侦察、收集事实、确认漏洞，并把每一步记录下来以便随时复盘、出报告，而不需要手工整理日志或在多个工具之间切换。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness | 0.1.0-rc.6 | bundle 在该版本上构建；`peerDependencies` 全部钉到 `0.1.0-rc.6` |
| Node.js | >=22.5 | sqlite 后端使用 Node 自带 `node:sqlite`，需要宿主运行时 ≥ 22.5 |
| 平台 | macOS / Windows / Linux | 宿主本身跨平台；预设中 Windows 禁用 bash，macOS/Linux 禁用 pwsh |
| 原生模块 | `node:sqlite` | Node 自带，无需额外安装，但要求宿主 Node 版本满足上面的最低要求 |
| React | ^18.2.0 | Web 端 bundle 内嵌的运行时要求 |

## 安装方式
```bash
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`）

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-pentest](https://deepseek-plugin.org/plugins/howmp/dsh-pentest)
Wiki generated by AI (model: `MiniMax-M3`)