SurrogateShield安全设计清单:fail-closed、密钥派生与文件权限细节全梳理
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 |
加密的会话历史(含你输入的真实值) |
实现上有几个值得抄作业的防御细节:
- 事后收紧:
ensure_private_dir()建目录时用0o700,如果目录已存在且权限偏松(st_mode & 0o077非零),主动chmod收紧;device.key同样处理,并打 warning 日志提示"权限偏松已修复"(见 shadow_map.py 与 #L145-L147); - 原子写入:所有写入走"临时文件 →
fchmod 0o600→fsync→rename"四步,中途失败会清理临时文件,绝不留半个密文(见 write_private()); - ID 防路径穿越:会话 ID 必须匹配
^[A-Za-z0-9_-]{1,64}$,../之类的名字在触碰任何文件前就被validate_id()拒绝; .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-library/tests/test_security_contract.py 覆盖"无出口、模型权重钉死且失败即闭、ShadowMap 与 README 描述一致、各级日志无值、每种失败模式 fail-closed、对抗输入时限有限"六大块;
- 专项测试:如 tests/test_fail_closed.py 专测检测失效路径,tests/test_shadow_map.py 专测加密存储行为。
运行方式(需先安装依赖):
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 |
对新手而言,这份清单的价值在于:它示范了"隐私工具"该有的工程底线——安全关键路径上,永远选择大声失败,而不是安静通过。