dsh-plugin-security-review AGENTS.md

AGENTS.md — dsh-plugin-security-review

DSH 插件安装安全审查守卫：对 cordis_define / cordis_run 安装或运行的动态插件源码做静态安全审查，按安全优先策略拦截；同时提供 plugin_security_review / plugin_security_audit 两个审查工具。

仓库形态

本项目包含两种可安装形态，静态 bundle 是推荐形态（v1.5.0 起）：

路径	形态	说明
package.json + cordis.patch.yml + lib/	静态 bundle（推荐）	dsh plugin add 安装后随 profile 层栈自动加载，开机自启动，跨 DSH 进程存续
manifest.json + package-source.js	动态插件回退形态（v1.4.0）	仅用于无 bundle 能力的 profile，需在每次重启后重新 cordis_define / cordis_run
tests/gate.test.mjs	动态形态行为测试	node tests/gate.test.mjs
tests/static.test.mjs	静态形态行为测试	node tests/static.test.mjs

常用命令

# 安装（静态 bundle，推荐）
dsh plugin --profile web add dsh-plugin-security-review
dsh plugin --profile web add file:/path/to/dsh-plugin-security-review   # 本地未发布时（路径不能含空格）

# 测试（两种形态各自的行为测试，无需构建）
node tests/gate.test.mjs
node tests/static.test.mjs

# 升级守卫（静态）
dsh plugin --profile web update dsh-plugin-security-review

本项目无构建步骤：lib/index.js 是直接可运行的 ESM 源码。

代码结构

• lib/index.js — 守卫全部实现（约 1070 行，单文件）。命名导出 name / inject / apply（Cordis 静态插件约定）：经 ctx.tools.register(defineTool(...)) 注册工具，经 ctx.on('tools/pre-execute') 拦截安装；v1.7.0 起经 ctx.inject(['webServer'], cb) 挂审批弹窗路由，并携带 client/client.js Client 半端（dsh.client 声明 + exports["./client"]）。
• lib/index.d.ts — 类型声明。
• client/client.js — 浏览器审批弹窗（拒绝 / 同意+白名单 / 同意），__ModuleLoader__ bundle 格式（照 dshmarket），无构建步骤；经 shell.overlay 浮层渲染。重试消息经 connection.api.sessions.prompt 注入到来源会话（entry.agentId，守卫拦截时从 exec.agent 记录），不依赖全局 session/subscribed 帧。
• cordis.patch.yml — bundle patch，把插件以 id: plugin-security-gate 插入 profile 层栈。
• package-source.js — 动态形态的 host 源码（与 lib/index.js 功能同源，含 LINEAGE_TOKEN 谱系令牌）。
• manifest.json — 动态形态的插件元数据（plugin/name/purpose/tools/notes）。
• tests/ — 两种形态的行为测试，直接 node 运行，无测试框架依赖。

核心规则（修改时必须保持的约定）

• 判定策略（安全优先，fail-closed）：BLOCK = critical>0 或 high≥2 或 总分≥100；ASK = high≥1 或 总分≥40；WARN = 总分≥10；其余 ALLOW。审批禁用时 seam 模式 ASK 等效拒绝。
• 审批弹窗 askMode（静态 bundle，v1.8.0）：ASK 判定默认 popup——挂起审批（记录来源会话 id agentId + 白名单类型 whitelistType）+ deny + 浏览器「拒绝/同意+白名单/同意」弹窗。approve（同意）只写 approved 指纹；approveTrusted（同意+白名单）另把插件族写入 trusted-local（new→prefixes，existing/run→pluginIds），同族安装/开发不再重复弹窗；白名单写入 best-effort，失败不影响指纹批准，读取侧 fail-closed 不变。同意/同意+白名单后由守卫注入到来源会话让 agent 自动重试（修复多会话下投错会话 Bug）。config.json 设 {"askMode":"seam"} 回退官方审批 seam。BLOCK 一律硬拒绝不经弹窗；弹窗仅静态 bundle 提供，动态回退形态 ASK 仍走 seam。禁止把弹窗/同意逻辑接到 BLOCK 或自动放行。
• 风险权重：critical=100, high=40, medium=15, low=4，总分上限 300；CAPABILITIES: 声明项计分减半（最低 1 分）。
• 拦截点：cordis_define / cordis_run 的 tools/pre-execute 事件；源码不可检索时一律 fail-closed（ask）。
• 静态形态无自升级豁免：所有动态插件一律审查，不允许存在任何前缀/谱系令牌绕过。
• 操作者白名单 trusted-local：<DSH_HOME>/storages/plugin-security-gate/trusted-local.json（prefixes/pluginIds/fingerprints）命中即直接放行并留审计痕迹；信任锚=有文件权限的操作者，非 agent 自我声明；文件不存在/损坏 = 无白名单（fail-closed 方向不变）；cordis_stop/cordis_undefine 自我保护不受白名单影响。禁止把"调用者是本会话 agent"作为自动放行条件。
• 跨会话批准持久化：人工批准的 ASK 代码指纹（host+client sha256）写入 <DSH_HOME>/storages/plugin-security-gate/state.json，命中指纹自动放行。
• 自我保护边界：静态 bundle 无法经 cordis_stop / cordis_undefine 停用，只能由有文件权限的操作者 dsh plugin remove 卸载。
• 已知限制：组合判定是静态 presence 判定（可能误报/漏报）；深度混淆有盲区；本守卫不是对抗恶意 actor 的安全边界。