执行前托管审批 Floralee2024/dsh-escrow

dsh-escrow

针对不可逆 agent 操作的执行前托管与故障关闭式人工审批。

dsh-escrow 是 DeepSeek Harness 的一个插件。它在执行前对工具调用进行分类，将高风险操作放入托管窗口，并且只有在明确决策之后才会放行。沉默、超时、适配器故障以及未知结果都不会放行操作。

当前版本：v0.3.26。 本仓库是一个系统/工件原型。其测试记录了已实现的不变量和已演练的行为；它们并不证明普遍安全性、生产规模有效性或对每一种攻击者的安全性。

它提供什么

- 针对 shell 和受信任的非 shell 效果的确定性执行前分类。
- green / yellow / red 路由，内置覆盖破坏性、特权、外部副作用、共享资源和治理类操作。
- 针对 host 或本地 adapter 模式的同步人工审批；针对默认 queue 模式的异步排队与 escrow_result。
- 一次性重放令牌、同签名去重、迟到调用保护，以及故障关闭式 red 路径处理。
- 结构化审批详情：操作、目标、远程、分支/引用、URL、数据库/schema、资源、权限范围、工具、风险类别和学习策略。
- 一个无依赖的本地审批适配器，可在 127.0.0.1 上渲染浏览器卡片。
- 仅追加的脱敏账本记录，带哈希链和 HMAC 完整性校验，以及迁移、重放、报告和诊断命令。
- 对关键操作（如强制推送、递归删除、磁盘/系统操作、外部发布、权限提升、共享资源删除和 dsh 治理变更）进行显式的永不学习处理。

为什么需要托管？

权限预设和事后回滚回答的是“可以尝试什么”或“损害如何修复”。托管在副作用发生之前增加了一个决策点。red 操作不会仅仅因为被排队就被视为成功，缺失的人工决策也不会被解释为同意。

从 GitHub 安装

前置条件：Node.js 18+ 以及已安装的 DeepSeek Harness profile。

git clone https://github.com/Floralee2024/dsh-escrow.git
cd dsh-escrow
dsh plugin --profile web add .

安装或更改插件后，请重启 dsh profile。如果你在 Windows 上从其他目录安装，请将该目录作为插件路径传入，而不是示例中的 .。

快速开始：本地审批适配器

该适配器是一个 MVP 替代审批界面。它绑定到回环地址，将待处理请求保存在内存中，支持宿主协议当前使用的两种稳定的一次性结果（allowed-once 和 rejected），并且当新请求到达且当前没有可见的审批页面时，会自动打开本地审批页面。

从仓库根目录启动它：

node approval-adapter/bin/dsh-escrow-approval-adapter.mjs --port 3099
适配器会尝试自动打开带令牌的本地 URL。如果环境是无头的，或者启动器不可用，请手动打开打印出的本地 URL。不要将适配器暴露在局域网或公共接口上。

在不提交令牌的情况下配置 dsh 配置文件：

- id: escrow
config:
approvalMode: adapter
approvalAdapterUrl: http://127.0.0.1:3099
approvalAdapterTimeoutSec: 300
mode: sync
ttlSec: 300
timeoutPolicy: cancel
defaultAction: yellow
builtinRules: true

在进程环境中设置令牌，或将其放入私有的配置文件覆盖层：

$env:DSH_ESCROW_APPROVAL_TOKEN = ''

端到端流程如下：

3081 Web session
-> dsh tool call
-> dsh-escrow tools/pre-execute
-> POST 127.0.0.1:3099/v1/approvals
-> structured approval card
-> human clicks “允许一次” or “拒绝” -> the original tool call is released or denied -> result returns to the 3081 session

适配器 UI 有意只暴露 MVP 按钮。approve-now 和显式手动白名单决策仍可通过 /escrow 命令界面使用；更丰富的适配器按钮需要兼容的主机协议扩展。

审批卡片与策略

卡片包含工具、风险类别、原因、审批 ID，以及可用时的结构化操作字段。它还会说明适用的学习策略。

- 正常的可学习红色操作：在两次批准后，默认策略会等待 24 小时冷却期，然后才自动允许。协议负载中提供了配置为立即允许的学习选项，但不会作为适配器 MVP 按钮呈现。
- 对同一签名的两次拒绝决策会激活已学习的拒绝路径。
- never-learn 操作永远不会变为自动允许，无论批准次数如何。它们只能通过显式的 /escrow allow 操作添加，相关风险由管理员承担。
- critical-red 保留用于强制推送、生产/共享资源删除、正式包发布、权限提升、安全策略变更以及 dsh 治理变更等操作。这些操作每次都需要显式决策。
- 分类基于操作表示，而不是基于诸如 -WhatIf 之类的声明；试运行命令仍可能需要审查。

命令界面

/escrow pending
/escrow approve
/escrow approve-now
/escrow approve-and-allow
/escrow deny
/escrow allowlist
/escrow allow
/escrow deny
/escrow forget
/escrow approve all
/escrow deny all
/escrow export [path]
/escrow import
/escrow reduce [--since 7d]
/escrow migrate
/escrow doctor
/escrow stats

queue 模式是异步的，会在操作仍处于待处理状态时返回一个合成的前台结果。host 和 adapter 模式是同步的，会等待决策。任何不可用的审批路径或超时，在 timeoutPolicy: cancel 下都会按失败关闭处理。
配置

主配置通过 profile 的 cordis.patch.yml 应用：

- id: escrow
config:
ttlSec: 300
timeoutPolicy: cancel # cancel | release | hold
defaultAction: yellow # green | yellow | red
builtinRules: true
mode: async # async | sync
approvalMode: queue # queue | host | adapter
approvalAdapterUrl: http://127.0.0.1:3099
approvalAdapterToken: '' # prefer DSH_ESCROW_APPROVAL_TOKEN
approvalAdapterTimeoutSec: 300
learnWhitelist: true
learnThreshold: 2
autoBlacklist: true
cooldownHours: 24
approvalChoices:
immediateAllow: true
manualWhitelist: true
selfModification:
red: true
trustedToolEffects:
- tool: email.send
effects: [external-write]
- tool: browser.publish
effects: [external-write, shared-resource-write]

用户规则是确定性的，且采用首个匹配优先。用户的 green 规则无法抑制内部 red 规则。非 shell 工具必须从宿主或管理员处获得可信效果；工具参数和 MCP 注解不能自行声明某个操作是安全的。

账本与完整性

决策在经秘密信息脱敏后写入 $DSH_HOME/.dsh-escrow/ledger.jsonl。账本记录观察结果、排队操作、决策、等待时间、工具身份和会话身份。大小限制会将活动文件轮转为 ledger.jsonl.bak。

每个当前格式的行都带有 SHA-256 链值和 HMAC。/escrow doctor 会报告完整性、密钥不匹配、遗留行、模式问题以及分类器性能。必须先迁移遗留行，账本才能提供完整的当前完整性保证。

该完整性设计可防范意外或未被察觉的篡改，以及可重写链但不持有 HMAC 密钥的攻击者。它无法防范可同时修改账本及其密钥的攻击者，也无法确立周围运行时是可信的。

测试与复现

从仓库根目录运行：

npm test
npm run test:taste
npm run test:integration
npm run test:host
npm run test:side-effects
npm run test:all

当前完整测试套件涵盖 107 项冒烟断言、43 项 taste 状态断言、76 项插件集成断言、可见宿主接缝、外部副作用分类、适配器集成以及适配器服务器行为。测试套件是这些用例的可执行证据，而非普适的安全证明。

论文产物位于 paper/：

- paper/manuscript.md — 系统/产物论文草稿；
- paper/experiment-card.json — 主张边界与证伪条件；
- paper/reproduce.ps1 — 可复现性入口点。

已知限制

- 本地适配器是内存中的 MVP。安全地重启它会丢失待处理请求，并导致等待中的调用以失败关闭方式结束。
- 适配器仅限回环，没有多用户身份、持久化存储、TLS 或远程通知服务。
- 当前适配器卡片仅支持 allowed-once 和 rejected；更丰富的学习选项仍基于命令。
- 分类器是确定性的，但并不完备。未在配置规则中表示的工具或效果可能会被错误分类。
- 本仓库不声称能证明安全性、消除提示注入，或替代针对具体部署的威胁建模与运维审查。

相关材料

- approval-adapter/README.md
- 设计-v0.2.md
- 红灯细分规则-v0.4.md
- third-party-review/
- paper/

许可证

MIT。参见 LICENSE。