OpenMed 防篡改审计链:在本地构建可验证的去标识化审计日志
OpenMed 防篡改审计链:在本地构建可验证的去标识化审计日志
导读
OpenMed 提供了一种把去标识化(de-identification)审计报告链接成有序、只追加(append-only)防篡改链的能力:链上每条记录都对前一条记录的哈希、序号、报告可复现哈希、输入文本哈希、去标识化输出文本哈希以及最小化的 span 摘要做出承诺。本文围绕 docs/security/tamper-evident-audit-log.md 展开,介绍审计链的生成、追加、CLI 校验、链上存储的字段边界与安全边界,并结合 openmed/core/audit_chain.py 的实现与单元测试,帮助你在本地合规场景中构建、验证与归档可追溯的去标识化证据。
一、什么是防篡改审计链
OpenMed 的防篡改审计链是一份完全本地化的合规证据文档。它的核心设计目标有三个:
- 链接(linking):每个新条目(entry)都要携带上一条目的哈希,形成一条单向链;
- 只追加(append-only):条目按序号递增,只能追加、不能插入、删除或重排;
- 可检测(detectable):链文档中保留的
entry_count与head_hash让尾部被截断(truncation)也能在验证时被发现。
链的创建与验证不发起任何网络调用,这一点在源码中也得到印证:AuditChain.verify() 是纯内存操作,append_to_chain_file 只涉及磁盘文件的原子替换,没有任何远程依赖。这意味着你可以把它用在完全隔离的合规环境中。
从实现看,链的格式、版本与创世哈希定义在 openmed/core/audit_chain.py:
CHAIN_FORMAT = "openmed.audit-chain"
CHAIN_VERSION = 1
GENESIS_HASH = stable_hash(
{"format": CHAIN_FORMAT, "version": CHAIN_VERSION, "sequence": -1}
)
第一条真实条目的 previous_hash 就是 GENESIS_HASH,后续每条都指向前一条的 entry_hash,从而形成一条不可断开的哈希链。
二、创建审计报告并追加到链
2.1 使用 deidentify(..., audit=True) 生成报告
要让一次去标识化运行生成 AuditReport,在调用 deidentify 时开启 audit=True。audit 参数是 deidentify 的关键字参数(见 openmed/core/pii.py),开启后函数返回的不再是普通脱敏结果,而是 AuditReport(见 openmed/core/pii.py 的返回值说明)。
2.2 用 append_to_chain_file 一步完成追加
文档给出的最小可运行示例:
from openmed import deidentify
from openmed.core.audit_chain import append_to_chain_file
report = deidentify(
clinical_text,
method="mask",
policy="hipaa_safe_harbor",
audit=True,
)
entry = append_to_chain_file("audit-chain.json", report)
print(entry.sequence, entry.entry_hash)
append_to_chain_file 的职责(openmed/core/audit_chain.py):
- 若目标链文件不存在,则创建一个全新的
AuditChain(); - 若存在,则先完整加载并验证现有链(
AuditChain.load之后走chain.append,而append内部会先执行verify()); - 拒绝追加
repro_hash与报告内容不再匹配的报告(_entry_from_report中调用report.repro_hash_matches(),不匹配直接抛ValueError,见 openmed/core/audit_chain.py); - 追加成功后通过临时文件 +
os.replace原子替换链文档(见 openmed/core/audit_chain.py),避免写入中途损坏链文件。
返回的 entry 是 AuditChainEntry,包含 sequence(从 0 开始的序号)与 entry_hash(本条目的哈希)。
2.3 内存中的 AuditChain 用法
如果不想立即落盘,可以先在内存中构建,最后再写文件:
from openmed.core.audit_chain import AuditChain
chain = AuditChain()
chain.append(first_report)
chain.append(second_report)
assert chain.verify().valid
chain.write("audit-chain.json")
AuditChain.append() 在追加前会先验证当前链,若链已失效会直接抛出 ValueError(见 openmed/core/audit_chain.py);write() 同样采用原子替换方式持久化。AuditChain 还提供了 contains_report(report) 用于判断某个报告是否已提交到链上(openmed/core/audit_chain.py)。
说明:示例中
deidentify的更多参数(如method、policy、confidence_threshold、lang等)均可在 openmed/core/pii.py 查看完整签名;method支持mask、remove、replace、hash、shift_dates、format_preserve、aadhaar_mask等策略。
三、从 CLI 验证链与报告成员资格
OpenMed 的 CLI 在 audit 子命令下提供了 verify 与 verify-chain 两个入口(命令注册见 openmed/cli/main.py)。
3.1 audit verify:同时识别报告与链
openmed audit verify audit-chain.json
verify 会自动识别输入文件是单条审计报告还是链文档(_load_audit_artifact 通过链的 format 字段区分,见 openmed/cli/main.py):
- 若是链,则执行
_audit_chain_verification,输出verified、entries_checked、reason(openmed/cli/main.py); - 若是单条报告,则执行
_audit_report_verification,校验repro_hash与 HMAC 签名(openmed/cli/main.py)。
校验失败时进程退出码为 1,成功为 0(见 openmed/cli/main.py)。
3.2 audit verify-chain:验证链并确认报告成员资格
openmed audit verify-chain audit-chain.json \
--report audit-report.json \
--key "$OPENMED_AUDIT_KEY"
--report指定要同时验证的签名报告;--key指定 HMAC 密钥;省略时从环境变量OPENMED_AUDIT_KEY读取(_AUDIT_KEY_ENV定义于 openmed/cli/main.py)。
最终 verified 为真需要同时满足三个条件(openmed/cli/main.py):
- 链本身验证通过;
- 报告本身的
repro_hash与签名验证通过; chain.contains_report(report)确认报告确实是链上的一个条目。
3.3 失败时的输出
以下任一情况都会导致验证失败,且输出会指明被检测到的具体条件,并在可定位时给出受影响的条目索引:
| 检测条件 | 失败原因输出(示例) |
|---|---|
| 插入 | insertion detected: chain contains more entries than declared |
| 删除 | deletion detected: chain contains fewer entries than declared |
| 重排 | reordering detected: entry sequence is out of order |
| 链接断裂(重排/篡改) | reordering or mutation detected: broken link at entry {index} |
| 条目哈希不匹配(篡改) | mutation detected: hash mismatch at entry {index} |
| 尾部截断 | deletion or mutation detected: retained head hash does not match |
这些 reason 字符串与 ChainVerificationResult 一一对应,完整逻辑见 openmed/core/audit_chain.py。
四、链上存储什么:刻意收窄的字段
审计链格式刻意比完整 AuditReport 更窄。一个条目只包含(_ENTRY_FIELDS,见 openmed/core/audit_chain.py):
sequence:序号;previous_hash:前一条目的哈希(首条为GENESIS_HASH);report_hash:报告的repro_hash(可复现哈希);input_hash:原始输入文本哈希;deidentified_text_hash:脱敏后输出文本哈希;spans:最小化 span 摘要列表,每个 span 只含start、end、label、text_hash(_SPAN_FIELDS,见 openmed/core/audit_chain.py),其中label必须属于规范化标签集合CANONICAL_LABELS;entry_hash:本条目的哈希。
AuditChainSpan.from_audit_span 把完整的 AuditSpan 收敛为"规范化标签 + 偏移 + 文本哈希"三类字段(openmed/core/audit_chain.py),因此链上不出现:
- 原始文本与脱敏文本本身;
- 替代值(surrogate);
- 上下文(context);
- 检测器证据(evidence)与映射(mapping);
- 自由格式元数据与残余风险备注。
更为关键的是:链加载时会拒绝未知字段(_reject_unknown_fields,见 openmed/core/audit_chain.py)。这意味着即使有人想"顺手"把未提交的明文数据塞进链文档,加载时也会直接抛 ValueError,不可能藏在已校验载荷旁边。
链的文档级结构同样固定(_CHAIN_FIELDS,见 openmed/core/audit_chain.py):format、version、genesis_hash、entry_count、head_hash、entries。加载时若 format、version 或 genesis_hash 与当前实现不符,同样会被拒绝(openmed/core/audit_chain.py)。
五、验证算法:如何检测插入、删除、重排与篡改
AuditChain.verify()(openmed/core/audit_chain.py)按顺序执行五步检查:
- 条数对比:实际条目数大于声明的
entry_count→ 检测到插入;小于 → 检测到删除; - 序号连续性:条目
sequence必须严格等于0..n-1;乱序但不缺号 → 重排;缺号 → 插入或删除; - 链接校验:从
GENESIS_HASH开始,逐条检查previous_hash是否等于上一条的entry_hash,断裂即报"broken link at entry i"; - 条目哈希校验:每个
entry.entry_hash必须等于按规范载荷重算的compute_hash(),不匹配即"hash mismatch at entry i"; - 头部锚点校验:最终累计的哈希必须等于文档中保留的
head_hash,否则说明尾部被截断或篡改。
全部通过后返回 ChainVerificationResult(valid=True, checked_entries=n, reason="chain is valid")。
哈希的确定性依赖两点:
- 规范 JSON 序列化:
_canonical_json使用sort_keys=True、紧凑分隔符、ensure_ascii=True、allow_nan=False(openmed/core/audit_chain.py),保证同一载荷永远得到同一字节序列; - 稳定哈希算法:
stable_hash对规范 JSON 取 SHA-256(openmed/core/audit.py)。
另外,报告的 repro_hash 本身也做了排序归一化:span 先按 (start, end, canonical_label, action, 规范JSON) 排序再哈希(见 openmed/core/audit.py),因此两条逻辑等价、只是内部拼接顺序不同的运行会产生相同的 repro_hash,可复现性不受装配顺序影响;同时 repro_hash_matches() 兼容旧版按存储顺序哈希的 legacy 报告(openmed/core/audit.py),保证升级后老报告仍可验证。
单元测试 tests/unit/core/test_audit_chain.py 覆盖了链的追加链接关系(首条 previous_hash == GENESIS_HASH、次条 previous_hash == first.entry_hash)、JSON/磁盘往返(from_json、write、load)、append_to_chain_file 追加保留既有条目,以及链验证、成员判断等路径,可作为实现行为的可执行证据。
六、安全边界与合规实践
一个验证通过的链只能证明:链中内容仍然与它保留的条目数、头部哈希和链接关系一致。它不能证明"谁"创建了链,也不能替代:
- 访问控制(access controls);
- 备份(backups);
- 单条审计报告上的 HMAC 签名。
因此文档明确给出三条实践建议:
- 对普通消费者保持链文档只读:只有追加流程可以写链;
- 把链的
head_hash连同发布/合规记录一起留存:头部哈希是链完整性的离线锚点,尾部被截断时凭它即可发现; - 当真实性(authenticity)重要时,同时验证签名报告及其链成员资格:即使用
verify-chain --report ... --key ...的组合校验。
需要特别强调的是:HMAC 签名针对的是单条报告(AuditReport.signature,算法与密钥信息见 openmed/core/audit.py),而链本身不做签名,只做完整性证明。两者互为补充——签名回答"这份报告是否由持有密钥的一方生成",链回答"这份报告是否自生成以来未被改动、且未被从证据序列中移除"。
最后,分布式共识(distributed consensus)与外部时间戳权威(external timestamp authorities)明确不在本功能的范围内。审计链定位为"本地合规证据",适合需要完全离线的受监管环境;若需要跨方共识或第三方时间戳,需要在 OpenMed 之外另行集成。
七、关键 API 速查
| 组件 | 说明 | 源码位置 |
|---|---|---|
deidentify(..., audit=True) |
生成 AuditReport 的入口 |
openmed/core/pii.py |
AuditReport |
可签名、可复现的去标识化审计报告 | openmed/core/audit.py |
AuditChain |
内存中的只追加链(append / verify / write / contains_report) |
openmed/core/audit_chain.py |
AuditChainEntry |
单个链条目(sequence、previous_hash、各哈希、spans、entry_hash) |
openmed/core/audit_chain.py |
AuditChainSpan |
PHI 安全的 span 摘要(start、end、label、text_hash) |
openmed/core/audit_chain.py |
append_to_chain_file(path, report) |
加载并验证现有链后原子追加 | openmed/core/audit_chain.py |
verify_chain(chain) |
链验证的便捷函数 | openmed/core/audit_chain.py |
ChainVerificationResult |
验证结果(valid、checked_entries、reason、entry_index) |
openmed/core/audit_chain.py |
openmed audit verify / verify-chain |
CLI 校验入口 | openmed/cli/main.py |
| 链单元测试 | 追加、往返、篡改检测等测试用例 | tests/unit/core/test_audit_chain.py |
八、小结
OpenMed 的防篡改审计链把"逐次去标识化运行"沉淀为一份可独立验证、完全离线、PHI 最小化的合规证据文档:字段刻意收窄到只含哈希与最小 span 摘要,未知字段一律拒绝,序号、链接、条目哈希与头部锚点共同构成五步校验,使插入、删除、重排、篡改与尾部截断全部可被检出。配合单条报告上的 HMAC 签名与 head_hash 的离线归档,这套机制足以支撑 HIPAA 等场景下的本地审计留痕需求——并且全程零网络调用,天然适合隔离网络与本地合规环境。