OpenMed 21 CFR Part 11 审计追踪:PHI 安全、可离线验证的本地审计链实战指南

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

OpenMed 21 CFR Part 11 审计追踪:PHI 安全、可离线验证的本地审计链实战指南

导读

本文围绕 OpenMed 仓库中的 21-cfr-part-11-audit-trail.md 展开,系统讲解 openmed.compliance.part11 模块如何为可能受 21 CFR Part 11 约束的工作流生成本地化、PHI 安全的审计追踪技术证据。你将掌握:如何用 Python API 或 CLI 发射审计记录、sha256: 摘要状态引用的设计原理、记录与链字段的语义、导出产物的完整性验证方式,以及一份逐条款映射的 Part 11 就绪度对照表(readiness crosswalk),从而在无需云服务的前提下为审计审查提供可验证的证据制品。


一、设计定位:技术证据,而非合规认证

21 CFR Part 11 是美国 FDA 关于电子记录与电子签名(ERES)的法规。OpenMed 提供的不是认证或法律意见,而是一套实现辅助工具:openmed.compliance.part11 在本地发射审计追踪证据,记录"谁(actor)、做了什么(action)、何时(UTC 时间)、变更前后状态引用(before/after state)、为什么(reason code)"这五要素,并将每条记录提交到追加式哈希链(append-only hash chain)中。

该模块的核心设计原则(见 part11.py 的模块文档)包括:

  • PHI 安全:每条状态只以受约束的标签(bounded label)加 sha256: 摘要表示,原始值、替换文本与临床文本绝不写入记录;
  • 本地优先:发射、验证、导出全部离线完成,无需网络;
  • 边界明确:电子签名工作流与身份供给(identity provisioning)被刻意排除在范围之外;系统验证、访问控制、身份核验、留存、备份、培训与书面政策等责任仍由采用组织承担。

模块常量也体现了这一自我约束,PART11_NOTICE 明确声明"该制品是 OpenMed 运行产生的技术证据,不是法律认证,也不构成对 21 CFR Part 11 合规性的判定"(见 part11.py)。

二、离线发射一条审计记录

当状态摘要(digest)已经可用时,可以直接使用安全的 Part11State 引用离线发射记录。文档中的标准用法如下:

from openmed.compliance import Part11AuditEmitter, hash_state

trail = Part11AuditEmitter()
trail.emit(
    actor_id="reviewer-001",
    action="record.update",
    before_state=hash_state("synthetic-before-state", label="pending"),
    after_state=hash_state("synthetic-after-state", label="approved"),
    reason_code="synthetic-review",
    timestamp="2026-08-04T10:00:00Z",
)

assert trail.verify()
trail.write("part11-audit-trail.json")

2.1 hash_state:只保留摘要与标签

hash_state 用于对调用方持有的状态材料做哈希,仅在审计制品中保留摘要与安全标签,原始材料不被该对象持有,也不会进入审计追踪。其实现位于 part11.py:先通过 _state_label 校验标签,再调用 stable_hash({"part11_state": value}) 生成确定性摘要,最终返回一个 Part11State 实例。

def hash_state(value: Any, *, label: str) -> Part11State:
    safe_label = _state_label(label)
    try:
        digest = stable_hash({"part11_state": value})
    except (TypeError, ValueError) as exc:
        raise ValueError("state value could not be converted to a stable hash") from exc
    return Part11State(label=safe_label, hash=digest)

其中 stable_hash 定义在 audit.py:先对数据做规范化 JSON 序列化(sort_keys=True),再计算 SHA-256,因此相同输入永远得到相同摘要,这是记录可重复验证的基础。

2.2 已有摘要时的映射传参

如果应用已经持有摘要,可以直接传入形如 {"label": "approved", "hash": "sha256:<64 lowercase hex digits>"} 的映射。Part11State.from_dict(part11.py)会调用 _reject_unknown_fields 拒绝白名单之外的字段,因此包含 value、text、raw 或其他未提交字段的状态映射会被直接拒绝(ValueError: ... contains unsupported fields)。这一点同样由单元测试覆盖:test_part11.py 验证了含 value 字段的状态映射发射时会抛错。

Part11State 还提供了 state_hash 属性作为 hash 的兼容别名,并支持 from_dict 时以 state_hash 替代 hash 键(两者同时出现且不一致时报错),方便事件形态输入平滑迁移。

2.3 emit 的别名与参数兼容

emit 方法(part11.py)同时注册了 append = emit 与 emit_record = emit 两个别名,并接受 before/after(状态别名)、reason(reason_code 别名)、timestamp/timestamp_utc(时间戳别名,二者不能同时提供)等兼容参数。发射前会先 self._chain.verify(),若底层链已损坏则拒绝追加(cannot append to an invalid audit chain);record_id 未提供时会由哈希自动生成,且要求在同一条 trail 内唯一。

三、记录与链字段语义

每条导出记录包含以下字段(完整定义见 part11.py 的 Part11AuditRecord 与 _RECORD_FIELDS):

字段 含义
record_id 稳定的非 PHI 审计事件标识符。
actor_id 调用方提供的操作者或假名身份引用。
action 被执行的控制性操作。
timestamp_utc 规范化、带时区感知的 UTC 时间戳(统一输出 Z 后缀)。
before_state / after_state 状态 label 加 sha256: hash;不含原始值。
reason_code 该操作的控制性原因。
chain_sequence 对应追加式链条目的序号。
chain_previous_hash 前一条链条目的哈希。
chain_entry_hash 包含该记录载荷的链条目哈希。
record_hash 将记录与链引用绑定的独立哈希。

值得注意的是,timestamp_utc 的规范化逻辑(_normalize_timestamp,part11.py)接受 datetime、带 Z 后缀或 ISO-8601 偏移的字符串,统一转为 UTC,并自动保留微秒精度。不带 UTC 偏移的时间戳会被拒绝,从而杜绝无时区的模糊记录。

3.1 链与导出制品的整体结构

导出的 JSON 制品在记录之上还包含:完整的 chain(含 genesis_hash 锚点与全部链条目)、导出的 records、head_hash、trail_hash 与就绪度对照表(readiness_checklist)。顶层字段集合由 _TRAIL_FIELDS 定义(part11.py),from_dict 会逐一校验 format、version、notice 等字段,格式不符即拒绝加载。

3.2 哈希链底层:HashChainAuditLog

每条记录的链绑定由 openmed.compliance.audit_chain 中的 HashChainAuditLog 提供(audit_chain.py)。它的工作机制是:

  • 首条记录的前驱哈希指向固定的 GENESIS_HASH 锚点(stable_hash({"chain": "openmed.compliance.audit", "sequence": -1}));
  • 每条 AuditRecord 的 record_hash 提交给 sequence + event_type + payload + previous_hash 四元组;
  • verify() 从锚点开始逐条校验序号连续性、前驱哈希一致性与自身哈希,任何中间改动都会导致整条链验证失败。

AuditSink 协议(audit_chain.py)刻意做小,使未来可以无痛替换为共享的防篡改审计链实现而不改动调用方。Part11AuditEmitter.__init__ 支持通过 chain 或 audit_sink 参数注入自定义链,二者不能同时提供。

3.3 全量离线验证

Part11AuditEmitter.verify(part11.py)执行的是全量验证:链链接、每条记录的 record_hash、每条记录与链载荷的逐字段匹配、保留的 head_hash、以及 trail 交叉校验(trail_hash)全部检查。验证完全离线,不依赖任何外部服务。

trail.verify()  # 完整校验链 + 记录 + trail 交叉引用

测试 test_part11.py 用三种篡改场景证明其有效性:改写 record_hash、改写链条目的 payload、改写导出 JSON 中的记录字段,三种情况 verify() 均返回 False。

四、CLI 导出:openmed compliance part11-export

4.1 输入事件格式

创建一个包含安全事件对象的本地 JSON 文件。输入可以是列表,也可以是带 events 数组的对象:

[
  {
    "actor_id": "reviewer-001",
    "action": "record.update",
    "timestamp_utc": "2026-08-04T10:00:00Z",
    "before_state": {
      "label": "pending",
      "hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
    },
    "after_state": {
      "label": "approved",
      "hash": "sha256:1111111111111111111111111111111111111111111111111111111111111111"
    },
    "reason_code": "synthetic-review"
  }
]

事件字段白名单由 _EVENT_FIELDS 定义(part11.py),同时接受 timestamp/timestamp_utc、before/before_state、after/after_state、reason/reason_code 等成对别名,未知字段一律拒绝。

4.2 导出命令

在本地导出:

openmed compliance part11-export events.json \
  --output part11-audit-trail.json

等价的动宾拼写是:

openmed compliance part11 export events.json --output part11-audit-trail.json

CLI 参数定义位于 cli/main.py(两种拼写均注册到同一组参数)与 cli/main.py。支持的选项:

参数 说明
input JSON 文件,包含安全事件对象、events 数组,或一个已存在的 Part 11 trail。
--output / -o 本地审计追踪 JSON 输出路径(必填)。
--overwrite 允许原子替换已存在的输出文件。
--json 输出机器可读的命令结果。

命令处理逻辑(cli/main.py)的关键行为:

  • 若输入是 format == "openmed.part11-audit-trail" 的对象,则按既有 trail 加载并重新验证;否则将输入解析为事件序列;
  • 通过 build_part11_audit_trail(events) 构建追踪,发布前强制调用 trail.verify(),验证失败直接报错(part11_export_failed);
  • 输出采用原子写入(先写临时文件再 os.replace),并支持 --overwrite 语义;
  • 成功结果返回 record_count、head_hash、trail_hash 与 verified: true。

Python 侧的 write 方法同样实现原子写:先写入同目录下带前缀的临时文件,成功后 os.replace 替换目标,失败时清理临时文件(part11.py)。

五、Part 11 就绪度对照表(readiness crosswalk)

机器可读的对照表常量是 openmed.compliance.PART11_READINESS_CHECKLIST(part11.py),同一份对照表会内嵌到每个导出制品的 readiness_checklist 字段中。两个边界状态的含义:

  • partial:发射器提供技术证据,但部署方必须完成该控制项;
  • external:该控制项主要属于组织层面,或明确超出本功能范围。
条款 Emitter 字段映射 边界
11.10(a) record_hash, trail_hash 验证证据为外部责任。
11.10(b) chain, records, record_hash 提供确定性电子副本。
11.10(c) chain_entry_hash, chain_previous_hash, trail_hash 留存与存储控制为外部责任。
11.10(d) actor_id 授权与供给为外部责任。
11.10(e) actor_id, action, timestamp_utc, before_state, after_state, reason_code, chain_entry_hash 发射器主要覆盖范围。
11.10(f) action, reason_code, chain_sequence 工作流排序由调用方负责。
11.10(g) actor_id, record_id 权限检查为外部责任。
11.10(h) actor_id 设备检查为外部责任。
11.10(i) actor_id 培训证据为外部责任。
11.10(j) actor_id, action, reason_code 书面政策为外部责任。
11.10(k) record_hash, trail_hash 文档控制为外部责任。
11.30 record_hash, chain_entry_hash, trail_hash 保密控制归部署方所有。
11.50 actor_id, timestamp_utc, action 电子签名不在范围内。
11.70 record_id, chain_entry_hash 签名链接不在范围内。
11.100 actor_id 身份供给与签名唯一性不在范围内。
11.200 actor_id, record_id 签名组件不在范围内。
11.300 actor_id 凭据生命周期归部署方所有。

Part11ReadinessItem 数据类(part11.py)在构造时会强制校验:clause 与 requirement 非空、emitter_fields 非空、status 只能是 partial 或 external。加载 trail 时若制品内嵌的对照表与当前格式不一致,from_dict 会直接拒绝(readiness checklist does not match this format)。

5.1 对照表的诚实价值

该对照表刻意暴露差距("The crosswalk intentionally makes gaps visible")。有效哈希链只能证明这份制品的完整性,不能证明组织已满足 Part 11 的每项程序性或操作性要求。11.10(e) 是发射器的主要覆盖范围,但即使这一项也标注为 partial——"qualified regulatory review is still required"(仍需合格监管审查)。11.50、11.70、11.100、11.200 等电子签名相关条款则全部明确标注为"out of scope"。

六、与 OpenMed 合规模块家族的关系

openmed.compliance 包(见 init.py 的导出)围绕"PHI 安全的本地合规证据"构建了一整套工具,part11 与其共享同一底层哈希链基础设施:

  • audit_chain.HashChainAuditLog:被 GDPR 访问/擦除工作流与 Part 11 共用,其设计初衷是"记录曾发生导出或预览,而不持久化底层个人数据"(audit_chain.py);
  • hash_state / Part11State / stable_hash:摘要与规范化哈希全部复用 openmed.core.audit 的 _sha256_bytes 与 _canonical_json(audit.py),保证整仓库哈希语义一致;
  • 高层辅助函数 build_part11_audit_trail(别名 export_part11_audit_trail)与 verify_part11_audit_trail 已作为公开 API 导出,便于其他模块直接调用。

这种"一个哈希链、多种合规场景"的架构,使得 Part 11 审计追踪与仓库中其他合规证据(如 Safe Harbor 认证、专家复核证据包)在技术基座上保持一致,均遵循"只记证据、不落 PHI"的同一原则。

七、适用边界与责任清单

最后,明确该功能的适用边界——它解决的是"可信地记录发生了什么事",而非"确保合规":

  • 本功能提供:本地、PHI 安全的审计记录;防篡改的追加式哈希链;可离线全量验证的导出制品;逐条款的就绪度对照表;
  • 本功能不提供:系统验证、访问控制、身份核验、记录留存与备份、人员培训、书面政策、电子签名工作流、身份供给、凭据生命周期管理;
  • 采用组织仍需负责:系统验证(validation)、访问控制、身份验证、留存、备份、培训、书面政策以及合格的监管审查(qualified regulatory review)。

在落地时,建议将导出的 trail 制品纳入组织的备份与留存策略(对应 11.10(c) 的 partial 边界),并保留 CLI 命令输出的 head_hash / trail_hash 作为长期完整性锚点;对涉及电子签名的场景,应另行引入符合 11.50/11.70/11.100/11.200 的签名工作流,本模块不会越界代劳。


延伸阅读:完整实现见 part11.py、audit_chain.py;CLI 参数与处理逻辑见 cli/main.py;验证行为测试见 test_part11.py;哈希基础设施见 audit.py。

登录后查看全文
openmed