dsh-vulnsec-bridge
把 VulnClaw（AI 渗透测试 CLI）与 DeepSec（Shield 代码审计 + Spear 授权渗透）包装成 DeepSeek Harness (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 页面，下载最新的 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 步。
方式二：从源码构建（开发者）
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（MIT）—— AI 渗透测试框架 - DeepSec（MIT）—— Shield 代码审计 / Spear 授权渗透
- 使用前请阅读各自的安全声明（仅限已授权目标）