dsh-pentester

Readme

# dsh-pentester

面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的最小化 Root-Orchestrator PTES 渗透测试插件。

**内置 962 个渗透测试 Skill**（6 个 bundle + 6 个 standalone），覆盖 Kali 工具、PTES 全阶段、CTF、逆向、漏洞知识库与报告生成。

**19 个内置专家 Agent** 按 PTES 阶段编排；MCP 集成支持 STDIO / Streamable HTTP / Legacy SSE 三种 transport（Legacy SSE 可直连 PortSwigger Burp MCP Server，无需代理中转）。PTES 阶段可为该阶段所有 Worker 共享 Skills / MCP server，也可配置跨阶段的 Global Worker 共享能力。

**唯一事实来源是 [`docs/plan.md`](docs/plan.md)**；架构视图见 [`docs/architecture.md`](docs/architecture.md)，磁盘布局见 [`docs/workspace.md`](docs/workspace.md)，领域术语见 [`CONTEXT.md`](CONTEXT.md)。Skill 能力运行时见 [`docs/skill-runtime-v4.md`](docs/skill-runtime-v4.md)（Native DSH Skill 集成）。

> **Builtin Skill Pack 独立分发**：上述 Builtin Skills 作为独立 GitHub Release Asset 分发，不随 npm package 安装。首次使用时在 **Settings → Pentester → Skills → 初始化 Builtin Skills** 点击下载安装。Custom Skills 放在 `$DSH_HOME/dsh-pentester/skills/`，与 Builtin Skill Pack 完全隔离。

> **Skill Runtime V4**：Worker 的 Skill 加载已完全融入 DeepSeek Harness 原生 Skill 生态 ——
> Delegation 创建时冻结 grant（Host-private snapshot + manifest），Worker 以官方
> `skill({name})` 工具按需加载，catalog 与会话记录由官方 `dsh-tool-skill` 产生，
> 前端直接用官方 Skill Row 渲染。旧 `pentester_skill_search` / `pentester_skill_load`
> 已退役（历史会话仍可回放）。

欢迎提交issues和PR。

详细英文文档见 [docs/README.md](docs/README.md)。

## 心智模型

```
User ⇄ DSH Root Session（pentester persona preset）
   → Root 是唯一 Orchestrator：判断缺口、派发 Delegation、决定推进/回溯阶段
   → Root 工具面 5 个：pentester_run / pentester_delegate /
     pentester_cancel_delegation / pentester_advance_stage / pentester_rollback_stage
   → pentester_run 是唯一生命周期入口（action: start | stop | resume | restart | status）
   → Root 每次 reasoning 前注入 compact run state（target/branch/stage/delegations）
Delegation（并行多个）= 各一个 DSH continuable child session（AgentProfile + 不可变 task_prompt）
   → Worker 工具：pentester_container_exec（dockerode）+ 官方 skill tool（child-scoped frozen SkillProvider，Root 不可见）
   → Worker 的 Skill catalog 由 Harness 官方注入（frozen grant 精确边界）
   → Worker 写/更新 result.md 作为当前可交付结果（continuable child 跨轮持续）
Deliverable = 文件（workspace/stages/<NN>-<stage>/delegations/D-00N/）
```
## docker based toolbox
> 设置界面
<img width="931" height="802" alt="image" src="https://github.com/user-attachments/assets/f79e9fd8-c2d2-43ff-92f7-3455ee26866a" />

仅通过dockerode与docker daemon交互，定期文件同步，允许远程docker server，可降低本机资源占用。

工具集详见 docker/kali

## 添加自己的 Skill

在 `~/.dsh/dsh-pentester/skills/` 下建一个文件夹放一个 `SKILL.md` 即可：

```
~/.dsh/dsh-pentester/skills/
└── my-waf-bypass.skill/
    └── SKILL.md      # name + description + 指令正文
```

目录热更新，无需重启；在 Settings → Agent Library 里 grant 给某个 Agent
后，之后新建的 Worker 会在原生 skill catalog 中看到它（模型自行决定
`skill({name})` 加载）。详见
[docs/skill-runtime-v4.md §4.1](docs/skill-runtime-v4.md)。

## Skill Runtime V4（原生 DSH Skill）

Worker 调用 Skill 与普通 DeepSeek Harness 会话完全同构：Agent Library
冻结 grant → child-scoped frozen SkillProvider → 官方 `dsh-tool-skill` 的
durable catalog 与 `skill({name})` 工具 → 标准的 `<skill_content>` 结果与
官方 Skill Row UI。

> Worker 会话里模型自主路由并加载 Skill（官方 Skill Row，与普通 DSH 会话无差异）
<img width="1325" alt="worker-native-skill-rows" src="docs/screenshots/v4-worker-native-skill-rows.png" />

> Trace 拓扑：每个成功加载的 Skill 是 Agent 节点外侧的一个芯片元素，用线连接
<img width="1325" alt="trace-skill-chips" src="docs/screenshots/v4-trace-skill-chips.png" />

> Output：每 Delegation 的 loaded_skills.md（native 会话事件审计投影）
<img width="1325" alt="output-loaded-skills" src="docs/screenshots/v4-output-loaded-skills.png" />

## Pentester Settings

Settings → Pentester 提供完整的插件配置面（Overview / Agent Library / Docker / Version 四个顶层 Tab）：

> Overview：状态摘要（Docker / Toolbox / Skills / Agents / MCP）+ PTES 阶段管线（每阶段参与编排的 Agent）
> <img width="1325" alt="settings-overview" src="docs/screenshots/settings-overview-ptes-pipeline.png" />

> Agent Library：19 个内置专家 Agent（按 PTES 阶段分工，可 Customize 覆盖 skill/MCP 分配）
> <img width="1325" alt="settings-agent-library" src="docs/screenshots/settings-agent-library.png" />

### PTES Assignment（Stage / Global 共享能力）

每个 PTES 阶段除了指派参与编排的 Agent，还可以配置该阶段所有 Worker 共享的 Skills 与 MCP server；页面顶部的 Global Worker Capabilities 则把共享能力下发给所有 Worker 阶段。共享能力是 additive 的（叠加在 Agent 自身能力之上），并在 Delegation 创建时冻结 —— 已创建的 Worker 不受后续配置变化影响。Root 不继承任何共享能力（仍是纯 Orchestrator 的正向 allow-list）。

### MCP 三种 Transport（含 PortSwigger Burp 兼容）

MCP Server 支持三种 transport：**STDIO**（本地进程）、**Streamable HTTP**（现代远端协议，推荐）、**Legacy SSE**（旧式 HTTP+SSE 兼容 —— 如 [PortSwigger Burp MCP Server](https://github.com/PortSwigger/mcp-server)，`http://127.0.0.1:9876`）。Legacy SSE 的 sessionId 握手由官方 MCP SDK 完成，无需手工配置；旧式 server 不再需要 mcp-proxy 中转。

> Transport 选择器（完整协议名称，不混淆两种 HTTP 协议）
> <img width="1325" alt="settings-mcp-transport" src="docs/screenshots/settings-mcp-transport-selector.png" />

> Burp Suite 以 Legacy SSE 直连：Loaded · 27 tools
> <img width="1325" alt="settings-mcp-burp" src="docs/screenshots/settings-mcp-legacy-sse-burp.png" />

### Version

Host / Client / Skill Pack 构建版本一目了然（host 与 client bundle 不一致时给出刷新提示）：

> <img width="1325" alt="settings-version" src="docs/screenshots/settings-version.png" />

## 展示
> 渗透测试模式
<img width="951" height="747" alt="image" src="https://github.com/user-attachments/assets/5eee1abc-016f-4455-ace9-b924b7e1a43e" />

> 授权确认
<img width="957" height="792" alt="image" src="https://github.com/user-attachments/assets/105802e6-3174-4237-81a8-714560b959b4" />

> 问题诊断
<img width="1031" height="808" alt="image" src="https://github.com/user-attachments/assets/bff95a27-d206-4d77-8b1f-4f0325e1d1db" />

> 使用docker镜像
<img width="994" height="670" alt="image" src="https://github.com/user-attachments/assets/d8eaf503-3e8c-4731-bdfc-9f666280909f" />


> 看板与子代理
<img width="1036" height="828" alt="image" src="https://github.com/user-attachments/assets/88b816b5-2c56-4cf2-b729-14098c3f3d6a" />

> 各个TAB
<img width="1049" height="801" alt="image" src="https://github.com/user-attachments/assets/9af17570-ae6e-4a29-b752-1f9252d8b08a" />

> 时间轴阶段拓扑
<img width="1057" height="818" alt="image" src="https://github.com/user-attachments/assets/022ea438-7432-49d5-9901-969797248b77" />

> 阶段产出
<img width="1052" height="797" alt="image" src="https://github.com/user-attachments/assets/2a1c6ba5-4755-490c-b4d3-96f2e2ba600a" />

> 子代理自动汇合推进
<img width="1019" height="783" alt="image" src="https://github.com/user-attachments/assets/30cf3fed-2d26-4564-bc32-9f963d152008" />

> 报告
<img width="1069" height="799" alt="image" src="https://github.com/user-attachments/assets/757586aa-939b-40d7-81c6-dfa5ccb07ae9" />

<img width="1049" height="793" alt="image" src="https://github.com/user-attachments/assets/40ff4485-45f0-4021-b6b5-a410279ce307" />

[查看报告](docs/test-report.md)

## 准备

安装deepseek harness

```bash
npm install -g @deepseek-ai/dsh
```

准备docker镜像
```bash
docker pull fb0sh/dsh-pentester-kali:latest
```

## 安装

```bash
# npm 源
dsh plugin --profile web add dsh-pentester@latest

# github 源
dsh plugin --profile web add github:fb0sh/dsh-pentester
```
安装后需要重启dsh

## 布局

| 目录/文件 | 职责 |
| --- | --- |
| `src/` | model/stages/store、workspace/git、dsh（childId 预留）/delegations/tools、docker/（host/connection/images/runtime）、rpc/settings-store、targets、migrate、host-manifest、invocations、build-id、index |
| `src/native-skill/` | Skill Runtime V4：frozen manifest、child-scoped SkillProvider（dsh-pentester-frozen）、agent/created mount seam、native audit 投影、legacy name 迁移 |
| `src/agent-library/` | Agent Library 组合根（profiles/skills/bundles/settings v2/watcher） |
| `src/pentest/` | pre-engagement/assets/findings 领域逻辑 |
| `src/ui/client/` | Settings 的 "Pentester Config" 页 + Pentester Tab（Stages/Trace/Findings/Output） |
| `src/ui-view/` | Pentester 数据面板（snapshot / native skill audit 投影 / RPC） |
| `agents/*/profile.yml` | 19 个 Builtin AgentProfile（Agent Topology V3：18 个进入默认 PTES 编排 + library-only ctf；见 docs/agent-skill-allocation.md） |
| `docker/` | Toolbox Dockerfile（kali 等，镜像白名单来源） |
| `presets/pentester/` | Root persona preset + `run-state.mjs`（工具面限制 + native skill provider 挂载 + 动态状态注入） |

## 开发

```bash
pnpm run check   # typecheck + build（含 client bundle）
pnpm test        # node --test
```

Docker host 优先级：Settings（settings.json）> 插件配置 > 本地 socket 自动发现 > `DOCKER_HOST` > 默认 socket。本地 Docker 按 Worker 白名单顶层目录逐目录 bind（`.git/` 与 `.dsh-pentester/` 物理上不在容器内）；远程 daemon 用共享 volume，阶段边界才做 mirror sync（push/pull 双向排除控制态、原子发布、不跟随 symlink）。