dsh-plugin-security-review

简体中文 ｜ English

DSH 插件安全审查门：安装前静态审查（危险代码、漏洞与供应链风险，含反混淆解码）、运行期持续审计与可选运行时守卫，以及设置页一键审查/安装/卸载的可视化面板。

🖥️ 已适配 dsh 桌面客户端（Electron + 内置 0.2.x 运行时，desktop profile）：装进 desktop profile 即可在桌面设置里看到同一个「插件安全审查」分区；安装/卸载走客户端内建插件管理器，install-gate 在打包运行时不可用（只读）。差异详见 桌面客户端适配记录。

📖 完整使用说明：docs/使用说明.md ｜ English: README.en.md ｜ User guide

面向 DeepSeek Harness（dsh）的插件安全审查插件：安装本插件后，再安装任何其他插件前，先对该插件的源代码做静态安全审查，识别危险代码、漏洞与供应链风险，输出安全审查报告并给出安装建议；运行期还会持续审计已安装插件，拦截并禁用危险插件。

平台支持

环境	运行时	状态
web 版 dsh	0.1.x 运行时	✅ 原有行为不变
dsh 桌面客户端	0.2.x（打包在 app.asar）	✅ 已适配（desktop profile）

工作原理（三层防线）

层	时机	能力
1. 安装预审	安装前（dsh-safe-plugin add）	下载源码（不执行任何安装脚本），静态分析后给出结论；block 直接拒绝安装，warn 需人工确认，pass 才转发给 dsh plugin add --ignore-scripts
2. 运行期门禁	dsh 启动后	对 profile 中所有外部插件逐一审查（带缓存）；block 的插件被 loader.update(id,{disabled:true}) 禁用，并把 disabled: true 写入 profile 的 cordis.patch.yml 托管拦截块，下次启动时其代码根本不会被 import；可选运行时守卫拦截危险工具调用
3. 会话内工具	会话进行中	security_review / security_review_status 两个工具，可随时审查任意插件/目录并读取历史报告
3.5 增强分析	审查时	反混淆解码（base64/hex/fromCharCode/\xNN 解码后重扫密钥/命令/URL）+ 词法剥离重扫（消除字符串/注释误报，捕捉动态拼接调用）

安装本插件

# 方式一：经本插件自带的安全安装器（推荐）
dsh-safe-plugin add github:ateen18/dsh-plugin-security-review

# 方式二：官方安装命令（安装后同样立即生效）
dsh plugin --profile web add github:ateen18/dsh-plugin-security-review

安装后，dsh.plugin 会自动把本包加入 dsh.profile.bundles 层栈（本包声明了 dsh.bundle），无需手工改配置。

让 agent 安装（会话内）

不自己敲命令也行，直接在会话里让 agent 装：

帮我把 github:ateen18/dsh-plugin-security-review 装进当前 profile（桌面端装进 desktop）。

agent 走 dsh 的 plugin_manager 工具（install_bundle；桌面端由同一个内建插件管理器执行，等价于「设置 → 插件」里的安装）：

• 该工具默认只在 Creator（Cordis）模式 启用；Standard / PTC / 极简模式下 agent 会改用终端执行 dsh plugin … add（web）或桌面 dsh.cmd … add，效果相同。0.1.x 的 web 版没有这个工具，一律走终端。
• 调用要求会话是完全权限（danger-full-access），或对这一次调用单独批准。
• 如果包带有安装/构建脚本，agent 会先把待批准的包名列给你（pendingBuilds），你同意后它才会带 approvedBuilds 重试。
• 装完通常要重启 dsh（或等 HMR 热加载）才完全生效。

让 agent 装插件等于让它下载并运行第三方代码；装之前建议先跑一遍审查：dsh-safe-plugin review <目标>，或装好本插件后用设置页里的「审查 / 安全安装」。

桌面客户端（dsh desktop）

桌面客户端把运行时打包进 app.asar，profile 固定叫 desktop，安装/卸载应交给内置插件管理器：

# 用桌面自带 CLI（路径按实际安装位置调整）
& "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" `
    plugin --profile desktop add github:ateen18/dsh-plugin-security-review

也可以在桌面「设置 → 插件」里安装。安装后重启客户端（或等 HMR 热加载）。桌面端差异： install-gate 不可用（运行时只读）、安装/卸载走内置 pluginManager、策略在本插件自己的设置分区 编辑。详见 桌面客户端适配记录。

卸载

dsh plugin --profile web remove dsh-plugin-security-review

审查并安装其他插件

# 审查 + 安装（block 直接拒绝；warn 需要交互确认，CI 中用 --yes）
dsh-safe-plugin add dsh-plugin-foo
dsh-safe-plugin add ./local-plugin-dir
dsh-safe-plugin add https://github.com/me/plugin.git

# 只审查不安装（--ignore 可跳过夹具/第三方目录，可重复）
dsh-safe-plugin review dsh-plugin-foo
dsh-safe-plugin review ./local-plugin-dir --json
dsh-safe-plugin review . --ignore test/fixtures --ignore dist

# 查看历史报告 / 复审已安装插件
dsh-safe-plugin list
dsh-safe-plugin verify

报告与结论

• 每份报告：安全评分（0-100）、pass / warn / block / audit 结论、逐条发现（级别、类别、文件:行、代码片段、建议）、安装建议与推荐命令。
• 报告持久化在 $DSH_HOME/security-review/：reports/latest/<包名>.md 为最新 Markdown 报告，reports/history/ 为 JSON 历史，index.json 为索引。
• Web GUI：
  • 设置页左侧栏新增「插件安全审查」模块：展示当前全部已加载插件（官方内置插件灰显、无需审查），每个插件带彩色风险圆点（🟢安全 / 🟡有风险 / 🔴危险）与一句话风险提炼；「一键安全审查」按钮对全部插件执行完整静态审查；非官方插件提供「卸载」按钮（走 pnpm remove，重启后完全生效）。
  • 设置页「security-review」配置区可调审查策略（standard / strict / audit-only）、自动禁用开关、allowlist、installGate。

审查策略（settings → security-review）

字段	默认	说明
policy	standard	standard：critical→block；strict：high 也 block；audit-only：只记录不拦截
autoDisable	false	默认只报告不自动禁用（稳定性优先：防止误伤合法插件或在运行中卸载服务导致 dsh 崩溃）；显式开启后，审计发现 block 才会禁用该插件
autoPatchProfile	false	默认不写 profile cordis.patch.yml 托管块；显式开启后，被拦截插件下次启动不再加载其代码
installGate	false	方案 B 改良版：开启后只在缺失/失效时注入（不反复重写）、原子写入 + node --check 语法自检（失败即回滚）、插件不可用时自清理、另有 dsh-safe-plugin install-gate/uninstall-gate 手动管理。默认关闭，安装预审推荐 dsh-safe-plugin add
runtimeGuard	off	运行时工具调用守卫：off 不启用；log 检测到危险工具调用（破坏性命令/下载执行/SSRF/敏感凭据文件/提示词注入）只记录日志；block 直接拒绝危险调用（fail-open，内部异常一律放行）
allowlist	[]	豁免名单（包名，* 表示全部豁免）

审查规则（节选，见 docs/design.md 与 lib/analyzer/rules.js）

• critical：安装生命周期脚本（preinstall/install/postinstall）、curl|wget 下载后管道执行、child_process 动态拼接/shell:true、eval/new Function 动态执行、远程动态 import、凭据+联网外传、硬编码 API key/Webhook、tarball 完整性校验失败。
• high：任何 child_process 调用、原生二进制（.node/.exe/.dll）、node-gyp 构建、原型污染、混淆特征（atob/fromCharCode/长 base64）、ctx.loader 控制面、包名近似知名包（typosquat）、可疑依赖。
• medium/low：明文 HTTP、包目录外文件写入、rm -rf、挖矿地址、缺 license/仓库/作者、压缩无源码等。

已知限制（诚实声明）

1. 静态分析无法覆盖原生二进制、动态下载的代码与高度混淆的载荷；block 结论是「存在强风险信号」，不是「证明恶意」。
2. 运行期门禁在本插件自身 apply 之后的插件 import 才有确定性拦截能力；同批次更早启动的插件在首次启动的毫秒级窗口内会先加载，随后被启动审计禁用，并被托管块保证下次启动不再加载。要获得确定性的安装前拦截，请使用 dsh-safe-plugin add。
3. 若某个被拦截插件是其他插件 inject 的服务提供方，禁用后启动会因缺服务而失败（这是 dsh 的 fail-loud 契约），报告会指出缺哪个服务。
4. 传递依赖（插件声明的第三方依赖）不在逐文件扫描范围内，只做名称层面的可疑检测；供应链深水区建议配合 lockfile 审计与 registry 信誉。
5. 本插件自身把「审查器运行失败」降级为 warn（fail-open），避免审查器自身故障瘫痪整个 dsh；可用 dsh-safe-plugin verify 手动复查。

目录结构

lib/
  index.js            宿主插件（审计、设置区、agent 工具、webServer API 注册、watcher）
  api.js              HTTP API（list/run/review/install/uninstall/settings/capabilities/gate，loopback 防护）
  client.js           浏览器端设置页模块（ModuleLoader bundle，策略面板 + 环境提示）
  desktop.js          桌面客户端探测（Electron/asar/profileContext、install-gate 能力判定）
  package-ops.js      profile 包操作（pluginManager → desktop CLI → pnpm）
  gate.js             运行期 import 门禁（EntryTree.prototype.import 补丁 + 作用域判定）
  host.js             dsh 宿主包解析（含 @deepseek-ai/dsh-desktop-runtime 打包布局）
  install-gate.js     原生 dsh plugin add 预审钩子（桌面端不可用）
  watcher.js          profile package.json 变更监听（pnpm 直装兜底）
  store.js            报告/缓存持久化（$DSH_HOME/security-review）
  patch-manager.js    profile cordis.patch.yml 托管拦截块
  settings.js         策略 schema、持久化与设置接线
  tools.js            security_review / security_review_status 工具
  runtime-guard.js    运行时工具调用守卫
  cli/index.js        dsh-safe-plugin CLI（安装预审主入口）
  analyzer/           纯静态分析器（零依赖，CLI 与宿主共用）
    rules.js          规则引擎（20 组规则）
    score.js          评分、结论与策略
    tar.js            tar.gz 解包（防路径穿越/zip bomb）
    registry.js       registry 元数据/版本选择/tarball 完整性校验
    semver.js         极简 semver
    known.js          知名包名清单（typosquat 比对）
    render.js         Markdown 报告渲染
    decode.js         反混淆解码与词法剥离重扫
docs/                 设计文档、使用说明、桌面端适配记录与修复/优化记录
test/                 node --test 单元测试与恶意/良性夹具

从本地源码安装（开发/内网场景）

# 先把本仓库链接进 profile（link: 方式，改动即时生效）
dsh plugin --profile web add link:<你的插件源码目录>

# CLI 的两种调用方式（任选其一）：
# 1) 用 profile 内生成的 bin（pnpm 会自动为带 bin 的依赖建 shim）
"$env:USERPROFILE\.dsh\profiles\web\node_modules\.bin\dsh-safe-plugin.cmd" --help
# 2) 直接以 node 运行
node "<你的插件源码目录>/lib/cli/index.js" review ./某个插件目录

# 运行单元测试（不需要 dsh 环境，零依赖；注意不要在 test 后加反斜杠）
cd <你的插件源码目录>
npm test

# 对本插件自身做一次自审（排除刻意构造的恶意测试夹具后应为 warn 而非 block）
node lib/cli/index.js review . --ignore test/fixtures

License: MIT