安全工具台MariNanari/dsh-vulnsec-bridge

dsh-vulnsec-bridge

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

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

✨ 特性

- 图形化安全工具台：设置 → 「安全工具台」页签，或侧边栏底部「⛨ 安全工具台」入口（全屏面板）
- VulnClaw 全流程：信息收集 / 漏洞扫描 / 漏洞利用 / 一键全流程 / 目标驱动求解
- DeepSec Shield：三层代码审计（L1 启发式 =0.1-rc =4-rc /                ← 你放置插件的目录（无空格路径，如 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 步。

方式二：从源码构建（开发者）
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 =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。

📄 许可与致谢

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