@guojin-ai/dsh-plugin-guard

Readme

# dsh-plugin-guard

> DeepSeek Harness 插件安全体检：对已安装的第三方插件做「静态代码审计 + 依赖审查 + AI 在线审计」，并以绿 / 黄 / 红三级报告面板呈现。
>
> Plugin security inspector for the DeepSeek Harness web GUI: statically audits installed plugins (dangerous API patterns + dependency review), then layers an AI (default-model) audit on top, rendered as a green / yellow / red report panel.

中文 | [English](README.en.md)

## 这是什么

`dsh-plugin-guard` 是 DeepSeek Harness（DSH）Web GUI 的一款**插件安全体检**插件。它在**不执行插件代码**的前提下，读取已安装第三方插件的源码与元数据，帮你判断「装上的这个插件到底在做什么、是否超出了它自称的功能范围、风险有多高」，最后给出一份绿 / 黄 / 红三级的报告。

## 主要功能

- **静态扫描**：逐文件检查第三方插件源码，识别 15 类危险能力（子进程、`eval`、`vm`、shell、文件读写、网络、环境变量、系统探测、混淆、可疑外联地址、高熵载荷、凭据外传迹象等），并按严重度打分。
- **依赖审查**：标出「非 npm registry 来源」（`git:` / `file:` / `link:` / URL）以及「包名命中可疑关键词」的依赖。
- **安装脚本审查**：单独标出 `preinstall` / `install` / `postinstall` 脚本——这是常见的供应链攻击面；安装脚本里若出现「下载即执行」（curl/wget 管道给 shell）会被单独再标一次。
- **密钥 / 下载执行扫描**：新增两条高危静态规则——「疑似硬编码密钥 / 令牌」（AWS / GitHub / Slack / Stripe / OpenAI / PRIVATE KEY 等已知格式，加通用的长引号 key 赋值）与「下载即执行」（`curl`/`wget`/`iwr` 管道给 `sh`/`bash`/`iex`），源码与安装脚本都查。
- **声明权限评分**：读取插件声明要注入的宿主服务（`dsh.plugin.json` 的 `entry.inject` 与 `package.json` 的 `dsh.client.inject`），按能力面分级——模型 / 网络 / 文件 / 进程 / 密钥 / 浏览器类为高危，UI / 国际化 / 配置类为低危，未知服务一律按中危「需人工复核」——给出 0–100 的权限分并在面板逐条列出。
- **能力与声明面不匹配告警**：当代码命中高危能力、但声明的宿主服务全是轻量级时，面板标红提示「高危能力与声明面不匹配」——这是最强的越权信号，确定性计算，不再交给模型去猜。
- **版本变更告警（持续监控）**：每次扫描保存一份基线（`$DSH_HOME/storages/dsh-plugin-guard/baseline.json`），下次扫描自动比对——面板对「新安装 / 版本变化 / 相比上次新增了风险能力或声明权限」的插件打标。把一次性快照升级成变更探测器：可信包某个新版本被投毒（最常见的供应链攻击手法）会直接显示「⚠ 自上次扫描有变更：+install-script」。
- **AI 在线审计**：调用默认模型，结合「插件自称的功能 + 静态代码证据 + 多层互联网声誉」二次判定，输出 `safe / suspicious / malicious / inconclusive` 结论及处置建议。**判定结论**按「内容指纹（含默认模型）+ 版本 + TTL」缓存，而**声誉证据（npm / OSV / 网络举报 / GitHub）每次实时拉新**——源码 / 清单 / README 一个字节未变、未超 TTL（默认 3 天）、且新声誉里没有新的负面信号（新漏洞 / 恶意记录、新的恶意举报、新增弃用标记）时，才复用上次判定（面板标注「来自缓存」），任一变化都强制重审。
- **统一风险分级与打分（AI 复审后重新定级）**：静态「风险分 = 代码旗分 + 声明权限分」（上限 100），静态等级为**红**（命中高危规则或旗分 ≥ 40）/ **黄**（风险分 ≥ 15）/ **绿**；AI 审计结束后按判定**重新分级**——`malicious`→红、`suspicious`→黄（静态已红则保持红）、`inconclusive`→不低于静态（静态绿则升黄）、`safe`→绿——且 **风险分改由 AI 给出 0–100**（safe 通常 < 30 / suspicious 约 40–70 / malicious ≥ 70）。AI 与静态不一致时徽章旁显式标注「AI … · 静态 …」，绝不静默降级；刷新页面后仍在有效期内的结论与打分会自动还原。
- **声誉佐证**（多层联网核实，均尽力而为、失败自动降级，绝不阻断审计）：
  - **npm registry 元数据**：描述、维护者、发布 / 更新时间、周下载量、**包龄**（新包 < 30 天会标红——恶意包常"发布→得手→数日内被下架"）与 **deprecated 弃用标记**（来自维护者的权威"不可信"信号）；
  - **OSV.dev 权威记录**：查询该包是否被官方漏洞 / 恶意包数据库收录，`MAL-*` 或 “Malicious” 条目会高亮为「恶意」，是判定恶意的强信号；
  - **互联网恶意/攻击报告检索**：以 Bing 为主、DuckDuckGo 兜底，中英双语检索「该插件是否被举报为恶意 / 后门 / 供应链攻击」。命中经过**相关性过滤**——只有确实提到该插件名、且涉及恶意/攻击的条目才会展示；若没有相关报告，直接显示「未检索到与该插件相关的恶意/攻击报告」，**不会**列出无关内容或链接；
  - **GitHub 仓库信号**：star / fork / 是否归档 / 作者账号年龄 / 公开仓库数 / **开源许可（SPDX）** / **开放 issue 数** / **有无 SECURITY.md**，并据 `pushed_at` 判断**是否已弃坑（超 1 年无提交标红）**。仓库地址**优先取自插件自述**（package.json 的 `repository` / `homepage`、README 文档）；只有插件完全没声明时，才按包名从 npm 推断，并明确标注「可能是同名仓库，请人工核对」。
  - **依赖漏洞扫描（OSV.dev 批量）**：每次审计会解析插件**直接运行依赖**（从自身 `node_modules` 读到精确安装版本，pnpm 符号链接照追、并与声明的 `dependencies` / `optionalDependencies` / `peerDependencies` 交叉过滤），单次批量查询 OSV.dev `/v1/querybatch` 是否有已知 CVE / 恶意记录；命中依赖会在声誉面板列出，且**新出现的依赖漏洞信号同样会使缓存判定失效**。全程无 key、尽力而为、不阻断审计。
- **GitHub Token**：可在面板中填写 Personal Access Token，把 GitHub API 限额从 60 次/小时提升到 5000 次/小时。
- **技能审计（SafeSkill）**：对接微步在线 SafeSkill 平台，在面板中填写 API Key 后可对该 profile 已安装的 DSH Skills 一键上传扫描（客户端自动 zip 打包，零新依赖）并拉取多引擎（LLM / 静态 / 动态 / 子文件 / 外链）判定报告，含威胁等级、信任分、威胁分类与详细风险指标；结果内联展示并附报告原文链接。
- **浅色 / 暗色主题适配**：报告面板自动检测应用的浅色 / 暗色主题并跟随切换，所有文字、徽章、控件在两套主题下均可读，无需刷新页面。

## 安装与启用

### 前提

- 一台已安装 DSH、能正常 `dsh web` 的机器。
- 机器上装有 `pnpm`（`dsh plugin` 内部需要它来安装插件）。

### 安装

```bash
dsh plugin --profile <name> add @guojin-ai/dsh-plugin-guard
```

把 `<name>` 换成你要审计的 profile（默认可填 `web`）。安装完成后，**重启 dsh**（重新运行 `dsh web`）。

### 打开面板

启动后打开 Web GUI 的 **设置 → 插件安全体检**，即可看到安全报告。

> 卸载：`dsh plugin --profile <name> remove @guojin-ai/dsh-plugin-guard`
>
> 说明：DSH 内部识别此插件的 id 是 `dsh-plugin-guard`（与 npm 包名 `@guojin-ai/dsh-plugin-guard` 不同，属正常现象）。

## 使用指南

### 报告总览

面板顶部给出汇总统计「N 正常 · N 警告 · N 高危」，并有一个「重新扫描」按钮，可随时刷新当前安装状态。

### 看懂单个插件

每个第三方插件一行，展示：

- **风险等级徽章**（绿 / 黄 / 红）；
- 插件名与版本、是否启用；
- **风险分**（AI 审计后改由 AI 给出 0–100，未审计时为静态分）、命中规则、**声明权限**、依赖、扫描文件数。

展开某一行可以看到：**自上次扫描的变更**（若有：版本变化、新增风险能力 / 声明权限）、所有命中的风险规则及对应文件、**声明的宿主服务权限**（含不匹配告警）、可疑依赖、以及扫描过程中出现的错误。

### AI 在线审计

每个插件行内都有一个「AI 审计」按钮。点击后：

1. 实时显示进度（采集证据 → 声誉查询 → 调用模型 → 解析结果）；
2. 输出判定结论（safe / suspicious / malicious / inconclusive）、关注点、处置建议与声誉佐证。

审计结果会保留：关闭设置面板再打开，已完成的（或仍在进行中的）结果仍然可见；**刷新页面后，仍在有效期内的结论与 AI 打分也会从本地缓存自动还原**。

**结果缓存**：审计**判定结论**写入本地缓存（内容指纹（含默认模型）+ 版本 + TTL，默认 72 小时 = 3 天）；**声誉证据（npm / OSV / 网络举报 / GitHub）每次都会实时拉新**。仅当源码、清单、README 均未变化、未超 TTL，且新拉取的声誉里**没有出现新的负面信号**（新漏洞 / 恶意记录、新的恶意举报、新增弃用标记）时，才复用上次结论并标注「来自缓存」——一旦出现新负面信号就自动作废缓存、强制重审。面板中提供「AI 缓存 TTL」设置框，可改小时数，设为 0 即关闭缓存、每次都强制重审。每个插件旁的「强制重审」按钮可单独绕过该插件的缓存重审一次，无需改全局 TTL。

### GitHub Token（可选）

面板顶部提供 Token 填写区（密码框，不回显）：

- **保存 / 清除**：填写后保存，状态显示「已配置 / 未配置」；
- 填写 Token 后，AI 审计的 GitHub 查询限额从 60 次/小时提升到 5000 次/小时；
- Token 只保存在本机（`$DSH_HOME/storages/dsh-plugin-guard/github-token.txt`），不进会话、不上传。

### SafeSkill 技能审计（可选）

本插件集成了**微步在线 SafeSkill 平台**（https://safeskill.cn），可对当前 profile 中已安装的 DSH Skills 做在线多引擎安全扫描。

- **配置 API Key**：在面板顶部的「SafeSkill API Key」输入框中填写你在 SafeSkill 平台申请的 API Key（密码框，不回显），点击保存。Key 只保存在本机（`$DSH_HOME/storages/dsh-plugin-guard/safeskill-key.txt`，权限 0600），不进会话、不上传。
- **扫描技能**：点击「扫描全部技能」或单个技能旁的扫描按钮，插件会读取该技能目录（`$DSH_HOME/skills/<name>/SKILL.md` 及其附带的支持文件），在客户端完成 CRC32 校验 + 标准 zip 打包（零额外依赖），上传至 SafeSkill 平台，然后轮询拉取报告（最长 5 分钟）。
- **查看结果**：扫描完成后，面板展示威胁等级（恶意 / 可疑 / 未知 / 安全）、信任分（0–100）、威胁分类以及各引擎（LLM / 静态 / 动态 / 子文件 / 外链）的判定概要；点击链接可跳转 SafeSkill 报告原文。
- **注意**：SafeSkill 是独立的外部平台，扫描结果由微步在线提供；本插件仅负责打包上传与结果回显，不做任何本地判定。未配置 API Key 时该区域不发起任何请求。

## 它会检查什么

### 静态风险规则

| 规则代码 | 严重度 | 命中内容 |
| --- | --- | --- |
| `child-process` | 高 | `child_process` 的 exec / spawn / fork 等 |
| `eval` | 高 | `eval(...)` / `new Function(...)` |
| `vm-module` | 高 | 引用 `vm` 模块（沙箱逃逸面） |
| `shell` | 高 | `shell: true` 或命令行拼接（rm -rf / curl / sh -c 等） |
| `fs-write` | 中 | 文件写入 / 删除 |
| `fs-read` | 中 | 文件读取 |
| `network` | 中 | net / dgram / dns / tls / ws / undici 等 |
| `exfil-url` | 中 | pastebin / webhook.site / ngrok / tg bot / onion 等外联地址 |
| `env-exfil` | 中 | 同一文件读取 `process.env.*` 又有子进程 / 网络外联（疑似凭据外传） |
| `high-entropy` | 中 | 长的高熵字符串（疑似 base64 / 加密载荷，与解码方式无关） |
| `http` | 低 | fetch / axios / request 等 HTTP 请求 |
| `env` | 低 | 读取 `process.env.*` |
| `system-info` | 低 | 主机名 / 用户 / CPU / 网卡等系统探测 |
| `obfuscation` | 低 | `atob` / base64 编码等混淆迹象 |
| `install-script` | 高 | package.json 声明安装脚本 |

### 依赖审查

- **非 npm registry 来源**：`git+ / git: / github: / http(s) / file: / link: / 相对路径` 的依赖会被标出；
- **可疑包名**：命中 `miner / stealer / keylogger / ransomware / trojan / backdoor / infostealer / credential-steal / exfil` 等关键词的依赖会被标记。
- **已知漏洞依赖（OSV.dev）**：AI 审计会解析直接依赖的精确版本并批量查询 OSV.dev，命中的依赖在声誉面板中列出（详见上文「声誉佐证」）。

### 声明权限评分

插件通过 `dsh.plugin.json` 的 `entry.inject` 和 `package.json` 的 `dsh.client.inject` 声明它需要宿主注入哪些服务。本插件把这些声明视作「权限面」来评分：

| 档位 | 说明 | 典型服务 |
| --- | --- | --- |
| 高危 | 可触达模型 / 网络 / 文件 / 进程 / 密钥 / 浏览器 | `llm`、`typert`、`remote`、`api`、`agentDefaultModel` 等 |
| 中危 | 未识别的服务，默认按「需人工复核」 | 任何不在上表的服务名 |
| 低危 | 仅 UI / 国际化 / 配置 / 数据流 | `locale`、`slots`、`ui-settings`、`renderer` 等 |

- **权限分**：高危 40 / 中危 18 / 低危 6，与静态风险分同一套权重；**已计入整体风险分**（代码旗分 + 权限分，上限 100），因此只声明高温权限、代码无旗的插件也会被推成「警告」——「红」仍只由**代码旗**产生（高危规则或旗分 ≥ 40），单靠声明 `llm` 之类的权限不会误判成红。
- **能力与声明面不匹配**：代码命中任一高危能力、且声明的宿主服务**全部为低危**时触发（未声明任何服务时不触发，避免误报）。这是最强的越权嫌疑信号，会同时喂给 AI 审计。

### 扫描边界

为提高准确度与性能，扫描会跳过 `node_modules`、`.git`、`.pnpm`，跳过 `.map` / `.d.ts` / `.min.js`，超过 1 MiB 的单个文件与过深目录也会跳过。

## 判定标准

- **静态计分**：高危 40 / 中危 18 / 低危 6；**风险分 = 代码旗分 + 声明权限分**，上限 100。
- **静态风险等级（AI 未审时）**：
  - 命中任一**高危**规则、或代码旗分 ≥ 40（例：3 个中危）→ **红**；
  - 风险分 ≥ 15 → **黄**；
  - 其余 → **绿**。
- **AI 复审后重新分级 + 打分**：
  - 判定驱动分级：`malicious` → 红；`suspicious` → 黄（静态已红则保持红）；`inconclusive` → 不低于静态（静态绿则升黄）；`safe` → 绿。
  - **风险分（0–100）改由 AI 给出**：safe 通常 < 30、suspicious 约 40–70、malicious ≥ 70；模型漏给时按判定回填（malicious 90 / suspicious 65 / inconclusive 50 / safe 10）。
  - AI 与静态结论不一致时，徽章旁显式标注「AI … · 静态 …」，绝不静默降级（确定性红旗仍在列表可见）。

AI 审计的判定口径：**危险能力本身不等于恶意**。它更看重「这个插件自称的功能」与「它实际做的」是否一致——文件管理器读写文件、代码执行器跑命令是本职；但计算器偷读 SSH 密钥、无名新包外联回传，才是真正的恶意信号。

## 常见问题

**问：有些插件的 npm 声誉栏显示「npm 未收录该包名」，是出问题了吗？**

不是。本地 `link:` / `file:` / GitHub 直连安装、或未发布到 npm 的包，npm 侧本来就没有记录，这是**预期行为**。AI 审计会以「声誉信息缺失时不臆造」的原则处理。

**问：绿色就一定安全、红色就一定是恶意吗？**

不是。这是**事后检测** + 静态分析的组合，会有误报和漏报。请结合 AI 结论与人工复核后再做决定。

**问：SafeSkill 扫描和 AI 审计有什么区别？**

SafeSkill 是微步在线的外部多引擎扫描平台，提供独立第三方判定——偏重「这个技能文件是否已知恶意 / 可疑」。AI 审计是本插件调用 DSH 默认模型的内部审计，偏重「插件代码 + 安装链 + 声誉」的综合判断。两者互不依赖、可同时使用。

## 局限与免责

- 这是**事后检测**：它读取源码与清单，无法拦截加载器在 `import()` 时已经执行的代码。
- 静态正则匹配存在误报 / 漏报：命中不代表恶意，未命中也不代表安全。
- 声誉与 AI 结论只是**佐证与参考**，最终是否信任某个插件仍需人工判断。

## 许可证

[MIT](./LICENSE)