OpenMed HIPAA Safe Harbor Attestation基于审计报告离线生成 18 类标识符合规证据【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmedOpenMed 的 Safe Harbor Attestation 特性把一次去标识化运行的审计报告转化为覆盖 HIPAA Safe Harbor 全部 18 类标识符的 PHI 安全证据制品它只汇总类别元数据、聚合计数、配置的策略动作与哈希绝不复制源文本、跨度偏移、替代值surrogate、上下文或检测器证据。本文基于 docs/compliance/hipaa-safe-harbor-attestation.md 展开结合openmed包内的实现源码与测试用例讲解如何离线生成、解读与校验该证据制品以及 18 类标识符与 OpenMed 规范标签canonical label的映射关系与残余风险语义。读完本文你将掌握openmed deid --auditopenmed compliance safe-harbor的完整取证链路理解source_report_hash/attestation_hash的可复现性设计并能准确判断哪些类别需要合格专家qualified expert复核。一、定位与边界证据制品而非法律认证1.1 它在合规链条中的位置OpenMed 把「去标识化执行」与「合规证据生成」拆成两步先在本机用审计模式运行去标识化得到审计报告audit report再基于该报告生成 Safe Harbor 证明。其核心实现位于 openmed/compliance/safe_harbor.py模块文档明确写道The generator ... deliberately emits only canonical category metadata, aggregate counts, policy actions, and hashes. Source text, span offsets, context, surrogates, and detector evidence are never copied into the attestation.也就是说从设计层面就保证了「证明」本身不携带原始 PHI 字段——即便审计报告被扩散Safe Harbor 证明文件也不会泄漏任何原始文本片段。1.2 明确的免责边界生成物是一次运行的证据evidence from one run而不是一项认证certification法律签署文件legal sign-off对 Safe Harbor「实际知情」actual knowledge评估的替代品。这一点在 safe_harbor.py 中以常量SAFE_HARBOR_ATTESTATION_NOTICE固化并作为notice字段写入每个制品This report is evidence from one OpenMed run, not a certification or legal sign-off. Residual-risk items require qualified expert review.二、离线生成两步命令行流程2.1 第一步生成带审计的去标识化报告在本地对note.txt执行去标识化并携带--audit输出审计报告openmed deid \ --input note.txt \ --output run-audit.json \ --policy hipaa_safe_harbor \ --audit--policy hipaa_safe_harbor指定去标识化姿态posture为hipaa_safe_harbor_deidentification。对应的策略文件位于 openmed/core/policies/hipaa_safe_harbor.json其默认动作为maskpolicy_label_actions中DIRECT_IDENTIFIER、QUASI_IDENTIFIER、SENSITIVE_ATTRIBUTE、CLINICAL_CONCEPT四类全部为mask且safety_sweep_mandatory: truekeep_mapping: false——即默认不保留任何映射。--audit会生成包含spans、policy、repro_hash等字段的审计报告AuditReport详见 openmed/core/audit.py每个 span 记录canonical_label或label、action、位置与表面文本等。2.2 第二步离线生成 Safe Harbor 证明openmed compliance safe-harbor run-audit.json \ --output safe-harbor-attestation.json该命令由 openmed/cli/main.py 注册compliance safe-harbor接收审计报告 JSON 路径作为位置参数report并提供--output/-o指定输出路径。处理函数_handle_compliance_safe_harbormain.py依次完成加载审计报告_load_audit_report调用generate_safe_harbor_attestation(report)生成证明若未指定--output将证明 JSON 打印到标准输出否则写入文件并在终端回显输出路径与attestation_hash。关键约束该命令完全在本地运行不发起任何网络请求。它只做纯函数式转换——读取 JSON、做类别映射与计数、算哈希、写 JSON。2.3 输出形式与机器可读封装省略--output将 JSON 制品直接打印到标准输出便于管道处理或人工查看。追加--json把标准输出包装进 OpenMed 统一的机器可读命令信封envelope证明本体位于其data字段。测试 tests/unit/compliance/test_safe_harbor.py 验证了--json模式下payload[command] compliance safe-harbor且payload[data][report_type] hipaa_safe_harbor_attestation。2.4 输入完整性校验命令会拒绝可复现性哈希repro_hash与内容不再匹配的审计报告。校验逻辑在 safe_harbor.py 的_source_report_hash若报告缺少repro_hash则退回对完整载荷计算稳定哈希若repro_hash存在但不符合^sha256:[0-9a-f]{64}$格式直接报错否则调用verify_repro_hash或对象自身的repro_hash_matches做内容完整性核验不匹配即抛出ValueError(audit report reproducibility hash does not match)。repro_hash的复算与校验实现见 openmed/core/audit.py按排序后的 span 序列重新计算哈希并与存储值比对从而发现审计报告在生成后被篡改或损坏的情况。三、报告内容与字段结构3.1 顶层字段证明制品包含以下字段对应 safe_harbor.py 的_payload与to_dict字段含义schema_version证明 schema 版本当前为1report_type固定为hipaa_safe_harbor_attestationsource_report_hash将证据绑定到来源审计运行的哈希格式sha256:...policy去标识化策略名hipaa_safe_harborsummary汇总category_count恒为 18、detection_count、residual_risk_category_count、requires_expert_determinationcategories恰好 18 条有序类别记录notice免责声明文本attestation_hash对证明载荷不含自身计算得到的稳定哈希使生成物独立可复现3.2 类别记录Category Record每条类别记录由SafeHarborCategoryAttestationsafe_harbor.py序列化而来{ ordinal: 1, category: NAME, name: Names, mapped_labels: [FIRST_NAME, LAST_NAME, MIDDLE_NAME, PERSON, PREFIX], policy_actions: {FIRST_NAME: mask, LAST_NAME: mask, MIDDLE_NAME: mask, PERSON: mask, PREFIX: mask}, detection_count: 2, applied_action_counts: {mask: 2}, residual_risk: false, residual_risk_reason: null }ordinal类别在 18 项中的序号1–18顺序由SAFE_HARBOR_CATEGORY_ORDER常量固化不依赖集合frozenset的无序性safe_harbor.pymapped_labels映射到该类别的规范标签按字典序排序保证确定性输出policy_actions每个映射标签在该策略下配置的动作detection_count/applied_action_counts该类别下的聚合检测数与实际执行动作分布residual_risk/residual_risk_reason是否需要合格专家复核及原因。3.3 绝不包含的内容报告永远不包含原始 span 文本raw span text、偏移量offsets、上下文、替换值、替代值surrogates或逐检测器证据。测试test_attestation_serialization_contains_no_raw_phitests/unit/compliance/test_safe_harbor.py直接断言渲染后的 JSON 中不含任何合成姓名、合成传真号、surrogate与context字样。存放建议尽管 OpenMed 审计报告设计为 PHI-safe仍应按照部署环境的相应控制级别来存储和处理来源审计报告本文档原文明确要求如此。四、18 类标识符与规范标签的覆盖映射4.1 映射的单一事实来源映射关系定义于 openmed/core/labels.py 的LABEL_TO_HIPAA因此证明始终与规范的标签策略主干label policy spine保持一致。18 个 HIPAA 类别常量HIPAA_NAME等定义于同一文件labels.py并通过HIPAA_SAFE_HARBOR_CLASSES冻结集合约束。safe_harbor.py在导入时调用_validate_category_table()safe_harbor.py强制要求类别总数必须为 18、与HIPAA_SAFE_HARBOR_CLASSES完全一致、类别名表完整——任何漂移都会在导入期直接抛RuntimeError。4.2 完整映射表Safe Harbor 类别规范标签覆盖NamesPERSON,FIRST_NAME,LAST_NAME,MIDDLE_NAME,PREFIXGeographic subdivisionsLOCATION,STREET_ADDRESS,BUILDING_NUMBER,ZIPCODE,GPS_COORDINATES,ORDINAL_DIRECTIONDate elements and ages over 89DATE,DATE_OF_BIRTH,TIME,AGETelephone numbersPHONEFax numbers无专用规范映射Email addressesEMAILSocial Security numbersSSNMedical record numbers无专用规范映射Health plan beneficiary numbers无专用规范映射Account numbers账户与金融标识符标签由规范跨映射cross-map映射而来Certificate and license numbers无专用规范映射Vehicle identifiers and serial numbersVIN,VEHICLE_REGISTRATIONDevice identifiers and serial numbersMAC_ADDRESS,IMEIWeb URLsURLIP addressesIP_ADDRESSBiometric identifiers无专用规范映射Full-face photographs and comparable images无专用规范映射Other unique identifying numbers or codes其余标签由规范跨映射映射到UNIQUE_IDENTIFIER补充细节来自LABEL_TO_HIPAA源码USERNAME、ID_NUM、PASSWORD、PIN、API_KEY、GENDER、ETHNICITY、ORGANIZATION、JOB_TITLE、MICROORGANISM、ANTIBIOTIC、CONDITION、MEDICATION、LAB_TEST、PROCEDURE以及临床概念类标签均映射到UNIQUE_IDENTIFIER金融类标签中CREDIT_CARD、CVV、IBAN、BIC、BITCOIN_ADDRESS、ETHEREUM_ADDRESS、LITECOIN_ADDRESS、MASKED_NUMBER映射到ACCOUNT_NUMBER账户类CREDIT_CARD_ISSUER、AMOUNT、CURRENCY映射到UNIQUE_IDENTIFIER技术类标签中IP_ADDRESS映射到IP_ADDRESSUSER_AGENT映射到UNIQUE_IDENTIFIER。4.3 无映射类别的残余风险语义没有任何规范标签映射的类别传真号、病历号、健康计划受益人编号、证书与执照编号、生物特征标识符、全脸照片等总是被标记为残余风险项要求合格专家复核。_category_attestationsafe_harbor.py在mapped_labels为空时写入原因No canonical OpenMed labels map to this category; qualified expert review is required.对应测试test_uncovered_categories_are_residual_risk_itemstests/unit/compliance/test_safe_harbor.py验证无映射类别集合非空requires_expert_determination为True且每个无映射类别记录的residual_risk_reason都包含 expert review。4.4 专门化 span 生产者的类别细化专门化的 span 生产者可以通过以下任一方式把检测计数更精确地归属到某个类别在 span 顶层字段提供合法的hipaa_safe_harbor_class或safe_harbor_class标签在 span 的evidence或metadata容器中提供上述键在regulatory_tags中提供 Safe Harbor 类别。解析逻辑见_explicit_span_categorysafe_harbor.py按 span 本体 →evidence→metadata的顺序查找_EXPLICIT_CATEGORY_KEYS即hipaa_safe_harbor_class/safe_harbor_class再回退扫描regulatory_tags若提供的值不在HIPAA_SAFE_HARBOR_CLASSES中则报错。典型场景测试_audit_report()tests/unit/compliance/test_safe_harbor.py构造了一个labelPHONE但携带safe_harbor_classFAX_NUMBER的 span——传真没有专用规范标签但专门化检测器可以用该标签把计数精确归入FAX_NUMBER类别。注意这样的标签不会把本无覆盖的类别变成规范的检测器覆盖——该类别仍保持residual_risk: true残余风险标志依然可见。4.5keep动作触发残余风险即使某类别已被规范标签覆盖只要该类别下任何一次实际检测使用了keep动作报告也会将该类别标记为残余风险safe_harbor.pyOne or more detections used the keep action; qualified expert review is required.测试test_keep_action_adds_residual_risk_to_a_covered_categorytests/unit/compliance/test_safe_harbor.py用{canonical_label: EMAIL, action: keep}验证了EMAIL_ADDRESS类别因此变为residual_risk: true。这是因为keep意味着原文被保留属于 Safe Harbor 框架下需要专家判断的高风险情形。五、生成算法与底层实现原理5.1 生成主流程generate_safe_harbor_attestationsafe_harbor.py的执行步骤输入校验审计报告须为 mapping 或暴露to_dict()spans必须是可迭代对象报告必须声明policy。策略校验通过load_policy(policy_name)加载策略若profile.name ! hipaa_safe_harbor则抛ValueError——证明只能基于该策略的审计报告生成。哈希绑定计算/校验source_report_hash。逐 span 聚合对每个 span解析canonical_label或label并规范化确定类别显式类别标签优先否则回退LABEL_TO_HIPAA读取action缺失时回退到策略为该标签配置的默认动作动作必须是ACTION_VALUES来自 openmed/core/schemas/span.py之一。随后累加detection_counts[category]与action_counts[category][action]。生成 18 条有序类别记录并用Counter统计结果填充。序列化to_json()使用allow_nanFalse、ensure_asciiTrue、sort_keysTrue、缩进 2输出确定性 JSONsafe_harbor.py。5.2 两个哈希的语义source_report_hash对来源审计报告载荷计算稳定哈希stable_hash或直接沿用报告自带的repro_hash需通过完整性校验从而把证明「绑定」到特定一次运行——防止张冠李戴。attestation_hash对证明自身的_payload()不含attestation_hash字段计算稳定哈希使同一输入在任何环境、任何时间生成的文件完全一致、可独立复现。两个哈希均以sha256:前缀 64 位十六进制呈现正则^sha256:[0-9a-f]{64}$。stable_hash的实现见 openmed/core/audit.py对规范化 JSONcanonical JSON做 UTF-8 编码后计算 SHA-256——规范化是关键它保证键序、转义等细节不会破坏跨环境的一致性。5.3 类别序号的确定性SAFE_HARBOR_CATEGORY_ORDER采用显式 tuple 而非集合推导模块注释特别说明「The regulatory order is meaningful and must not depend on frozenset ordering」safe_harbor.py。这意味着 18 条类别记录的输出顺序是稳定、可预期的便于下游程序按ordinal对齐不同批次的证据。六、测试保障与可验证性测试文件 tests/unit/compliance/test_safe_harbor.py 提供了完整的验证矩阵测试验证点test_category_mapping_enumerates_all_18_core_classes类别顺序恰为 18 项且SAFE_HARBOR_CATEGORY_ORDER、HIPAA_SAFE_HARBOR_CLASSES、SAFE_HARBOR_CATEGORY_LABELS三者集合一致反向配对与LABEL_TO_HIPAA完全相等test_attestation_reports_counts_actions_and_policy_mapping检测计数、动作分布与策略动作映射正确如NAME类别detection_count 2、applied_action_counts {mask: 2}test_uncovered_categories_are_residual_risk_items无映射类别全部进入residual_risk_categoriestest_attestation_serialization_contains_no_raw_phi序列化结果不含任何原始 PHI 文本、surrogate、context哈希以sha256:开头test_attestation_rejects_untrusted_action_text未知动作直接抛ValueError且错误信息不泄漏不可信文本test_keep_action_adds_residual_risk_to_a_covered_categorykeep动作使已覆盖类别标记残余风险test_cli_emits_attestation_offline端到端 CLI 流程compliance safe-harbor audit.json --output ...正常写盘--json相关测试机器可读信封中command与data.report_type正确此外策略层面的回归由 openmed/eval/suites/policy_compliance.py 与tests/unit/compliance/test_policy_coverage.py覆盖build_policy_coverage_matrix(policies(hipaa_safe_harbor,))从「策略覆盖矩阵」维度保证该策略下的行为一致性。七、读取与消费建议7.1 如何快速判断一次运行是否需要专家介入直接看summary字段{ category_count: 18, detection_count: 42, residual_risk_category_count: 6, requires_expert_determination: true }requires_expert_determination为true只要存在任意残余风险类别时说明该次运行的证据不能单独作为「达到 Safe Harbor 标准」的结论必须结合合格专家的复核意见residual_risk_category_count与residual_risk_categories可精确定位需要关注的类别。7.2 常见排查路径若residual_risk_reason为「No canonical OpenMed labels map to this category」说明该类别没有规范标签覆盖属于结构性缺口需要专门的 span 生产者通过hipaa_safe_harbor_class/safe_harbor_class/regulatory_tags细化归属或由专家另行评估若「One or more detections used the keep action」检查对应类别的applied_action_counts中keep的计数回溯策略配置如 hipaa_safe_harbor.json 中相关标签的 action或运行参数若 CLI 报reproducibility hash does not match审计报告已被修改或损坏重新运行openmed deid --audit生成新报告。7.3 与相邻合规工具的关系openmed compliance子命令还包含其他合规证据工具21 CFR Part 11 审计追踪导出、专家复核证据报告、证明核验等注册于 openmed/cli/main.py可结合 docs/compliance/21-cfr-part-11-audit-trail.md、docs/compliance/audit-envelopes.md、docs/compliance/artifact-lineage.md 等文档构建更完整的合规证据链。策略与运行时行为可进一步参考 openmed/core/policy.py 与 openmed/core/pii.py。八、小结OpenMed 的 Safe Harbor Attestation 是一套「本地化、PHI-safe、可复现」的合规证据生成机制它把去标识化审计报告压缩为恰好 18 条有序类别记录只保留规范标签映射、策略动作、聚合计数与双重哈希并通过导入期校验、确定性序列化与完整的单元测试保证输出的稳定与可信。对工程师而言它提供了可审计、可复现、可编程消费的证据文件对合规流程而言它清晰划定了「机器证据」与「专家判定」的边界——凡是无规范标签覆盖的类别以及任何使用keep动作的检测都会以residual_risk标志明确提醒需要合格专家复核。【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenMed HIPAA Safe Harbor Attestation：基于审计报告离线生成 18 类标识符合规证据
OpenMed HIPAA Safe Harbor Attestation基于审计报告离线生成 18 类标识符合规证据【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmedOpenMed 的 Safe Harbor Attestation 特性把一次去标识化运行的审计报告转化为覆盖 HIPAA Safe Harbor 全部 18 类标识符的 PHI 安全证据制品它只汇总类别元数据、聚合计数、配置的策略动作与哈希绝不复制源文本、跨度偏移、替代值surrogate、上下文或检测器证据。本文基于 docs/compliance/hipaa-safe-harbor-attestation.md 展开结合openmed包内的实现源码与测试用例讲解如何离线生成、解读与校验该证据制品以及 18 类标识符与 OpenMed 规范标签canonical label的映射关系与残余风险语义。读完本文你将掌握openmed deid --auditopenmed compliance safe-harbor的完整取证链路理解source_report_hash/attestation_hash的可复现性设计并能准确判断哪些类别需要合格专家qualified expert复核。一、定位与边界证据制品而非法律认证1.1 它在合规链条中的位置OpenMed 把「去标识化执行」与「合规证据生成」拆成两步先在本机用审计模式运行去标识化得到审计报告audit report再基于该报告生成 Safe Harbor 证明。其核心实现位于 openmed/compliance/safe_harbor.py模块文档明确写道The generator ... deliberately emits only canonical category metadata, aggregate counts, policy actions, and hashes. Source text, span offsets, context, surrogates, and detector evidence are never copied into the attestation.也就是说从设计层面就保证了「证明」本身不携带原始 PHI 字段——即便审计报告被扩散Safe Harbor 证明文件也不会泄漏任何原始文本片段。1.2 明确的免责边界生成物是一次运行的证据evidence from one run而不是一项认证certification法律签署文件legal sign-off对 Safe Harbor「实际知情」actual knowledge评估的替代品。这一点在 safe_harbor.py 中以常量SAFE_HARBOR_ATTESTATION_NOTICE固化并作为notice字段写入每个制品This report is evidence from one OpenMed run, not a certification or legal sign-off. Residual-risk items require qualified expert review.二、离线生成两步命令行流程2.1 第一步生成带审计的去标识化报告在本地对note.txt执行去标识化并携带--audit输出审计报告openmed deid \ --input note.txt \ --output run-audit.json \ --policy hipaa_safe_harbor \ --audit--policy hipaa_safe_harbor指定去标识化姿态posture为hipaa_safe_harbor_deidentification。对应的策略文件位于 openmed/core/policies/hipaa_safe_harbor.json其默认动作为maskpolicy_label_actions中DIRECT_IDENTIFIER、QUASI_IDENTIFIER、SENSITIVE_ATTRIBUTE、CLINICAL_CONCEPT四类全部为mask且safety_sweep_mandatory: truekeep_mapping: false——即默认不保留任何映射。--audit会生成包含spans、policy、repro_hash等字段的审计报告AuditReport详见 openmed/core/audit.py每个 span 记录canonical_label或label、action、位置与表面文本等。2.2 第二步离线生成 Safe Harbor 证明openmed compliance safe-harbor run-audit.json \ --output safe-harbor-attestation.json该命令由 openmed/cli/main.py 注册compliance safe-harbor接收审计报告 JSON 路径作为位置参数report并提供--output/-o指定输出路径。处理函数_handle_compliance_safe_harbormain.py依次完成加载审计报告_load_audit_report调用generate_safe_harbor_attestation(report)生成证明若未指定--output将证明 JSON 打印到标准输出否则写入文件并在终端回显输出路径与attestation_hash。关键约束该命令完全在本地运行不发起任何网络请求。它只做纯函数式转换——读取 JSON、做类别映射与计数、算哈希、写 JSON。2.3 输出形式与机器可读封装省略--output将 JSON 制品直接打印到标准输出便于管道处理或人工查看。追加--json把标准输出包装进 OpenMed 统一的机器可读命令信封envelope证明本体位于其data字段。测试 tests/unit/compliance/test_safe_harbor.py 验证了--json模式下payload[command] compliance safe-harbor且payload[data][report_type] hipaa_safe_harbor_attestation。2.4 输入完整性校验命令会拒绝可复现性哈希repro_hash与内容不再匹配的审计报告。校验逻辑在 safe_harbor.py 的_source_report_hash若报告缺少repro_hash则退回对完整载荷计算稳定哈希若repro_hash存在但不符合^sha256:[0-9a-f]{64}$格式直接报错否则调用verify_repro_hash或对象自身的repro_hash_matches做内容完整性核验不匹配即抛出ValueError(audit report reproducibility hash does not match)。repro_hash的复算与校验实现见 openmed/core/audit.py按排序后的 span 序列重新计算哈希并与存储值比对从而发现审计报告在生成后被篡改或损坏的情况。三、报告内容与字段结构3.1 顶层字段证明制品包含以下字段对应 safe_harbor.py 的_payload与to_dict字段含义schema_version证明 schema 版本当前为1report_type固定为hipaa_safe_harbor_attestationsource_report_hash将证据绑定到来源审计运行的哈希格式sha256:...policy去标识化策略名hipaa_safe_harborsummary汇总category_count恒为 18、detection_count、residual_risk_category_count、requires_expert_determinationcategories恰好 18 条有序类别记录notice免责声明文本attestation_hash对证明载荷不含自身计算得到的稳定哈希使生成物独立可复现3.2 类别记录Category Record每条类别记录由SafeHarborCategoryAttestationsafe_harbor.py序列化而来{ ordinal: 1, category: NAME, name: Names, mapped_labels: [FIRST_NAME, LAST_NAME, MIDDLE_NAME, PERSON, PREFIX], policy_actions: {FIRST_NAME: mask, LAST_NAME: mask, MIDDLE_NAME: mask, PERSON: mask, PREFIX: mask}, detection_count: 2, applied_action_counts: {mask: 2}, residual_risk: false, residual_risk_reason: null }ordinal类别在 18 项中的序号1–18顺序由SAFE_HARBOR_CATEGORY_ORDER常量固化不依赖集合frozenset的无序性safe_harbor.pymapped_labels映射到该类别的规范标签按字典序排序保证确定性输出policy_actions每个映射标签在该策略下配置的动作detection_count/applied_action_counts该类别下的聚合检测数与实际执行动作分布residual_risk/residual_risk_reason是否需要合格专家复核及原因。3.3 绝不包含的内容报告永远不包含原始 span 文本raw span text、偏移量offsets、上下文、替换值、替代值surrogates或逐检测器证据。测试test_attestation_serialization_contains_no_raw_phitests/unit/compliance/test_safe_harbor.py直接断言渲染后的 JSON 中不含任何合成姓名、合成传真号、surrogate与context字样。存放建议尽管 OpenMed 审计报告设计为 PHI-safe仍应按照部署环境的相应控制级别来存储和处理来源审计报告本文档原文明确要求如此。四、18 类标识符与规范标签的覆盖映射4.1 映射的单一事实来源映射关系定义于 openmed/core/labels.py 的LABEL_TO_HIPAA因此证明始终与规范的标签策略主干label policy spine保持一致。18 个 HIPAA 类别常量HIPAA_NAME等定义于同一文件labels.py并通过HIPAA_SAFE_HARBOR_CLASSES冻结集合约束。safe_harbor.py在导入时调用_validate_category_table()safe_harbor.py强制要求类别总数必须为 18、与HIPAA_SAFE_HARBOR_CLASSES完全一致、类别名表完整——任何漂移都会在导入期直接抛RuntimeError。4.2 完整映射表Safe Harbor 类别规范标签覆盖NamesPERSON,FIRST_NAME,LAST_NAME,MIDDLE_NAME,PREFIXGeographic subdivisionsLOCATION,STREET_ADDRESS,BUILDING_NUMBER,ZIPCODE,GPS_COORDINATES,ORDINAL_DIRECTIONDate elements and ages over 89DATE,DATE_OF_BIRTH,TIME,AGETelephone numbersPHONEFax numbers无专用规范映射Email addressesEMAILSocial Security numbersSSNMedical record numbers无专用规范映射Health plan beneficiary numbers无专用规范映射Account numbers账户与金融标识符标签由规范跨映射cross-map映射而来Certificate and license numbers无专用规范映射Vehicle identifiers and serial numbersVIN,VEHICLE_REGISTRATIONDevice identifiers and serial numbersMAC_ADDRESS,IMEIWeb URLsURLIP addressesIP_ADDRESSBiometric identifiers无专用规范映射Full-face photographs and comparable images无专用规范映射Other unique identifying numbers or codes其余标签由规范跨映射映射到UNIQUE_IDENTIFIER补充细节来自LABEL_TO_HIPAA源码USERNAME、ID_NUM、PASSWORD、PIN、API_KEY、GENDER、ETHNICITY、ORGANIZATION、JOB_TITLE、MICROORGANISM、ANTIBIOTIC、CONDITION、MEDICATION、LAB_TEST、PROCEDURE以及临床概念类标签均映射到UNIQUE_IDENTIFIER金融类标签中CREDIT_CARD、CVV、IBAN、BIC、BITCOIN_ADDRESS、ETHEREUM_ADDRESS、LITECOIN_ADDRESS、MASKED_NUMBER映射到ACCOUNT_NUMBER账户类CREDIT_CARD_ISSUER、AMOUNT、CURRENCY映射到UNIQUE_IDENTIFIER技术类标签中IP_ADDRESS映射到IP_ADDRESSUSER_AGENT映射到UNIQUE_IDENTIFIER。4.3 无映射类别的残余风险语义没有任何规范标签映射的类别传真号、病历号、健康计划受益人编号、证书与执照编号、生物特征标识符、全脸照片等总是被标记为残余风险项要求合格专家复核。_category_attestationsafe_harbor.py在mapped_labels为空时写入原因No canonical OpenMed labels map to this category; qualified expert review is required.对应测试test_uncovered_categories_are_residual_risk_itemstests/unit/compliance/test_safe_harbor.py验证无映射类别集合非空requires_expert_determination为True且每个无映射类别记录的residual_risk_reason都包含 expert review。4.4 专门化 span 生产者的类别细化专门化的 span 生产者可以通过以下任一方式把检测计数更精确地归属到某个类别在 span 顶层字段提供合法的hipaa_safe_harbor_class或safe_harbor_class标签在 span 的evidence或metadata容器中提供上述键在regulatory_tags中提供 Safe Harbor 类别。解析逻辑见_explicit_span_categorysafe_harbor.py按 span 本体 →evidence→metadata的顺序查找_EXPLICIT_CATEGORY_KEYS即hipaa_safe_harbor_class/safe_harbor_class再回退扫描regulatory_tags若提供的值不在HIPAA_SAFE_HARBOR_CLASSES中则报错。典型场景测试_audit_report()tests/unit/compliance/test_safe_harbor.py构造了一个labelPHONE但携带safe_harbor_classFAX_NUMBER的 span——传真没有专用规范标签但专门化检测器可以用该标签把计数精确归入FAX_NUMBER类别。注意这样的标签不会把本无覆盖的类别变成规范的检测器覆盖——该类别仍保持residual_risk: true残余风险标志依然可见。4.5keep动作触发残余风险即使某类别已被规范标签覆盖只要该类别下任何一次实际检测使用了keep动作报告也会将该类别标记为残余风险safe_harbor.pyOne or more detections used the keep action; qualified expert review is required.测试test_keep_action_adds_residual_risk_to_a_covered_categorytests/unit/compliance/test_safe_harbor.py用{canonical_label: EMAIL, action: keep}验证了EMAIL_ADDRESS类别因此变为residual_risk: true。这是因为keep意味着原文被保留属于 Safe Harbor 框架下需要专家判断的高风险情形。五、生成算法与底层实现原理5.1 生成主流程generate_safe_harbor_attestationsafe_harbor.py的执行步骤输入校验审计报告须为 mapping 或暴露to_dict()spans必须是可迭代对象报告必须声明policy。策略校验通过load_policy(policy_name)加载策略若profile.name ! hipaa_safe_harbor则抛ValueError——证明只能基于该策略的审计报告生成。哈希绑定计算/校验source_report_hash。逐 span 聚合对每个 span解析canonical_label或label并规范化确定类别显式类别标签优先否则回退LABEL_TO_HIPAA读取action缺失时回退到策略为该标签配置的默认动作动作必须是ACTION_VALUES来自 openmed/core/schemas/span.py之一。随后累加detection_counts[category]与action_counts[category][action]。生成 18 条有序类别记录并用Counter统计结果填充。序列化to_json()使用allow_nanFalse、ensure_asciiTrue、sort_keysTrue、缩进 2输出确定性 JSONsafe_harbor.py。5.2 两个哈希的语义source_report_hash对来源审计报告载荷计算稳定哈希stable_hash或直接沿用报告自带的repro_hash需通过完整性校验从而把证明「绑定」到特定一次运行——防止张冠李戴。attestation_hash对证明自身的_payload()不含attestation_hash字段计算稳定哈希使同一输入在任何环境、任何时间生成的文件完全一致、可独立复现。两个哈希均以sha256:前缀 64 位十六进制呈现正则^sha256:[0-9a-f]{64}$。stable_hash的实现见 openmed/core/audit.py对规范化 JSONcanonical JSON做 UTF-8 编码后计算 SHA-256——规范化是关键它保证键序、转义等细节不会破坏跨环境的一致性。5.3 类别序号的确定性SAFE_HARBOR_CATEGORY_ORDER采用显式 tuple 而非集合推导模块注释特别说明「The regulatory order is meaningful and must not depend on frozenset ordering」safe_harbor.py。这意味着 18 条类别记录的输出顺序是稳定、可预期的便于下游程序按ordinal对齐不同批次的证据。六、测试保障与可验证性测试文件 tests/unit/compliance/test_safe_harbor.py 提供了完整的验证矩阵测试验证点test_category_mapping_enumerates_all_18_core_classes类别顺序恰为 18 项且SAFE_HARBOR_CATEGORY_ORDER、HIPAA_SAFE_HARBOR_CLASSES、SAFE_HARBOR_CATEGORY_LABELS三者集合一致反向配对与LABEL_TO_HIPAA完全相等test_attestation_reports_counts_actions_and_policy_mapping检测计数、动作分布与策略动作映射正确如NAME类别detection_count 2、applied_action_counts {mask: 2}test_uncovered_categories_are_residual_risk_items无映射类别全部进入residual_risk_categoriestest_attestation_serialization_contains_no_raw_phi序列化结果不含任何原始 PHI 文本、surrogate、context哈希以sha256:开头test_attestation_rejects_untrusted_action_text未知动作直接抛ValueError且错误信息不泄漏不可信文本test_keep_action_adds_residual_risk_to_a_covered_categorykeep动作使已覆盖类别标记残余风险test_cli_emits_attestation_offline端到端 CLI 流程compliance safe-harbor audit.json --output ...正常写盘--json相关测试机器可读信封中command与data.report_type正确此外策略层面的回归由 openmed/eval/suites/policy_compliance.py 与tests/unit/compliance/test_policy_coverage.py覆盖build_policy_coverage_matrix(policies(hipaa_safe_harbor,))从「策略覆盖矩阵」维度保证该策略下的行为一致性。七、读取与消费建议7.1 如何快速判断一次运行是否需要专家介入直接看summary字段{ category_count: 18, detection_count: 42, residual_risk_category_count: 6, requires_expert_determination: true }requires_expert_determination为true只要存在任意残余风险类别时说明该次运行的证据不能单独作为「达到 Safe Harbor 标准」的结论必须结合合格专家的复核意见residual_risk_category_count与residual_risk_categories可精确定位需要关注的类别。7.2 常见排查路径若residual_risk_reason为「No canonical OpenMed labels map to this category」说明该类别没有规范标签覆盖属于结构性缺口需要专门的 span 生产者通过hipaa_safe_harbor_class/safe_harbor_class/regulatory_tags细化归属或由专家另行评估若「One or more detections used the keep action」检查对应类别的applied_action_counts中keep的计数回溯策略配置如 hipaa_safe_harbor.json 中相关标签的 action或运行参数若 CLI 报reproducibility hash does not match审计报告已被修改或损坏重新运行openmed deid --audit生成新报告。7.3 与相邻合规工具的关系openmed compliance子命令还包含其他合规证据工具21 CFR Part 11 审计追踪导出、专家复核证据报告、证明核验等注册于 openmed/cli/main.py可结合 docs/compliance/21-cfr-part-11-audit-trail.md、docs/compliance/audit-envelopes.md、docs/compliance/artifact-lineage.md 等文档构建更完整的合规证据链。策略与运行时行为可进一步参考 openmed/core/policy.py 与 openmed/core/pii.py。八、小结OpenMed 的 Safe Harbor Attestation 是一套「本地化、PHI-safe、可复现」的合规证据生成机制它把去标识化审计报告压缩为恰好 18 条有序类别记录只保留规范标签映射、策略动作、聚合计数与双重哈希并通过导入期校验、确定性序列化与完整的单元测试保证输出的稳定与可信。对工程师而言它提供了可审计、可复现、可编程消费的证据文件对合规流程而言它清晰划定了「机器证据」与「专家判定」的边界——凡是无规范标签覆盖的类别以及任何使用keep动作的检测都会以residual_risk标志明确提醒需要合格专家复核。【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考