OpenMed 防篡改审计链:在本地构建可验证的去标识化审计日志

原创2026-09-17 17:55:112,126 阅读
文章标签:医疗健康NLP数据脱敏人工智能隐私合规AI 技能MCP 服务本地部署

OpenMed 防篡改审计链:在本地构建可验证的去标识化审计日志

导读

OpenMed 提供了一种把去标识化(de-identification)审计报告链接成有序、只追加(append-only)防篡改链的能力:链上每条记录都对前一条记录的哈希、序号、报告可复现哈希、输入文本哈希、去标识化输出文本哈希以及最小化的 span 摘要做出承诺。本文围绕 docs/security/tamper-evident-audit-log.md 展开,介绍审计链的生成、追加、CLI 校验、链上存储的字段边界与安全边界,并结合 openmed/core/audit_chain.py 的实现与单元测试,帮助你在本地合规场景中构建、验证与归档可追溯的去标识化证据。


一、什么是防篡改审计链

OpenMed 的防篡改审计链是一份完全本地化的合规证据文档。它的核心设计目标有三个:

  1. 链接(linking):每个新条目(entry)都要携带上一条目的哈希,形成一条单向链;
  2. 只追加(append-only):条目按序号递增,只能追加、不能插入、删除或重排;
  3. 可检测(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):

  1. 链本身验证通过;
  2. 报告本身的 repro_hash 与签名验证通过;
  3. 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)按顺序执行五步检查:

  1. 条数对比:实际条目数大于声明的 entry_count → 检测到插入;小于 → 检测到删除;
  2. 序号连续性:条目 sequence 必须严格等于 0..n-1;乱序但不缺号 → 重排;缺号 → 插入或删除;
  3. 链接校验:从 GENESIS_HASH 开始,逐条检查 previous_hash 是否等于上一条的 entry_hash,断裂即报"broken link at entry i";
  4. 条目哈希校验:每个 entry.entry_hash 必须等于按规范载荷重算的 compute_hash(),不匹配即"hash mismatch at entry i";
  5. 头部锚点校验:最终累计的哈希必须等于文档中保留的 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 签名。

因此文档明确给出三条实践建议:

  1. 对普通消费者保持链文档只读:只有追加流程可以写链;
  2. 把链的 head_hash 连同发布/合规记录一起留存:头部哈希是链完整性的离线锚点,尾部被截断时凭它即可发现;
  3. 当真实性(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 等场景下的本地审计留痕需求——并且全程零网络调用,天然适合隔离网络与本地合规环境。

登录后查看全文
openmed