安全与引用库

层级：专题适用：0.1.x 权威性：安全边界与引用库说明；具体参数见《工具与参数》

1. 一句话结论

这是个人工具，不是沙箱、不是多租户隔离、也不是“AI 权限系统”。

它给 AI 的是你本人权限下的真实 shell。AI 能执行命令之后，就能读写你的文件、访问本机接口、改插件数据，甚至改审计文件。插件内的任何规则都只能约束“愿意遵守规则的程序”，挡不住恶意或提示词注入后的 AI。

所以，真正能约束 AI 的只有两类东西：

它没有拿到的操作系统权限（独立用户、容器、虚拟机、宿主侧 broker）；
你在执行前的人为判断（以及 DSH 的沙箱模式）。

插件内的模式闸门、锁、危险命令护栏、审计和引用库，都是在这个前提下的降低风险，不是安全隔离。

2. 信任边界：同用户、同机器

这是理解所有边界的起点：

你的用户账号
├── DSH / 本插件进程
│   ├── 读取 ~/.dsh/terminalkeeper/ 下的数据
│   ├── 提供本机 HTTP 接口
│   └── 驱动 tmux 服务端
├── tmux 服务端
│   └── 持久 shell（AI 通过工具操作）
└── AI 的 shell
    └── 和插件进程拥有同一个 UID、同一套文件权限

因此：

插件进程能访问的文件，AI 的 shell 基本也能访问；
本机上的其它进程通常也能访问这些接口（除非 DSH 的 connection 服务做了浏览器会话校验）；
插件没有独立的 Linux 用户、没有 seccomp、没有容器，也没有独立的能力令牌；
一旦 AI 能执行任意命令，它就可以尝试改策略、读数据、改代码或绕过插件。

这不是“实现得不够好”，而是部署形态决定的上限。

3. 实际能起作用的四件事

机制	能做什么	不能做什么
DSH 模式闸门	在 `workspace-write` / `read-only` 下拒绝插件写工具，避免插件 shell 绕过 DSH 文件沙箱	完全控制模式下不拦截；不限制 DSH 原生 bash；不防 AI 用其它通道
手动锁	人锁住 shell 后，AI 对该 shell 的写入/改动被拒；人可解锁	只读不受影响；不是身份认证；AI 仍可读屏
危险命令护栏	拦 `rm -rf /`、`mkfs`、`dd of=/dev/*`、`curl\|sh` 等明显高危形状	启发式；变量、脚本、拼接、别名都能绕过；会误报
审计链	记录输入、开关会话、引用库操作等；可发现删改/重排/截断；可选镜像和 `chattr +a`	同用户可改审计文件和签名私钥；不能证明“没被改过”

锁和归属不是权限模型。

owner 只表示“谁创建的”，跨对话用具体 id 操作别的 shell 是允许的；“不要动别人的 shell”是模型使用约定，不是系统强制。

4. 引用库：只防“直接进模型”，不防主动读取

引用库（vault）解决的是一个很具体的问题：

不要把密码、令牌等敏感值直接放进模型的上下文，也不要把它们展开进 AI 可以加工的普通命令。

它采用“键值分离”：

人通过面板写入值；
AI 的工具面只能看到键名、组、剩余次数等元数据；
AI 使用 `` 引用时，由宿主侧解析值，并只允许整条裸引用作为进程输入（例如喂给 sudo -S / read -s 的 stdin）；
嵌进 echo、管道、curl -H、宏等命令形态会被拒绝，避免值进入 AI 可读取的输出管线；
面板列表不回显值；单键读取会写审计。

它不能做什么

引用库不防 AI 主动读取。 只要 AI 有 shell / 本机接口访问权，它仍可能：

直接 cat ~/.dsh/terminalkeeper/vault.json；
在用户解锁口令组后调用本机 /vault-get 之类的接口；
把引用值喂给会回显的程序（cat、env、日志程序）；
用 base64/rev/od 等变换绕过字面打码；
从 output/ 留痕、进程输出、终端屏幕里读到值。

所以准确的表述是：

引用库防“敏感信息直接进入模型上下文”，不防“AI 主动把值读出来”。

5. 口令加密到底防什么

引用组有三种模式：

模式	落盘	主要作用
不加密	明文	开箱即用；不防本机同用户
简单混淆	设备密钥混淆	防“全盘搜索直接看到明文”；不是强保密
口令加密	AES-GCM 密文	未解锁时磁盘上只有密文；不知道口令无法解密

口令组的密钥派生：

KEK = HMAC-SHA256(pepper, scrypt(口令, salt))

scrypt 让每次口令猜测都有 CPU/内存成本；
pepper 是 32 字节设备随机值，存在 vault.pepper，和 vault.json 分文件；
只拿到 vault.json：没有 pepper，不能直接用密文离线猜口令；
口令组未解锁：插件不会自动解密，AI 直接读 vault.json 只能得到密文；
解锁之后：KEK 在宿主内存里，值可以按用户操作解密；此时“同用户 AI 不能读”不再成立；
pepper 也在数据目录：同权限 AI 如果同时读走 vault.json 和 vault.pepper，pepper 就不再提供额外保护，只剩 scrypt + 口令强度；
解锁有“60 秒内 5 次失败”限速，但这是在线接口限速，不是离线暴力破解的绝对防护。

因此：

口令模式在“未解锁”时可防直接读盘得到明文；它不防同用户 AI 主动拿走密文后离线尝试，也不防用户解锁后的读取。

最稳妥的用法是：长期秘密放在口令组，只在可信时段解锁；不要把“引用库”当成秘密不会泄露的保证。

5.1 落盘结构（技术细节）

一组 = 一整段密文：组名、值、剩余次数、备注一起加密；不是逐条明文记录。
AAD：加密时把组名和代数（epoch）作为附加认证数据；把整段密文搬到别的组会解密失败，防跨组拼接。
分桶填充：加密前把长度填充到统一桶，密文长度和条目数量不可直接看出。
计数取最大值：剩余次数取 max(文件里的值, 内存里的值)，单侧回滚不会把已用次数改小。
删除不留明文键名：只保留不透明的 entryId 和名字指纹（用于烧伤标记）。
状态头：保存单调递增的 seq，用于判断回滚/缺头/篡改；读取和写入都是 O(1)，不需要每次扫描全部内容。
诚实边界：这些设计防的是“直接读文件拿到明文/静默回滚计数”，不防同用户 AI 在解锁后读取，也不防整盘替换。

6. 审计链：可发现篡改，不是不可篡改

审计记录进入逐天 SHA-256 哈希链，检查点用 Ed25519 签名；可配置镜像，也可以给审计目录加 chattr +a。

改一条、删一条、重排、截断、删整天文件、检查点回滚，通常都能被发现；
删除动作会先写“删除见证”，不是悄悄删；
但签名私钥、审计文件都在同一个用户可访问的位置；
同用户或 root 可以控制磁盘、私钥和进程，能整盘替换或删光；
默认情况下这不是不可篡改存储，只是“事后查得清”。

7. 攻击面清单

路径	风险
提示词注入 → AI 调工具	AI 以你的用户权限执行命令；插件内的规则不能阻止
本机 HTTP 路由	面板和宿主通过本机 HTTP 通信；如果 AI 能发请求，它可能操作会话或读取面板能读的数据
同源浏览器页面	同源插件 JS / XSS 可以访问面板接口；不要把不可信页面装进同一个 DSH
引用库文件	同权限可直接读；口令组未解锁只见密文
终端输出 / 留痕	值进入屏幕就会进原始留痕；打码占位符是 `redacted`，只覆盖部分可见面
插件代码 / 配置	同用户可改；改完可能影响下一次启动或运行中的行为
审计 / 签名私钥	同用户可改；镜像和 `chattr +a` 只是提高成本

8. 使用建议

把它当个人工具：不要在多人共用、生产、含有不可替代数据的机器上把完整 shell 长期交给不可信 AI。
保持 DSH 的受限模式：非必要不要给 danger-full-access；模式闸门只有在完全控制之外才有意义。
不要用一个长期 full shell 跑不受信任的提示词；受污染后，当前会话的所有数据都应视为可能已泄露。
引用库存短秘密：长期令牌放口令组，只在可信时段解锁；备份时同时保存 vault.json 和 vault.pepper。
不要把引用库当保密边界：需要真正的秘密隔离时，使用独立用户/容器/外部密钥服务。
审计锁可选开启：./install-deps.sh --audit-lock；它防的是文件被追加/删改，不防读取，也不防同用户控制整台机器。
需要多智能体隔离时：不要让它们共享同一个插件数据目录和同一个用户；用独立用户、容器或宿主侧 broker。

一句话：

模式闸门负责避免插件绕过 DSH 沙箱，锁负责人机互斥，护栏负责减少手滑，审计负责事后追溯，引用库负责避免秘密直接进入模型上下文；它们都不负责“防住已经拿到同用户 shell 的 AI”。

9. 报告安全问题

请不要在公开 issue 里贴可利用载荷、凭据、内网地址或完整日志。

优先用 GitHub 的 Security → Report a vulnerability 私有报告；说明 DSH 版本、tmux -V、插件版本和受影响工具/页面即可。

不得把“显示打码”说成“防泄露”，不得把状态头/审计链说成“不可篡改”，也不得把引用库说成“AI 无法读取”。

↑ 回到目录