@dsh-external/dsh-voredteam

Readme

# dsh-voredteam

> **DSH 插件形态的单模式安全作战系统**：一个模式（`网络安全模式`），一套可审计的作业法。
> 核心范式：**把渗透测试还原为状态空间搜索** —— 黑板（Fact）+ 显式「事实 → 意图」图。
> 组织形态：**总控做 reason，12 个专业子 agent 做 explore**，成果与覆盖度集中在作战面板。
> 唯一硬约束（门禁）：**禁 DDoS / 禁爆破 / 模糊测试低频化**。

它不是"一个会打靶的模型"，而是**把一次授权测试当工程项目管起来**：谁在测哪个面、测到哪一步、哪些面没测、结论有没有证据与复核，全部落在库里、画在图上、写进报告。

---

## 目录

- [它解决什么问题](#它解决什么问题)
- [功能全景](#功能全景)
  - [1. 黑板书：Fact / Intent / Hint](#1-黑板书fact--intent--hint)
  - [2. 六阶段作业法 + 六张检查矩阵](#2-六阶段作业法--六张检查矩阵)
  - [3. 总控 reason + 12 个专业子 agent](#3-总控-reason--12-个专业子-agent)
  - [4. 作战面板（三个分栏 / 八泳道 / 按会话分类）](#4-作战面板三个分栏--八泳道--按会话分类)
  - [5. 设置面板（测绘 API / 技能 / MCP）](#5-设置面板测绘-api--技能--mcp)
  - [6. 唯一门禁：禁 DDoS / 禁爆破 / 低频模糊](#6-唯一门禁禁-ddos--禁爆破--低频模糊)
  - [7. 内置技能库（246 个可装载技能）](#7-内置技能库246-个可装载技能)
  - [8. 内置 MCP 注册表（19 条）](#8-内置-mcp-注册表19-条)
  - [9. 部署与运维](#9-部署与运维)
  - [10. 测试、验证与发布](#10-测试验证与发布)
- [目录结构](#目录结构)
- [快速开始](#快速开始)
- [关键设计](#关键设计)
- [已知缺口与权衡（如实说）](#已知缺口与权衡如实说)
- [许可与第三方](#许可与第三方)

---

## 它解决什么问题

大模型做渗透测试的典型失败模式：**跑得很欢，但说不清测了没有**。它会在图上看不见的地方反复试、把同一个面测三遍、遇到硬骨头就换方向，最后交一份"疑似/可能/建议进一步确认"的报告。

dsh-voredteam 用三件事把这件事拽回工程：

| 失败模式 | dsh-voredteam 的对策 |
|---|---|
| 不知道自己测过什么 | **黑板 + 资产清单 + 六张检查矩阵**：没登记进矩阵的东西等于没测 |
| 自述"测全了" | **阶段门禁**（`bb_phase_advance` 不满足就拒绝并列缺口）+ **覆盖矩阵**（谁缺哪一项，点名到 `asset:key`） |
| 结论靠脑补 | **证据三件套**（请求/响应、PoC、文件路径）+ **独立复核子 agent**（`bb_fact_review` confirm/challenge） |
| 反复重跑死路 | **死路也是资产**：`dead=true + note` 写清"试过什么、为什么不通"，图留痕 |
| 新会话继承上一次的图 | **一个会话一个项目**：会话是项目的唯一边界，子 agent 才按父会话/工作目录共享 |

---

## 功能全景

### 1. 黑板书：Fact / Intent / Hint

数据层是 SQLite（`node:sqlite`，同步 API），一个会话一块项目，**图 append-only**。

| 对象 | 含义 | 工具 |
|---|---|---|
| **Fact（事实）** | 已确认的客观事实：什么 + 在哪 + 如何验证 + 证据路径 | `bb_fact_add` / `bb_fact_deprecate`（推翻留痕）/ `bb_fact_review`（独立复核） |
| **Intent（意图）** | 一条待探索方向 = 图上一条边（`from[] → to_fact`），可认领、可结论、可判死路 | `bb_intent_propose` / `bb_intent_claim` / `bb_intent_release` / `bb_intent_conclude` |
| **Hint（人类提示）** | 人类在对话里给的范围/凭据/禁测项，总控每轮读图时吸收 | `bb_hint_add` / `bb_hint_list`（也可直接在面板上写） |
| **Asset（资产）** | 可测对象清单（domain / subdomain / ip / port / service / url / endpoint / js / repo / cred / cloud / app） | `bb_asset_add` / `bb_assets` / `bb_asset_update` |
| **Check（检查矩阵）** | 每个资产 × 六个 stage × 检查项的结论与证据 | `bb_asset_check` / `bb_asset_checks` |
| **Untested（未测面）** | 没做/做不了的面 + 为什么（报告必带） | `bb_untested_add` |

- **23 个工具**：21 个 `bb_*` + 2 个角色卡工具（`vore_agent_card` / `vore_agents_list`）。
- **逐轮图快照注入**：每一步系统提示里都带当前阶段、六张矩阵的百分比、未测面声明状态、复核进度、待认领意图、最近事实、人类提示 —— 模型不必"记得"，它每轮都看得见。
- **多项目与迁移**：主键含 `project_id`（同一 `f001` 可在不同项目共存）；旧库启动时自动迁移（含幽灵项目补 `origin/goal`、五阶段→六阶段一次性改写）。
- **回灌**：任何阶段发现新资产 → 六张矩阵同时出现缺口，且**阶段自动退回 P1 起点**（`reflow_pending=1`），必须先再收一轮确认"连续 0 新增"才解封。

### 2. 六阶段作业法 + 六张检查矩阵

```
P1 起点 ── 多来源并发收集（子域/DNS · 端口/服务 · URL/接口 · JS/仓库/云）
   │        每轮收尾 bb_coverage {endRound:true}；连续一轮 0 新增 → 饱和出关
   ↓
P2 信息收集 ── 逐资产「信息全采」：info 矩阵 BASE 12 项
   │        tech / lang / middleware / os / arch / dirs / paths / cert / dns / waf / third / sec
   │        按 kind 追加：js→jsrev+params · url/endpoint→params · ip/port/service→banner
   │                     app→client · repo→repo · cred→cred · cloud→cloud · domain/subdomain→sub
   ↓
P3 浅层 ── ① verifyInfo 矩阵：**逐条核实信息收集的产出**（ok / wrong / unknown，wrong=采错了）
   │        ② shallow 矩阵 8 项：fp 指纹行为验证 · pathTruth 路径真值 · params 参数面与基线 ·
   │           authEdge 鉴权边界 · errLeak 错误与信息泄露 · expose 暴露面存在性 ·
   │           lowFuzz 低频模糊 · compHint 组件版本线索
   ↓
P4 中间层 ── ① verifyShallow 矩阵：**核实浅层的每一项**（有没有证据、有没有漏）
   │          ② owasp 矩阵：OWASP Top 10 (2021) A01–A10 逐类测试
   ↓
P5 深层 ── ① 完整读取该资产已有全部信息 ② 核验中间层结论（必须 reviewed）
   │        ③ deep 矩阵 8 类：unauth / authz / inj / ssrf / upload / logic / race / deser
   ↓
P6 成果 ── 缺口清零 → 未测面声明 → 每条漏洞事实复核 → 证据索引 → 报告
```

**纪律**：每一层先核实上一层，再做本层的工作。**六张矩阵是唯一判据**（`assets.s2/s3` 只是自动同步的汇总位）：

- `na`（不适用）/ `wrong`（采错了）/ `unknown`（无法核验）**必须写理由**，理由太短直接拒绝；
- `hit`（命中）**必须给证据**；`reviewed` 是漏洞事实进报告的前提；
- 未测面必须写"为什么没做/做不了"（≥4 字），报告必带；
- 覆盖范围按优先级收敛：`info` / `verifyInfo` 要求**所有**资产；后四张只要求 `priority ≥ 3`，低优先资产必须在登记时写明"为什么不要求"，即**可审计的降级**，不是偷偷免测。

### 3. 总控 reason + 12 个专业子 agent

| 子 agent | 领域 |
|---|---|
| `recon` | 侦察测绘：子域/端口/URL/指纹/证书/DNS |
| `js-reverse` | 前端 JS 逆向：接口、密钥、签名、加密、路由 |
| `api-security` | 接口安全：未鉴权、越权、参数面、导入导出 |
| `web-injection` | 注入类：SQLi / XSS / 模板 / 命令 / 反序列化链 |
| `auth-logic` | 认证与会话：账号接管、鉴权边界、业务逻辑、竞态 |
| `component-cve` | 组件与版本 → 公开漏洞线索与验证 |
| `app-reverse` | 客户端逆向：小程序/App 包、加固、协议 |
| `internal-network` | 内网：横向、凭据复用、AD 面（在授权边界内） |
| `cloud-ai` | 云资源与 AI 面：桶/元数据/密钥/LLM 接口 |
| `exploit-dev` | 利用开发：把线索做成可复现 PoC/EXP |
| `reviewer` | 独立复核：只拿原始材料，二选一 confirm/challenge |
| `reporter` | 报告：按 vore-report 七项规范出交付物 |

- 角色卡在 `agents/*.md`（含**授权与边界 / 输入前置条件 / 纪律 / 工作方法 / 黑板协议 / 输出格式 / 六矩阵责任表**）。
- 派单 = **`vore_agent_card <role>` 读出角色卡整段 + 四要素**（目标标识 / 授权边界 / 唯一子目标 / 成功标准）+ `intent_id` + **`project=<项目 id>`** + 本单要覆盖的资产与检查项清单。
- 并行：无依赖方向一次并行派多个（`subagent` / `workflow` 扇出）；有依赖的串行。
- **总控不许替子 agent 脑补结论**，也不许替它把检查行标 `done/ok/hit` —— 检查行由执行者写，总控只核对。

### 4. 作战面板（三个分栏 / 八泳道 / 按会话分类）

会话页签「作战面板」，三个分栏：

**① 实时情况（八条泳道，从上到下）**

```
① 起点       origin 锚点 + 资产数/收集轮次
② 信息收集   资产节点：info x/y · 百分比
③ 浅层       资产节点：verifyInfo + shallow · ⚠ 待核实 n
④ 中间层     资产节点：verifyShallow + owasp · 命中 n
⑤ 深层       资产节点：deep x/8 · 命中 n
⑥ 线索       分两组上下摆：**已确认事实** / **未确认（疑似结论 + 待探索方向）**
⑦ 死点       死路意图 + 被推翻的结论（灰色虚框，留痕不消失）
⑧ 成果       goal + category=vuln 事实（按严重级排序）
```

- 同一资产的四层之间用纵向连线串起来；**信息收集没采全的资产不画后面三层**（宁严勿松）；
- 一条泳道一行最多 10 个节点，**超了自动换行**（真实作业里资产上百个，一行排下去会把图拉成两万多像素宽的口袋阵）；
- **交互**：点节点看详情、滚轮缩放、拖拽平移、右上角「适应窗口 / ＋ / －」**钉在画布外层**（滚图不会把工具条带走）+ 缩放百分比；
- **全屏**：优先 Fullscreen API，被浏览器拒绝时自动降级为 CSS 兜底全屏；进全屏后**按新容器重算缩放**（rAF + 定时 + resize），缩放下限 0.05；
- **右侧详情栏可拉伸/收起**：拖分隔条改宽度（220px .. 面板宽度−320px）、松手落盘、双击复位 330px、`⟩/⟨` 收起展开；显示选中对象完整字段 + 六张矩阵逐项状态，未选中时显示**待认领意图**、**人类提示**与**写一条提示**输入框（Enter 提交 → 面板写 hint，总控下一轮读图吸收）；
- **回灌横幅**：`reflow_pending=1` 时顶部提示「已退回 P1 起点，先再收一轮」；
- **字体与配色自己说了算**：SVG 文本 `fill` 写死（SVG 默认黑字在深色底上等于隐身），浅/深两套 `--vore-ink`/`--vore-canvas-bg`，画布自带不透明底色 + 网格，字体栈带中文。

**② 任务汇总**：成果计数徽章（critical/high/medium/low）+「复制 Markdown」（成果表 + 死路清单，可直接贴进报告）+ 成果表（点行展开描述/POC/修复建议/证据路径）+ 资产与接口折叠区 + 死路与未排除面。

**③ 覆盖矩阵**：六阶段完成度（P1–P6，各自缺口数 + `asset:key` 点名）+ **六张矩阵**完成度 + `na` 与"真测过"分列（防止用 `na` 刷满覆盖率）+ 未测面清单（含未测原因，未声明会标红）+ 复核进度（已复核/待复核，未清零就提示 P6 不能收口）+ 按类别统计 + 资产明细（点行进详情）。

**会话分类（一个会话一个项目）**：

- 顶栏 **「会话」下拉**：本会话一个选项 + 其他会话按 `<optgroup>` 分组（选项里直接写 `阶段 · 资产 N · 事实 N`）；点开历史项目 = **钉住**，出黄色横幅 + 「回到本会话」；
- **本会话还没有黑板**时**不借别人的图**，显示空态 + 历史项目清单（按会话归类，点一条就打开）+ 「或直接给本会话建黑板」（origin/goal 输入框 → `project.create`）；
- 后端解析口径：`projectId`（人点开的历史项目）> 本会话 `sessionId` > **null**；**没有"猜一个最近项目"的档**（那正是"新会话继承了上一次测试面板"的病根）；
- 子 agent 例外：按 **父会话 → 工作目录** 回退命中同一张图（顶层会话绝不按目录借）。

**面板运维**：

- **删除该面板**（红框）：删掉当前显示的那一块（项目 + 事实/意图/提示/资产/检查矩阵/未测面），**删前自动落一份 `VACUUM INTO` 一致性备份**（`blackboard.backup-<本地时间>.db`），删除是一个事务、失败整体回滚；
- **强刷页面**：带时间戳重载，强制重新下载客户端 bundle（等价 Ctrl+F5）；
- **自动刷新**：3 秒轮询（页面隐藏时暂停）；三个端点相互独立，任一失败只影响它对应的分栏。

### 5. 设置面板（测绘 API / 技能 / MCP）

双入口：会话页签「设置」+ 设置弹窗里的「dsh-voredteam 设置」一节。

- **测绘 API**：FOFA / Shodan / YesCaptcha / Grok 网关的 key 与限速，读写 `~/.dsh/voredteam/settings.json`（**密钥只回显掩码**，绝不明文返回）；
- **技能管理**：列出内置技能根、扫描技能（`vore_skill_search` 用）、显示条数与目录体积；
- **MCP 管理**：勾选启用/停用注册表条目，展示缺哪个环境变量、端口是否在听；
- **速率门禁参数**：模糊测试的默认速率上限等阈值由这里下发（与 `vore-guard` 共用）。

### 6. 唯一门禁：禁 DDoS / 禁爆破 / 低频模糊

位置在 `plugins/vore-guard`，挂在 `ctx.tools.guard()`（**命令执行前的确定性拦截缝**），只对 `网络安全模式` 会话及其子 agent 生效。

1. **禁 DDoS**：洪水、压测、连接耗尽、并发打满一律拦；
2. **禁爆破**：不做字典爆破；`hydra` / `kerbrute` / `netexec` / `nxc` / `--password-file` 等命中即拦（离线 `hashcat`/`john` 放行；`impacket-*` / `bloodhound-python` / `smbclient -U` / `curl -u` 这类**凭据复用**放行）；
3. **模糊测试必须显式低频**：ffuf ≤50、dirsearch/gobuster/wfuzz ≤10、nuclei ≤50；nmap 全端口/大范围必须带 `--max-rate` 且 ≤ `defaultRps×60`（夹紧 100..1000）——`-T4` 与 `--min-rate` **不算**限速。

- **误报治理是这件事的一半**：注释/路径参数（`-Path`）、工具名不在命令词位置、`impacket-*` 前缀等都会被误判，规则已按"命令词位置 + 语义"重写；
- **拒绝文案自带降级路径**（先小样本 ≤50 → 显式限速 → 去重 → 命中即停），判定落 `<workspace>/vore-guard-log.md`，事后可复核。

### 7. 内置技能库（246 个可装载技能）

- `skills/`：本项目自研 4 个（黑板规程 / 六阶段作业法 / 报告规范 / 速率门禁细则）；
- `vendor/skills/`：**内置的第三方技能库**（真实文件，非目录联接）：`claude-red` 50 · `claude-red-legacy` 28 · `reverse-skill` 43 · `anthropic` 120 · `clown` 1；
- `skills/registry.yaml`：**247 条**技能盘点（path 全为仓库相对路径，由 `npm run registry:gen` 从真实文件生成）；
- `npm run skills` 按宿主"一层深度"规则算出**真正可装载**的条数；`npm run vendors` 校验内置内容与源库逐字节一致；
- 出处与许可证见 `vendor/THIRD-PARTY.md` + `vendor/licenses/`。

### 8. 内置 MCP 注册表（19 条）

`mcp/registry.yaml`：C2（AdaptixC2，89 个工具）、资产测绘（FOFA）、抓包/逆向、浏览器与移动端等，**路径与密钥全用 `${VAR}` 占位符**（可发布）；缺变量的条目会被标成"未配置（缺哪个变量）"，本机填法见 `mcp/registry.local.example.yaml`，启动顺序与已知坑见 `mcp/NOTES.md`。

### 9. 部署与运维

```bash
node deploy/deploy.mjs              # 只读体检（逐项 ✓/✗）
node deploy/deploy.mjs --dry-run    # 预演：要改哪些文件、备份叫什么
node deploy/deploy.mjs --apply      # 幂等应用：重建预设实体目录 + 备份并更新 profile package.json + 建 node_modules 链接
```

- 预设落盘时把 `{{PROJECT_ROOT}}` 渲染成本机绝对路径（宿主只认绝对路径）；
- `deploy/restart-dsh-web.ps1`：延迟 → 停旧 → 起新 → 健康检查，全程写日志（脚本内**不含任何机器路径**，默认值取 `$env:DSH_CHECKOUT` / `$env:DSH_HOME`）；
- **可移植性硬约束**：出厂文件不含本机绝对路径，由 `tests/portability.test.mjs` 守着。

### 10. 测试、验证与发布

```bash
npm test      # 193 项离线断言（不需要 DSH 运行）
npm run verify   # 88 项全量验证（逐条 stat / bundle 新鲜度 / 预设一致性 / 安装态）
npm run accept   # 25 项验收自检（结构 / 契约 / 角色卡 13 份 / 零禁用引用）
npm run deploy -- --check   # 28 项部署态校验
```

| 套件 | 项数 | 覆盖 |
|---|---|---|
| `tests/smoke.mjs` | 46 | 黑板引擎 + 六阶段门禁 + 六张矩阵 + 回灌 + 多项目/迁移 + 门禁边界 |
| `tests/registry.test.mjs` | 9 | 247 条技能 & 19 条 MCP 契约解析 |
| `tests/preset.test.mjs` | 11 | 预设组合行与插件元数据 |
| `tests/load.mjs` | 27 | 假宿主 ctx 真装载：工具面、HTTP 通道、按会话解析、删除面板与备份、门禁 |
| `plugins/vore-console/tests/console.test.mjs` | 27 | 八泳道/线索分组/适应窗口/配色/Markdown/HTTP(403 重试)/槽位注册 |
| `plugins/vore-console/tests/panel-render.mjs` | 27 | 迷你 React 真渲染：hook 数量守恒（防 React #310 白屏）、全屏、工具条固定、右栏拉伸、会话分类、删除面板、毒化载荷不白屏 |
| `plugins/vore-settings/tests/settings.test.mjs` | 29 | 设置读写/掩码/技能扫描/MCP 清单/面板渲染 |
| `tests/client-contract.mjs` | 17 | 客户端 bundle 契约（factory 形参 / 槽位 / 在线下发字节） |

发布前另有两个手动检查：`tests/_secret-scan.mjs`（把本机 `settings.json` 里的真实密钥拿去全仓比对，**不回显密钥**）与 `tests/_privacy-scan.mjs`（本机绝对路径泄漏）。

---

## 目录结构

```
modes/network-security/     预设（persona + 组合行：工具面 / 技能 / 子代理 / MCP）
agents/                     13 份角色卡（总控 + 12 专业子 agent）
skills/                     自研技能 4 个 + registry.yaml（247 条盘点）
vendor/skills/              内置第三方技能库（真实文件；出处与许可见 vendor/THIRD-PARTY.md）
mcp/                        内置 MCP 注册表（19 条，占位符化）
plugins/vore-blackboard/    黑板引擎：数据层 + bb_* 工具 + 角色卡工具 + HTTP API + 逐轮快照注入
plugins/vore-console/       作战面板（实时情况 / 任务汇总 / 覆盖矩阵）
plugins/vore-settings/      设置（测绘 API / 技能 / MCP / 速率）
plugins/vore-guard/         唯一门禁
docs/                       体系结构 · 覆盖缺口 · 验证与事故复盘（20 章）· 技能盘点 · 离线测试
deploy/                     一键部署 CLI + 重启脚本
tests/                      离线测试套件
```

## 快速开始

```bash
# 0) 前置：一个可用的 DSH 检出（本插件依赖宿主扩展点：tools / slots / systemPrompt / webServer / guard）
export DSH_HOME="$HOME/.dsh"
export DSH_CHECKOUT="/path/to/deepseek-harness"

# 1) 只读体检 → 2) 预演 → 3) 应用
node deploy/deploy.mjs
node deploy/deploy.mjs --dry-run
node deploy/deploy.mjs --apply

# 4) 安装 profile 依赖并重启 dsh web，新建会话选「网络安全模式」
cd "$DSH_HOME/profiles" && pnpm install
pwsh -File deploy/restart-dsh-web.ps1 -DelaySeconds 25
```

打开会话页签「作战面板」，让总控 `bb_project_init` 写清 origin/goal，图就开始长。

## 关键设计

- **一条 intent 就是一条边**：`intent_sources` 存起点集合（多 from 即超边），终点是 `to_fact`；图 append-only，结构上不成环，无需环检测。
- **意图认领互斥**：同一方向同时只有一个 worker，避免重复劳动。
- **死路也是资产**：`bb_intent_conclude(dead=true, note=…)` 写清试过什么，后人不再重跑。
- **进度是数据不是自述**：阶段、资产清单、六张矩阵、未测面、复核都落在库里；模型不得自我宣布"测全了"。
- **每一层先核实上一层**：verifyInfo / verifyShallow 两张矩阵把"上一个阶段的工作"变成可核验的检查项。
- **人类随时介入**：面板写 hint、面板取消方向（记死路）、面板看缺口点名。

## 已知缺口与权衡（如实说）

- **会漏掉的测试面**：见 `docs/COVERAGE-GAPS.md`（缺 `env`/`vhost` 维度、来源类别只覆盖 7 类、`cloud/cred/repo` 类来源未做穷尽判定等），每条都写了缺什么、为什么、怎么补。
- **只有一条门禁是有意为之**：阶段门/矩阵/证据流程如果都做成硬门禁，真实作业里会变成"流程税"；严谨性改由**事实纪律 + 独立复核 + 证据落盘**保证。
- **第三方技能库的许可**：`vendor/skills/` 是内置的**第三方内容**（来源与许可证见 `vendor/THIRD-PARTY.md`，其中 `clown` 一项未标注许可证）。若你要把这些内容一并再分发，请先核对各自许可；只想发布本项目自身的代码时，可执行
  `git rm -r --cached vendor/skills && echo "vendor/skills/" >> .gitignore`。
- **面板的取舍**：全屏第一诉求是"看得见全貌"，资产上百个时适应窗口给出的比例偏小（看细节用滚轮/＋）。

## 许可

本项目自身代码：**MIT**（见 `LICENSE`）。第三方技能库与 MCP 的许可见 `vendor/THIRD-PARTY.md`。