SurrogateShield安全设计清单:fail-closed、密钥派生与文件权限细节全梳理

原创2026-11-13 14:43:581,955 阅读

SurrogateShield安全设计清单:fail-closed、密钥派生与文件权限细节全梳理

SurrogateShield 是一个面向 LLM 与 RAG 管道的隐私优先防护工具:它在消息发出前实时检测并替换 PII(个人身份信息),收到回复后再把真实值还原,且所有加密操作都在本地完成。本文带你完整梳理它的 5 层安全设计:fail-closed 失效行为、HKDF-SHA256 密钥派生、AES-256-GCM 加密存储,以及 0o600/0o700 文件权限细节,帮你判断这类隐私工具的底层保障是否可靠。

为什么这套安全设计值得细看 🛡️

SurrogateShield 的核心机制是"影子映射"(ShadowMap):每个真实值(如你的邮箱、社保号)会被替换成一个逼真的替身值,映射关系存在本地磁盘上。这意味着映射文件本身就是最高价值资产——一旦泄露,替身值就能被还原成真实 PII。

因此它的安全设计围绕三条原则展开(见 SECURITY.md 的 Scope 章节):

原则 具体含义
宁停勿漏 检测器任何环节失败,宁可报错拒发,也不放行原文
密钥与数据分离 密钥派生自设备本地秘密,绝不与数据文件放在一起
全程留痕可审计 权限收紧、原子写入、损坏隔离,每一步都有防御性处理

一、fail-closed:出错时"关门"而不是"放行" 🚪

普通工具在模型加载失败时常常静默降级——返回"没检测到实体",结果原文直接发给了 LLM。SurrogateShield 的做法正相反:

  • 检测模型缺失或加载失败:抛出 DetectorUnavailable 异常,mask()/scan() 不返回任何内容,整条请求被阻断;
  • 模型对输入推理出错(如 CUDA 错误):同样抛异常,绝不把 spaCy 处理不了的输入当作"无实体"(见 entity_trace.py 的注释);
  • 映射文件写不进去:抛 StorageError,因为"存不下的映射意味着下一轮无法还原",调用方必须知道(见 shadow_map.py);
  • 离线环境未缓存模型:HF_HUB_OFFLINE=1 且无缓存时,balanced/fast/strict 预设拒绝工作而非偷偷联网下载(见 CONFIGURATION.md)。

这些行为不是口头承诺,而是有专门测试锁死的:tests/test_fail_closed.py 的注释写明"缺失或故障的模型必须抛 DetectorUnavailable,而不是返回'无实体'",覆盖 spaCy 缺失、ContextGuard 崩溃、级联传播、库 API 静默失败等全部路径。

模型权重也要"验明正身"

检测质量取决于模型本身,所以 PII tagger 的权重文件被 SHA-256 钉住(pin):配置里写的不是"哪个仓库的哪个分支",而是 sha256: 加权重文件的哈希值。本地权重与钉值不符时,在 import torch 之前就 fail closed(见 pii_tagger.py 与 test_security_contract.py)。

连模型输出的形状也会校验:标签数量对不上、偏移越界、结果行数与输入文本数不符等畸形输出,一律抛 DetectorUnavailable,且异常信息里不带原文——避免你的数据借异常消息二次泄露(见 test_security_contract.py)。

二、密钥派生:HKDF-SHA256 如何为每个会话"生"一把钥匙 🔑

密钥管理的核心思路是:只存一个设备秘密,其余密钥全部派生。

device.key:唯一的根秘密

首次使用时生成一个 32 字节随机数,存为 ~/.surrogateshield/device.key(可用环境变量 SURROGATESHIELD_HOME 改目录)。几个关键细节:

  • 创建是原子的:先写临时文件再用硬链接占位,两个进程同时启动也不会生成出两个不同的秘密(见 shadow_map.py);
  • 读到的秘密长度不对就拒绝派生——"密钥绝不从被截断的秘密派生";
  • 秘密文件不可读写时,默认抛 ShadowMapStorageError;只有调用方显式选择 allow_ephemeral 才退化为进程级临时密钥(重启后写下的数据无法再读,宁可丢也不裸奔)。

每个会话一把独立的 AES 密钥

ShadowMap 的 AES-256-GCM 密钥不是直接用 device.key,而是:

key = HKDF-SHA256(ikm=device secret, salt=会话ID, info=文件种类)
  • salt 用会话 ID、info 用文件种类(shadowmap-v1 或 transcript-v1),实现于 derive_key();
  • 种类 + ID 还作为 **AAD(附加认证数据)**绑进密文,所以"一个文件只能以它写入时的种类和 ID 打开"——把某会话的 shadowmap 当成 transcript 解密会直接认证失败。

ShadowMap 文件格式

落盘格式为 "SSv1" ‖ 12字节随机 nonce ‖ AES-GCM 密文(见 shadow_map.py)。每次写入用全新 nonce;无法解密的文件会被移走隔离为 <name>.corrupt-<时间戳> 而不是删掉,并抛 CorruptStoreError——"它永远不会悄无声息地变成一个空映射"。

三、文件权限细节:0o700、0o600 与原子写入 🔒

运行时数据全部落在 ~/.surrogateshield/ 下,权限要求如下:

对象 权限 说明
~/.surrogateshield/ 目录 0o700 仅属主可进入
device.key 0o600 32 字节根秘密
<会话ID>.shadowmap 0o600 加密的替身→真实值映射
conversations/*.json 0o600 加密的会话历史(含你输入的真实值)

实现上有几个值得抄作业的防御细节:

  1. 事后收紧:ensure_private_dir() 建目录时用 0o700,如果目录已存在且权限偏松(st_mode & 0o077 非零),主动 chmod 收紧;device.key 同样处理,并打 warning 日志提示"权限偏松已修复"(见 shadow_map.py 与 #L145-L147);
  2. 原子写入:所有写入走"临时文件 → fchmod 0o600 → fsync → rename"四步,中途失败会清理临时文件,绝不留半个密文(见 write_private());
  3. ID 防路径穿越:会话 ID 必须匹配 ^[A-Za-z0-9_-]{1,64}$,../ 之类的名字在触碰任何文件前就被 validate_id() 拒绝;
  4. .gitignore 兜底:*.shadowmap、conversations/、device.key、.env、*.key、*.pem 全部排除在版本控制之外,且运行目录 ~/.surrogateshield/ 本身就在仓库之外。

四、其他容易被忽略的防线 🕵️

  • 日志零真实值:安全契约测试用一条塞满姓名、邮箱、SSN、卡号、地址的"金丝雀"消息跑完整流程,断言任何级别(含 DEBUG)的日志里都不出现其中的任何一个真实值(见 test_security_contract.py);
  • 包本身无网络出口:静态扫描整个库,禁止 socket/requests/urllib 等网络模块与 pickle/eval 等不安全反序列化入口,动态测试则直接让所有 socket 操作抛异常来验证"掩码过程零网络请求"(见 test_security_contract.py);
  • 随机数隔离:替身值生成不跟随全局 random 状态,保证攻击者无法通过观察随机序列预测替身。

五、如何验证这些设计?🧪

这套清单不是文档里的美好愿望,而是被两条测试线持续执行:

运行方式(需先安装依赖):

python -m pytest python-library/tests/test_security_contract.py

总结:一张表看懂 SurrogateShield 安全设计 ✅

防线 机制 源码位置
失效行为 任一检测/存储失败即抛错阻断,不降级放行 core/detection/
模型完整性 权重 SHA-256 钉住 + 畸形输出 fail closed pii_tagger.py
密钥根 32 字节 device.key,0o600,原子创建 shadow_map.py
密钥派生 HKDF-SHA256,会话 ID 为 salt,文件种类为 info/AAD shadow_map.py
加密存储 AES-256-GCM,新 nonce,SSv1 格式 shadow_map.py
文件权限 目录 0o700、文件 0o600,偏松自动收紧 shadow_map.py
数据卫生 ID 正则防穿越、损坏隔离不删除、日志无真实值、包无网络模块 test_security_contract.py

对新手而言,这份清单的价值在于:它示范了"隐私工具"该有的工程底线——安全关键路径上,永远选择大声失败,而不是安静通过。

登录后查看全文
SurrogateShield