dsh-vulnsec-bridge

Readme

# dsh-vulnsec-bridge

把 [VulnClaw](https://github.com/Unclecheng-li/VulnClaw)（AI 渗透测试 CLI）与 [DeepSec](https://github.com/Unclecheng-li/DeepSec)（Shield 代码审计 + Spear 授权渗透）包装成 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/dsh) 插件：**18 个安全工具 + 图形化「安全工具台」**，零第三方运行时依赖（桥接层只调用 DSH 官方 subprocess 服务）。

> ⚠️ **仅限已授权目标**：所有渗透类功能只应作用于你拥有或已获得书面授权的系统，请遵守当地法律与目标方的授权条款。

## ✨ 特性

- **图形化安全工具台**：设置 → 「安全工具台」页签，或侧边栏底部「⛨ 安全工具台」入口（全屏面板）
- **VulnClaw 全流程**：信息收集 / 漏洞扫描 / 漏洞利用 / 一键全流程 / 目标驱动求解
- **DeepSec Shield**：三层代码审计（L1 启发式 <50ms / L2 AST <2s / L3 LLM 语义），text/json/sarif/markdown 输出
- **DeepSec Spear**：端到端授权渗透（recon → explore → fact → reflect → report → PoC），目标必须在 scope 白名单内
- **一键审计**：输入目录即审计，发现风险实时提示
- **插件安全审查**：新加载的第三方插件自动执行 Shield 扫描（24h 去重），支持手动指定审查
- **LLM 三要素配置**：Provider / Base URL / 模型名 / API Key + 连通性测试
- **一键安装 CLI**：自动探测 Python → 创建独立 venv → 从 CDN 拉取源码 → pip 安装并验证（幂等，约几分钟）
- **全控件悬停提示**：鼠标停留在任意按钮/输入框上即显示功能说明

## 📥 下载与安装

### 环境要求

| 依赖 | 要求 | 说明 |
|---|---|---|
| DeepSeek Harness (dsh) | 任意 0.1.x | 插件只使用官方稳定服务（tools / subprocess / webServer / slots），peerDependencies 范围宽（`dsh-tools >=0.1-rc <2`、`cordis >=4-rc <5`） |
| Node.js | ≥ 22.13 | 构建与一键安装脚本所需 |
| pnpm | 任意 9+（或 corepack） | `dsh plugin` 内部转发 pnpm；无 pnpm 时按「方式二手动」 |
| Python | 3.10+（可选） | 仅「一键安装 CLI」需要（自动探测；已有 venv 或已装 CLI 则不需要） |
| 网络 | 可选 | 仅「一键安装 CLI」从 jsdelivr CDN 拉取源码时需要；插件本身与审计功能完全离线 |

### 部署结构（路径无关性说明）

插件**不依赖任何固定安装路径**：venv、审计记录等全部按「插件所在目录」相对推导：

```
<任意目录>/                ← 你放置插件的目录（无空格路径，如 C:\dsh-plugins）
├── dsh-vulnsec-bridge/    ← 插件目录（本包）
│   ├── lib/  index.js  package.json  scripts/  ...
└── sec-tools-venv/        ← 「一键安装 CLI」创建的 venv（自动推导，无需配置）
```

- venv 默认 = `<插件目录>/../sec-tools-venv`（host 端与一键安装脚本推导规则一致）；
- 需要换位置时设置环境变量 `VULNSEC_VENV`（host 端）或 `--venv <路径>`（安装脚本）；
- CLI 定位顺序：`VULNSEC_VULNCLAW` / `VULNSEC_DEEPSEC` 环境变量 → venv → PATH；
- 工具台状态条会显示插件版本（`/vulnsec/api/status` 的 `version` 字段），便于核对部署版本。

### 方式一（推荐）：从 Releases 下载安装包

1. 打开 [Releases 页面](https://github.com/MariNanari/dsh-vulnsec-bridge/releases)，下载最新的 `dsh-vulnsec-bridge-<版本>.tgz`（安装包，含构建产物，无需自己编译）；
2. 解压得到目录 `package/`，**将其重命名为 `dsh-vulnsec-bridge`**（重要：依赖名取自目录名，保持与包名一致）；
3. 装配到 DSH（官方命令，安装后**自动**把插件加入 bundles 装配层）：

   ```bash
   # ⚠️ 路径中不要包含空格！Windows 下 dsh 以 shell 方式转发 pnpm，
   #    空格路径会被拆成多个参数导致安装失败；如路径含空格，请先
   #    把插件目录复制到无空格路径（如 C:\dsh-plugins\dsh-vulnsec-bridge）
   dsh plugin --profile web add C:\dsh-plugins\dsh-vulnsec-bridge
   ```

4. **重启 DSH**，进入 设置 → 「安全工具台」即可使用。

> **故障排查**：若安装后工具台未出现，检查 profile 的 `package.json`：
> - `dependencies` 中应有 `"dsh-vulnsec-bridge": "link:<你的路径>"`；
> - `dsh.profile.bundles` 中应包含 `"dsh-vulnsec-bridge"`（`dsh plugin add` 成功后会**自动**写入，无需手动编辑）；
> - 若 `dependencies` 出现了 `"Deepseek"`、`"package"` 等奇怪条目，说明路径含空格被拆参——删除这些条目后，把插件放到无空格路径重新执行第 3 步。

### 方式二：从源码构建（开发者）

```bash
git clone https://github.com/MariNanari/dsh-vulnsec-bridge.git
cd dsh-vulnsec-bridge
npm install -D tsdown typescript @types/node
npx tsdown            # 产出 lib/index.js（host）+ lib/client.js（browser）
# 然后按方式一的第 3、4 步装配
```

### 安装安全 CLI（VulnClaw / DeepSec）

插件本身不捆绑 CLI，两种方式二选一：

- **图形界面**：安全工具台 → 状态条 → 「⚡ 一键安装 CLI」按钮（推荐）
- **命令行**：`node --use-system-ca scripts/install-cli.js`（本机代理证书链需要系统 CA）

> 一键安装脚本会创建独立 venv 并安装两个 CLI，幂等可重复执行。

## 🚀 快速上手

1. 安装插件并重启 DSH，打开 设置 → 「安全工具台」；
2. 若状态条显示 `vulnclaw ✗` / `deepsec ✗`，点击「⚡ 一键安装 CLI」；
3. 状态条变绿后：
   - **代码审计**：Shield 卡片输入项目路径 → 检测层选 `all` → 「一键审计」；
   - **授权渗透**：先到 Scope 卡片把目标加入白名单 → Spear 卡片输入目标 + 授权文件 + 模式 → 执行；
   - **LLM 语义分析（L3）**：配置卡片填写 Provider/Base URL/模型名/API Key → 「测试连接」。
4. 鼠标悬停任意控件查看说明；结果实时显示在底部日志区（脱敏 + 截断）。

## 🧰 工具清单

| 工具 | 说明 |
|---|---|
| `sec_tools_status` | 检查两个 CLI 是否可用（定位到的可执行文件路径与版本探测） |
| `sec_tools_install` | 一键安装 CLI：创建独立 venv、从 CDN 拉取源码、pip 安装并验证（幂等） |
| `vulnclaw_recon` / `vulnclaw_scan` / `vulnclaw_exploit` | 信息收集 / 漏洞扫描 / 漏洞利用（⚠️ 仅限授权目标） |
| `vulnclaw_run` / `vulnclaw_solve` | 一键全流程 / 目标驱动求解（⚠️ 仅限授权目标/CTF） |
| `vulnclaw_report` / `vulnclaw_config` | 会话报告 / 配置管理（LLM 提供商切换等，敏感值脱敏） |
| `deepsec_shield_scan` | Shield 代码审计：L1/L2/L3 全层扫描，text/json/sarif/markdown 输出 |
| `deepsec_shield_agent_audit` / `deepsec_shield_supply_chain` | agent 配置审计 / 供应链与幻觉包检查 |
| `deepsec_spear_recon` / `deepsec_spear_run` | Spear 侦察 / 端到端授权渗透（目标必须在 scope 白名单内，否则拒绝） |
| `deepsec_scope` / `deepsec_config` / `deepsec_report` | 授权范围管理 / 配置 / 报告生成 |
| `deepsec_audit_all` | 一键审计：Shield 全层扫描 → 供应链检查 → agent 配置审计，合并输出 |

## 🌐 Web API（供安全工具台 UI 调用）

| 端点 | 说明 |
|---|---|
| `GET /vulnsec/api/status` | CLI 状态（vulnclaw/deepsec 路径 + 版本） |
| `POST /vulnsec/api/run` | 执行任意工具 `{tool, target, ...}` |
| `POST /vulnsec/api/scope` | scope 白名单操作 `{action: list\|add\|verify, target?}` |
| `POST /vulnsec/api/config` | LLM 配置 `{which: vulnclaw\|deepsec, action, provider?}` |
| `POST /vulnsec/api/llm:test` | LLM 连通性测试 |
| `GET/POST /vulnsec/api/audits` | 插件安全审查记录 / 手动触发审查（`force` 可绕过 24h 去重） |
| `POST /vulnsec/api/install` | 一键安装 CLI |

## 🔍 CLI 定位顺序

1. 环境变量 `VULNSEC_VULNCLAW` / `VULNSEC_DEEPSEC`（可执行文件绝对路径）
2. 默认 venv：`<插件目录>/../sec-tools-venv`（可用 `VULNSEC_VENV` 覆盖）
3. PATH 兜底

## 🛡 安全设计

- 所有渗透类工具描述声明「仅限已授权目标」；DeepSec Spear 自带 scope 白名单闸门（不在白名单内直接拒绝）
- 工具输出自动脱敏（`sk-…` API Key、secret 值、私钥块）
- 输出截断至 120KB，防止大响应污染上下文
- 新加载的第三方插件自动执行 Shield 扫描（官方与内置插件自动跳过）

## 🛡 版本兼容策略（DSH 升级防崩溃）

DSH 版本迭代较快，本插件按「**防御式适配**」设计，升级 DSH 后**不会因 API 变化而崩溃**：

- **apply 永不抛错**：宿主与浏览器端初始化整体 try/catch——任何服务缺失/形状变化都只降级（日志记录），绝不向上抛导致 fiber 失败或 DSH 启动崩溃；
- **能力探测**：`tools` / `subprocess` / `webServer` 服务经 `ctx.get` 安全获取（属性回退），缺失时自动降级（工具不可用时返回明确错误信息，而非崩溃）；
- **逐项容错**：单个工具注册失败只跳过该工具，不影响其余注册与 Web API；
- **依赖最小化**：inject 仅声明 `tools` / `subprocess` / `webServer`（宿主）与 `slots`（浏览器），peerDependencies 范围宽（`dsh-tools >=0.1-rc <2`、`cordis >=4-rc <5`）；
- **升级自检**：升级 DSH 后运行 `node scripts/selftest.mjs`（随包提供）——mock 三种场景（完整服务 / 服务全缺 / 部分服务）验证 apply 不抛错、工具注册数与路由正常；
- **版本核对**：工具台状态条 / `/vulnsec/api/status` 的 `version` 字段为插件自身版本，`/vulnsec/api/status` 的 `status` 段回显 CLI 探测结果——升级后一眼确认插件与 CLI 状态。

**回退方案**：若新版本 DSH 出现不兼容（工具台消失且状态条异常），`dsh plugin --profile web remove dsh-vulnsec-bridge` 可随时移除；本插件不修改任何 DSH 官方文件，卸载即净。

## 📁 仓库文件结构（注脚）

| 文件 / 目录 | 作用 |
|---|---|
| `src/index.ts` | 宿主端（Node）源码：18 个安全工具注册、`/vulnsec/api` Web 路由、插件加载自动审查钩子、CLI 探测/安装逻辑 |
| `src/client/index.tsx` | 浏览器端源码：安全工具台 UI（设置页签 + 侧边栏入口 + 全屏面板 + 自绘 tooltip） |
| `lib/` | tsdown 构建产物：`index.js`（宿主 ESM）、`client.js`（浏览器 CJS bundle）、`index.d.ts`（类型声明）、`.map`（源码映射） |
| `scripts/install-cli.js` | 一键安装脚本（Node ESM）：Python 探测 → venv 创建 → CDN 拉取 VulnClaw/DeepSec 源码 → pip 安装 → 验证 |
| `scripts/selftest.mjs` | 部署自检脚本：mock 三种服务场景验证 apply 不抛错（升级 DSH 后建议运行） |
| `cordis.patch.yml` | bundle 装配补丁：声明插件入口（`id: vulnsec-bridge`），由 DSH 装配机制加载 |
| `index.js` | 包根 shim：`export * from './lib/index.js'`（cordis loader 以裸包名加载时的入口） |
| `package.json` | 包元数据：`dsh.client` 声明（浏览器 bundle 注入）、构建脚本、peerDependencies |
| `tsconfig.json` | TypeScript 编译配置 |
| `tsdown.config.ts` | 双端构建配置：host ESM（Node）+ client CJS（浏览器，`__ModuleLoader__.load` 包装） |
| `CHANGELOG.md` | 修改记录（版本对比与修复详情） |
| `README.md` | 本文档 |
| `LICENSE` | MIT 许可证 |

## 📝 修改记录

见 [CHANGELOG.md](./CHANGELOG.md)。

## 📄 许可与致谢

- 本插件：MIT License（见 LICENSE）
- 集成的 CLI 均为 MIT 许可的开源项目，本插件**仅以子进程方式调用、不包含其代码**：
  - [VulnClaw](https://github.com/Unclecheng-li/VulnClaw)（MIT）—— AI 渗透测试框架
  - [DeepSec](https://github.com/Unclecheng-li/DeepSec)（MIT）—— Shield 代码审计 / Spear 授权渗透
- 使用前请阅读各自的安全声明（仅限已授权目标）