隐私脱敏盾 MARYCOMPLEX/dsh-privacy-shield

dsh-privacy-shield

为 DeepSeek Harness 提供可开关的隐私脱敏，走官方扩展点。

敏感值会在变成模型可见的消息和工具结果之前替换成 vault token。模型看到的是 {{PHONE_ab12cd}}；本地 vault 保留真实值；secure_run / secure_write / secure_read / secure_edit / secure_request 在工具内部还原真实值，再把输出重新脱敏。

重要的日志注意事项： DSH 会在 agent/pre-step 运行之前，把原始用户输入写入 agent/inbox/spliced 审计事件。user/message 事件和模型请求都已脱敏，但更早的那条 inbox 事件仍包含原始文本。如果这一点对你重要，不要导出或分享原始会话文件。见已知缺口。

插件只使用 DSH 有文档的扩展点，这是刻意为之：

| 扩展点 | 这里做什么 |
| agent/pre-step | 在 user/message 追加之前，对已接纳的用户消息脱敏。 |
| tools/post-execute | 对工具结果脱敏（规范 value 和渲染后的 content），赶在写入日志、暴露给模型之前。 |
| tools/pre-execute | 拒绝收到 vault token 的普通工具；模型必须改用 secure_ 工具。 |
| session-telemetry/record | 对发往外部的遥测副本做单向脱敏。 |

它不包装 llm/stream，不重新派发请求，也不需要代理或 fork。这样能保住 DSH 的「模型可见 ⇔ 已记录」不变量：日志和模型看到同一份脱敏文本。

状态： MVP，33 个单元测试，适配 DSH 0.2.x 扩展点。尚未发布到 npm。

为什么走官方扩展点，而不是 llm/stream？

DSH 从只追加的会话日志构建每个请求，并对其深度冻结。llm/stream 监听器收到的是冻结后的请求，以及一个转发原始请求的 next()；它无法替换请求。社区的做法（dsh-llmasking）是通过瀑布流重新派发一份脱敏副本，这能跑通，但绕过了已准备好的调用，会重新进入每个监听器，还依赖私有的派发行为。

本插件走另一条官方路线：更早脱敏，赶在事件提交之前。代价是日志和 UI 也显示 token；好处是模型和日志保持一致，且不涉及任何私有 API。将来可以做只面向模型的投影（SessionMessageProjection），在不改变这套安全模型的前提下还原原始对话视图。

安装

从本仓库安装

git clone https://github.com/MARYCOMPLEX/dsh-privacy-shield.git
cd dsh-privacy-shield
npm install
npm run build
dsh plugin --profile my add link:$PWD
dsh --profile my

包的 dsh.bundle.patch 会自动加上 privacy-shield 这一行。新建的配置档会拿到下面的默认值。

从 npm 安装（发布后）

dsh plugin --profile my add dsh-privacy-shield

最小配置档补丁

- insert:
- id: privacy-shield
name: dsh-privacy-shield
config:
enabled: trueyaml
mode: vault
vault:
backend: file

用户级 cordis.patch.yml 可以替换整行配置： yaml
- id: privacy-shield
name: dsh-privacy-shield
config:
enabled: true
mode: vault
maskUserMessages: true
maskToolResults: true
failMode: closed
rules:
secrets: true
phone: true
email: true
idcard: true
bankcard: false
ipPrivate: false
jwt: true
privateKey: true
allowlist: ["example.com"]
vault:
backend: file
path: ""
encryption: aes-256-gcm
secureTools:
enabled: true
allowedHosts: ["api.example.com", ".internal.example.com"]
run:
allowedCommands: ["printf", "git"]
denyNetwork: true
blockedPatterns: ["\\brm\\s+-rf\\b"]

开关

/privacy 是普通 DSH 命令。插件挂载后即可使用。

| 命令 | 作用 |
| /privacy 或 /privacy status | 显示模式、vault 后端/大小、当前会话 ON/OFF、计数器、已知缺口。 |
| /privacy off | 关闭当前会话的脱敏。新的用户消息/工具结果不再脱敏，直接通过。 |
| /privacy on | 重新开启当前会话的脱敏。已有历史不会被追溯脱敏，只处理新内容。 |
| /privacy global on / off | 修改进程级默认值（仅内存；会话级覆盖仍然优先）。 |
| /privacy test | 用本地哨兵值跑一遍检测器；不走网络。 |
| /privacy demo | 打印一条合成的用户消息 → 工具调用 → 解码链路。 |

配置里的 enabled 是启动默认值。/privacy on|off 是会话级覆盖，进程退出前一直有效。

Web 输入框开关

包还带一个小的浏览器端部分（lib/client.js，由 dsh.client 声明）。它在输入框的 plan 槽位注册一个 Privacy ON/OFF 开关，并通过现有的 Remote commands 命名空间调用同样的 /privacy status、/privacy on、/privacy off 命令。不需要 Settings 页面、配置档编辑或额外宿主服务。

如果客户端 bundle 被移除或加载失败，宿主命令接口照常工作。这个开关刻意只做展示：它不解析、也不显示 vault 里的值。

晚开启

DSH 没有可用的钩子能改写已经提交的消息。如果会话启动时脱敏是 OFF，之后再开启只保护新的用户消息和工具结果。已有历史可能仍含真实值，并会发给模型。在意的话请开新会话。命令会打印这条警告。

哪些内容会被脱敏

用户消息

agent/pre-step 在追加 user/message 之前，对每个 text/reasoning 块（以及调用方提供的工具结果内容）做脱敏。user/message 事件存的是 token。更早的 agent/inbox/spliced 审计事件在这个接缝之外，可能仍含原始输入。

工具结果 tools/post-execute 会遮蔽规范 value（递归处理，仅限 JSON 字符串）和渲染后的 content。模型看到的是 token，日志里存的也是 token。下游的 block 决策会被尊重。

遥测

session-telemetry/record 单向遮蔽导出的 body，替换为 [REDACTED:LABEL]。它从不写入 vault。这与会话日志是两回事：遥测可以完全关闭，但只要开着，就不该携带密钥。

哪些内容不会被遮蔽

- 模型自己生成的助手文本。 如果模型写出它已经知道的真实密钥，日志记录之前没有任何环节能看到它。插件遮蔽的是它控制的输入，不是模型的先验知识。
- 系统提示词 / AGENTS.md / 工具描述。 DSH 只提供追加式的 systemPrompt.section，没有提示词变换。别往这些文件里放密钥。
- 原始的 agent/inbox/spliced 事件。 DSH 在 agent/pre-step 有机会改写之前，就把用户输入追加到这个审计事件里。模型可见的 user/message 已被遮蔽，但原始 inbox 事件仍留在会话文件中。要堵住这个口子，需要未来的会话导出清洗器，或者一个输入准入钩子。
- 智能体循环之外的一次性调用（某些标题生成 / 压缩 / 辅助调用）不受 agent/pre-step / tools/post-execute 覆盖。如果它们携带的是已遮蔽的会话内容，那携带的就是 token，安全；如果它们直接读取外部来源，那就在本插件范围之外。
- 工具副作用。 密钥仍可能通过命令或 HTTP 请求泄露出去。secure_request 有主机白名单；secure_run 有尽力而为的命令策略（denyNetwork、allowedCommands、blockedPatterns），但不是内核级防火墙。把 secure_run 当作「智能体可以拿着真实值运行代码」——因为它确实可以。

Vault 与 token

- Token 形态：{{LABEL_xxxxxx}}；LABEL 是 1–12 个大写 ASCII 字符；xxxxxx 是六个 base32 字符（a–z、2–7）。
- 同一个 vault 内，相同的值得到相同的 token；同一个值用不同标签，仍会去重到第一个 token。
- vault 模式可逆：PII 和密钥可由安全工具解析还原。
- mask 模式不可逆：替换为 [REDACTED:LABEL]，且不查询 vault。
- 文件后端：$DSH_HOME/privacy-shield/vault.json（或 ~/.dsh/...），目录 0700，文件 0600，原子重命名。
- encryption: aes-256-gcm（默认）：映射用随机 32 字节密钥做 AES-256-GCM 加密，密钥在 vault.json.key（0600）。vault 文件只包含 {version:2, alg, iv, tag, data}。v1 明文文件仍可读取，并在下次写入 / 关闭时迁移。
- encryption: none 仅用于迁移 / 调试；它写出 v1 明文格式。
- 内存后端：映射随进程结束而消失；持久化日志里的 token 将无法解析。需要重启后仍可用，就用文件模式。
加密保护静态文件，但不防同一 UID 的进程：这类进程既能读保险库，也能读密钥。如果这不可接受，请改用内存模式或操作系统钥匙串。删除保险库或密钥会撤销全部映射。

能力工具

模型无法把 token 传给普通工具：tools/pre-execute 会拒绝，并给出提示。有五个工具在各自的函数体内解析 token。

secure_run
json
{ "command": "curl -H 'Authorization: Bearer {{API_KEY_ab12cd}}' https://api.example.com", "timeout_ms": 30000 }

- 解析 command 中的 token（遇到未知 token 即失败关闭）。
- 使用 ctx.shell（配置档的 shell 执行器），因此继承与 bash 工具相同的沙箱/执行器。
- 返回前再次遮蔽 stdout/stderr。
- 强制执行 secureTools.run：denyNetwork（默认 true）拦截常见网络客户端，allowedCommands 限制命令前缀（并拒绝 shell 串联），blockedPatterns 追加不区分大小写的正则拒绝规则。这只是防护，不是内核沙箱：bash -c、别名或任意解释器仍可发起网络调用。
- 返回 { exitCode, signal, timedOut, stdout, stderr } 或 { error }。

secure_write
json
{ "path": "config/.env", "content": "API_KEY={{API_KEY_ab12cd}}\n" }

- 解析 content 中的 token。
- 使用 ctx.fs（配置档的文件系统后端），因此遵循与 write 相同的工作区/沙箱策略。
- 只返回 { path, bytes }；真实内容绝不回显。

secure_read
json
{ "path": "config/.env" }

- 通过 ctx.fs 读取，返回内容前遮蔽每个检测到的值。
- 适合读取含密钥的 .env 或配置，而不把真实值放进模型上下文。
- 返回带 token 的 { path, content }，或 { error }。

secure_edit
json
{
"path": "config/.env",
"old_string": "API_KEY=old-value",
"new_string": "API_KEY={{API_KEY_ab12cd}}",
"replace_all": false
}

- 解析 old_string 和 new_string 中的 token。
- 通过 ctx.fs.editText 编辑，因此适用与 edit 相同的工作区/沙箱策略。
- 只返回 { path, bytes }；真实值绝不回显。

secure_request
json
{
"url": "https://api.example.com/v1/items",
"method": "POST",
"headers_json": "}\",\"Content-Type\":\"application/json\"}",
"body": "}\"}"
}

- 解析 URL、请求头值和 body 中的 token。
- 强制执行 secureTools.allowedHosts（空 = 任意主机；精确匹配或 .suffix）。
- redirect: "manual"，因此 3xx 无法悄悄把请求转到另一台主机。
- 返回前再次遮蔽响应体。
- 返回 { status, body } 或 { error }。
只有在 secureTools.enabled 为 true 且 ctx.tools 可用时，才会挂载这些工具。如果某个配置档里没有 ctx.shell / ctx.fs，工具会直接返回明确的错误，不会退回到不受沙箱约束的 Node 调用。

检测规则

内置规则（全部可配置）：

- API 密钥：sk-…、GitHub gh_/github_pat_、AWS AKIA/ASIA、Google AIza…、Slack xox…、Stripe sk_live_/rk_test_、npm、PyPI、GitLab、Hugging Face。
- JWT、PEM 私钥块、Bearer …、password=/token=/api_key= 赋值、数据库 URL 中的密码。
- PII：邮箱、中国大陆手机号、18 位居民身份证号（ISO 7064 校验）、银行卡号（Luhn 校验）、私有 IPv4（默认关闭）。
- 自定义正则规则，通过 customRules: [{ label, pattern }] 配置。

校验器会拒绝格式不合法的候选值，因此插件不会把每个 16 位数字、每个形似 user:pass@ 的字符串都打码。allowlist 中的条目按子串匹配（不区分大小写），匹配到的会跳过。

失败行为

- 打码失败（failMode: closed，默认）：钩子抛出异常，本轮直接失败，不会发出未打码的文本。设为 open 时，该值回退为 [REDACTED:LABEL]。
- 启动时读取 vault 失败：插件加载失败。损坏的 vault 绝不会被当作空 vault 处理。
- 执行时遇到未知 token：secure_* 拒绝运行（fail closed），绝不会把 token 原样替换进去。
- 本设计不包含还原：没有响应还原，所以模型回答里的 token 仍然是 token。将来可以在客户端加一层展示层，替人解析出真实值，同时不改变写入日志、模型可见的文本。

已知缺口

1. agent/inbox/spliced 保留原始用户输入。 官方的 pre-step 接缝在这个审计事件写入之后才运行。模型看不到原始文本（user/message 已打码），但原始会话导出能看到。dsh-secret-scrub 记录的也是同一个缺口。
2. 模型自己生成的助手文本不会打码，只有输入会。
3. 系统提示词 / AGENTS.md / 工具描述不做转换，不要把密钥放在这些地方。
4. 人类 UI 会显示 token。 本版本没有展示还原插件。
5. secure_run 可能用真实值执行代码。 denyNetwork / allowedCommands / blockedPatterns 提高了门槛，但它们不是出站防火墙；解释器可以绕过命令名扫描。
6. 加密密钥和 vault 放在一起（0600）。 它能防住备份泄露和随手翻看，但防不住同 UID 的攻击者——对方两个文件都能读。

与其他 DSH 隐私插件的关系

- dsh-redact / dsh-secret-scrub：在准入阶段打码，配有 vault / 能力工具。本插件增加了按会话开关、token 参数守卫，以及带主机白名单的 secure_request；它同样不还原助手展示内容。
- dsh-llmasking：只在 llm/stream 这一层做遮蔽，重新派发一份遮蔽后的副本；会话日志和 UI 保留真实值。这是另一种取舍，依赖重新派发这个变通做法。本插件让模型和日志保持一致（两边都遮蔽）。
- dsh-privacy-gateway：HMAC 稳定的占位符，加一条本地 UI 解析路径；聚焦 PII，没有工具参数能力层。
- dsh-honey-guard：结构化假值和金丝雀；刻意不做自动还原。

现有插件里，没有哪一个能同时做到只用官方接缝、运行时开关、通过能力工具执行任意工具、token 守卫。本插件就是朝这个组合的一次尝试。

链路，附真实示例

看 CHAIN.md 里一次真实的 DSH 0.2.1-rc.2 运行：agent/inbox/spliced 那个确切的坑、user/message 的 token、assistant/message 的工具调用、tool/call、vault 解析、tool/result，以及下一次请求——原始手机号不出现在任何一次服务商请求里。

验证

- npm test：33 个单元测试（检测、校验器、加密 vault/迁移、钩子、开关、命令、安全工具、入口接线、浏览器标签）。
- DSH 0.2.1-rc.2 无头冒烟测试，接本地 OpenAI 兼容端点：抓到的 /v1/chat/completions 请求体里是 {{PHONE_...}}，不是原始号码；secure_run、secure_write、secure_read、secure_edit、secure_request 都出现在请求的工具列表里。同一次测试也暴露了上面说的 agent/inbox/spliced 原始输入坑。

开发 sh
npm install
npm run build
npm test # builds, then 33 unit tests
npm run typecheck

目录结构： text src/ index.ts plugin entry + mounts config.ts schemastery config + normalization detect.ts rules, validators, overlap merge tokens.ts token format/random suffix vault.ts memory/file vault mask.ts text/JSON/content/message masking state.ts toggle + counters hooks.ts official seam listeners command.ts /privacy tools.ts secure_run / secure_write / secure_read / secure_edit / secure_request types.ts minimal structural DSH types lib/client.js browser composer chip (Privacy ON/OFF)

路线图

本次发布已完成：

- Web 输入框标签开关（lib/client.js）
- AES-256-GCM 文件 vault，密钥权限 0600，带 v1 迁移
- secure_read / secure_edit
- 尽力而为的 secure_run 出口守卫（denyNetwork、allowedCommands、blockedPatterns）

仍未完成，附原因：
1. 只对模型做投影（「日志保留真实内容，模型侧脱敏」）。SessionMessageProjection 是官方机制，但通用的脱敏投影需要一个受支持的追加点，位置在步骤消息提交之后、buildRequest 之前。agent/pre-step 在提交之前；agent/request 也在提交之前；session/event 拒绝重入追加；session/flush 在请求组装完成之后才运行。按消息逐条投影的朴素事件，还会让仓库外的会话日志无法恢复。这需要核心层留出接缝，靠插件取巧做不到。

2. 客户端显示还原。浏览器需要一条宿主 RPC，用来解析 token，同时不把值写进会话事件。像 /privacy reveal 这样的模板字面量命令，会把结果记进 command/done，所以它不是安全的显示路径。

3. 操作系统钥匙串保险库后端。AES 密钥目前和保险库放在同一目录（0600）；改用钥匙串就能把它移出这个目录。

4. 更强的出站控制。secure_run 只是命令名守卫；真正的边界是网络命名空间/代理，或者让 secure_request 成为唯一的出站路径。

5. 更多校验器：云服务商专属检查、IBAN、国民身份标识，以及用户自定义的校验钩子。

License

MIT. See LICENSE。