MariNanari / dsh-vulnsec-bridge

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 装配层）：

   # ⚠️ 路径中不要包含空格！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。

📄 许可与致谢

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