437 lines
15 KiB
Markdown
437 lines
15 KiB
Markdown
# HIPAA医疗合规检测工具
|
||
|
||
`HIPAA` `医疗数据安全` `PHI检测` `合规审计` `HL7 FHIR`
|
||
|
||
# HIPAA Guardian
|
||
|
||
**面向 Claude、Cursor、Windsurf 及 AI Agent 的 AI 驱动 HIPAA 合规、PHI/PII 检测和医疗数据安全技能集。**
|
||
|
||
HIPAA Guardian 是专为医疗从业者、开发者及构建 HIPAA 合规系统的组织设计的专项技能集合，提供以下自动化工具：
|
||
- 🔍 **检测受保护健康信息（PHI）** - 覆盖全部 18 项 HIPAA 标识符
|
||
- ✅ **验证医疗数据格式** - HL7 FHIR、HL7 v2、CDA、X12 EDI
|
||
- 📋 **审计日志** - 符合 45 CFR §164.312(b) 的不可篡改合规审计记录
|
||
- 🛡️ **风险评估** - 数据泄露风险评分及修复指导
|
||
- 🔐 **合规映射** - HIPAA、NIST CSF 2.0、HITRUST 对齐
|
||
|
||
## ⚠️ 合规声明
|
||
|
||
- ✅ **HIPAA 就绪**：专为 HIPAA BAA（业务伙伴协议）环境设计
|
||
- ✅ **审计跟踪**：支持符合 45 CFR §164.312(b) 的不可篡改日志
|
||
- ✅ **标准集成**：对齐 HL7 FHIR R5、NIST CSF 2.0、HITRUST CSF
|
||
- ✅ **开源**：MIT 许可证，安全优先的代码审查流程
|
||
|
||
> **注意**：本技能集旨在支持 HIPAA 合规，但不保证达成 HIPAA 合规。在生产环境中使用前，请咨询您的法律和合规团队，并与任何服务提供商签订业务伙伴协议（BAA）。
|
||
|
||
## 工作原理
|
||
|
||
### PHI 检测流程
|
||
|
||
```
|
||
输入文件/代码
|
||
↓
|
||
模式匹配（18 项 HIPAA 标识符）
|
||
↓
|
||
置信度评分（0-100%）
|
||
↓
|
||
风险评估
|
||
↓
|
||
HIPAA 规则映射
|
||
↓
|
||
报告生成 + 修复建议
|
||
```
|
||
|
||
### 可检测的内容
|
||
|
||
| 标识符 | 示例 | 风险等级 |
|
||
|--------|------|----------|
|
||
| **姓名** | 患者、医疗提供者、家属 | 高 |
|
||
| **社会安全号（SSN）** | 社会安全号码 | 极高 |
|
||
| **病历号（MRN）** | 医疗记录编号 | 极高 |
|
||
| **出生日期（DOB）** | 出生日期、入院日期 | 高 |
|
||
| **电话/传真** | 所有格式均可检测 | 中 |
|
||
| **电子邮件** | 医疗相关邮箱地址 | 中 |
|
||
| **地址** | 街道、城市、邮编 | 中 |
|
||
| **医保ID** | 保险、保单号码 | 高 |
|
||
| **生物特征** | 照片、指纹、声纹 | 极高 |
|
||
| **设备ID** | 序列号、UDI 码 | 中 |
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
# 安装所有 HIPAA Guardian 技能
|
||
npx skills add 1Mangesh1/hipaa-guardian
|
||
|
||
# 安装指定技能
|
||
npx skills add 1Mangesh1/hipaa-guardian --skill hipaa-guardian
|
||
```
|
||
|
||
## 快速入门
|
||
|
||
### 1. 扫描代码中的 PHI 泄露
|
||
|
||
```bash
|
||
# 让 Claude/Copilot 扫描代码库
|
||
"扫描我们的后端代码，查找硬编码的 PHI，如患者姓名、SSN 或 MRN"
|
||
|
||
# 输出：详细发现报告，包含：
|
||
# - 文件位置
|
||
# - 行号
|
||
# - 风险评分
|
||
# - 修复步骤
|
||
```
|
||
|
||
**发现示例：**
|
||
```json
|
||
{
|
||
"file": "database/seeders/PatientSeeder.js",
|
||
"line": 42,
|
||
"finding": "检测到 SSN：123-45-6789",
|
||
"identifier_type": "ssn",
|
||
"risk_score": 95,
|
||
"severity": "极高",
|
||
"remediation": [
|
||
"从种子文件中移除硬编码的 SSN",
|
||
"改用 faker.js 或测试数据库",
|
||
"使用环境变量管理测试凭据"
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2. 验证医疗数据
|
||
|
||
```bash
|
||
# 验证 FHIR 患者资源
|
||
"检查此 FHIR 资源是否存在 PHI 暴露和合规问题"
|
||
|
||
{
|
||
"resourceType": "Patient",
|
||
"id": "pat-123",
|
||
"identifier": [{"value": "MRN-2024-001"}],
|
||
"name": [{"given": ["John"], "family": "Doe"}],
|
||
"birthDate": "1985-01-15"
|
||
}
|
||
|
||
# 返回：✓ FHIR R5 结构有效，✓ 所有 PHI 已正确识别
|
||
```
|
||
|
||
### 3. 生成审计日志
|
||
|
||
```bash
|
||
# 记录医疗数据访问以满足 HIPAA 合规要求
|
||
"创建用户查看患者病历的审计日志"
|
||
|
||
# 生成合规条目，包含：
|
||
# - 唯一审计ID
|
||
# - 精确时间戳
|
||
# - 用户标识
|
||
# - 执行操作
|
||
# - 访问资源
|
||
# - 成功/失败状态
|
||
```
|
||
|
||
### 4. 生成合规报告
|
||
|
||
```bash
|
||
# 全面 HIPAA 合规评估
|
||
"对我们的代码库进行 HIPAA 合规审计并生成报告"
|
||
|
||
# 生成综合报告：
|
||
# - 执行摘要
|
||
# - 按严重程度分类的发现
|
||
# - HIPAA 规则映射
|
||
# - 风险评估
|
||
# - 修复操作手册
|
||
```
|
||
|
||
## 可用技能
|
||
|
||
| 技能 | 用途 | 激活触发词 | 版本 |
|
||
|------|------|-----------|------|
|
||
| [hipaa-guardian](./skills/hipaa-guardian/) | PHI/PII 检测、医疗格式验证、审计日志 | "扫描 PHI"、"HIPAA 合规"、"检测 PII"、"医疗数据安全" | 1.2.0 |
|
||
| [fhir-hl7-validator](./skills/fhir-hl7-validator/) | HL7 FHIR R5 & HL7 v2 验证 | "验证 FHIR"、"检查 HL7 消息"、"医疗格式" | 1.0.0 |
|
||
| [healthcare-audit-logger](./skills/healthcare-audit-logger/) | HIPAA 合规审计跟踪日志 | "审计日志"、"合规日志"、"跟踪医疗访问" | 1.0.0 |
|
||
|
||
### [hipaa-guardian](./skills/hipaa-guardian/) 核心功能
|
||
|
||
#### PHI 检测引擎
|
||
- **18 项 HIPAA 安全港标识符**：姓名、SSN、MRN、出生日期、电话、邮箱、地址、IP、生物特征等
|
||
- **置信度评分**：0-100% 匹配置信度，结合模式分析
|
||
- **风险评估**：基于敏感度与暴露程度的自动风险评分
|
||
- **文件类型支持**：JSON、CSV、XML、SQL、Python、JavaScript、YAML、FHIR、HL7、CDA
|
||
- **智能模式**：熵检测、格式验证、跨字段分析
|
||
|
||
#### 医疗格式支持
|
||
```
|
||
HL7 FHIR R5 → Patient、Condition、Observation、MedicationRequest
|
||
HL7 v2.x → MSH、PID、DG1、OBX、RXO 段
|
||
CDA/C-CDA → 临床文档、patientRole 元素
|
||
X12 EDI → 医疗理赔（837、835 格式）
|
||
```
|
||
|
||
#### 代码安全扫描
|
||
```
|
||
✓ 源代码（所有语言）
|
||
✓ 注释和文档
|
||
✓ 测试固件和模拟数据
|
||
✓ 配置文件（.env、secrets）
|
||
✓ 数据库种子文件和迁移脚本
|
||
✓ API 响应示例
|
||
```
|
||
|
||
#### 合规功能
|
||
- **HIPAA 规则映射**：每条发现关联具体法规章节
|
||
- **泄露风险评分**：0-100 风险评分，含严重程度分级（极高→低）
|
||
- **去识别化验证**：验证数据移除是否符合 HIPAA 标准
|
||
- **审计跟踪生成**：符合 45 CFR §164.312(b) 的合规日志
|
||
- **修复指导**：附带代码示例的分步修复说明
|
||
|
||
#### 集成支持
|
||
- **Claude/Copilot/Windsurf**：通过技能触发词激活
|
||
- **GitHub Actions**：CI/CD 流水线集成
|
||
- **预提交钩子**：代码提交前自动扫描
|
||
- **VS Code 插件**：编码时实时检测 PHI
|
||
- **OpenAPI 3.1**：供第三方集成的 REST API
|
||
|
||
### [fhir-hl7-validator](./skills/fhir-hl7-validator/)
|
||
|
||
按 HL7 标准验证医疗数据：
|
||
- **FHIR R5 Schema 验证** - Patient、Condition、Observation 资源
|
||
- **HL7 v2 消息解析** - 完整的 v2.x 段验证
|
||
- **CDA 文档结构** - 临床文档架构合规性
|
||
- **自定义验证规则** - 领域特定约束
|
||
|
||
### [healthcare-audit-logger](./skills/healthcare-audit-logger/)
|
||
|
||
HIPAA 合规审计跟踪日志：
|
||
- **不可篡改日志** - 防篡改的审计记录
|
||
- **完整上下文** - 用户、操作、资源、时间戳、结果
|
||
- **访问控制日志** - 记录谁在何时访问了什么
|
||
- **事件分类** - CREATE、READ、UPDATE、DELETE、EXPORT 事件
|
||
- **留存管理** - 可配置的日志留存策略
|
||
|
||
## 真实使用场景
|
||
|
||
### 1. 代码审查 - 检测硬编码的患者数据
|
||
|
||
**场景**：医疗初创公司构建患者门户后端
|
||
|
||
```bash
|
||
# PR 审查期间扫描代码，防止意外提交 PHI
|
||
"审查此 PR 是否含有硬编码的患者数据"
|
||
|
||
# 发现：
|
||
// ❌ 极高风险：database/seeders/PatientSeeder.js:42
|
||
const mockPatient = {
|
||
name: "John Doe", // 高风险：患者姓名
|
||
ssn: "123-45-6789", // 极高风险：SSN
|
||
mrn: "MRN-2024-001", // 极高风险：MRN
|
||
dob: "01/15/1985", // 高风险：出生日期
|
||
};
|
||
|
||
// ✅ 修复方案：改用 faker.js
|
||
const faker = require('faker');
|
||
const mockPatient = {
|
||
name: faker.name.fullName(),
|
||
ssn: faker.datatype.string(11),
|
||
mrn: `MRN-${faker.datatype.uuid()}`,
|
||
dob: faker.date.past(),
|
||
};
|
||
```
|
||
|
||
### 2. 数据库安全审计 - 暴露的患者记录
|
||
|
||
**场景**：医院通过日志发现潜在数据泄露
|
||
|
||
```bash
|
||
# 扫描应用日志中的 PHI 暴露
|
||
"检查我们的日志中是否含有不应出现的患者数据"
|
||
|
||
# 发现：
|
||
❌ application.log:2024-02-07T10:15:33Z
|
||
ERROR：患者 John Doe（SSN：123-45-6789）查询失败
|
||
|
||
✅ 修复方案：
|
||
1. 从日志中移除具体标识信息
|
||
2. 对敏感数据进行哈希或脱敏处理
|
||
3. 使用患者ID代替姓名
|
||
4. 实施日志过滤策略
|
||
|
||
// 正确的日志记录方式：
|
||
logger.error(`患者查询失败：${patient.id}`);
|
||
// 禁止记录：姓名、SSN、出生日期、MRN
|
||
```
|
||
|
||
### 3. FHIR API 验证 - 医疗数据交换
|
||
|
||
**场景**：构建符合 HL7 FHIR 规范的患者 API
|
||
|
||
```bash
|
||
# 在返回客户端之前验证 FHIR 资源
|
||
"检查此患者响应的 PHI 安全性和 FHIR 合规性"
|
||
|
||
// API 响应 - 自动检查：
|
||
{
|
||
"resourceType": "Patient",
|
||
"id": "pat-12345", // ✓ 仅安全ID
|
||
"identifier": [...], // ✓ 病历号
|
||
"name": [{"given": [...]}], // ✓ 患者姓名（预期字段）
|
||
"telecom": [...], // ✓ 电话/邮箱
|
||
"birthDate": "1985-01-15", // ✓ 出生日期（医疗场景预期字段）
|
||
"address": [...] // ✓ 地址数据
|
||
}
|
||
|
||
✓ FHIR R5 Patient 有效
|
||
✓ 所有字段适用于医疗场景
|
||
✓ PHI 为预期且必要字段
|
||
✓ 可安全传输至授权客户端
|
||
```
|
||
|
||
### 4. 合规审计 - 满足 HIPAA 要求
|
||
|
||
**场景**：医疗 SaaS 公司的年度 HIPAA 审计
|
||
|
||
```bash
|
||
# 生成完整合规报告
|
||
"对我们的整个代码库进行全面的 HIPAA 合规检查"
|
||
|
||
# 生成报告：
|
||
├── 执行摘要
|
||
│ ├── 整体风险：中等
|
||
│ ├── 极高风险发现：3 项
|
||
│ ├── 高风险发现：12 项
|
||
│ └── 预计修复时间：约 16 小时
|
||
├── 按类别分类的发现
|
||
│ ├── 代码安全（12 项问题）
|
||
│ ├── 配置（5 项问题）
|
||
│ ├── 测试数据（8 项问题）
|
||
│ └── 文档（3 项问题）
|
||
├── HIPAA 规则映射
|
||
│ ├── 45 CFR §164.308（管理保障措施）
|
||
│ ├── 45 CFR §164.312（技术保障措施）
|
||
│ └── 45 CFR §164.504（业务伙伴要求）
|
||
└── 修复操作手册
|
||
├── 优先级 1：极高风险修复（3 项）
|
||
├── 优先级 2：高风险项（12 项）
|
||
└── 时间表和责任人分配
|
||
```
|
||
|
||
## 法规参考
|
||
|
||
### HIPAA 规则（45 CFR）
|
||
- **隐私规则（§164.500+）**：患者权利、使用与披露、PHI 保护
|
||
- **安全规则（§164.300+）**：行政、物理和技术保障措施
|
||
- **泄露通知规则（§164.400+）**：通知要求与文档记录
|
||
|
||
### 医疗标准
|
||
- **[HL7 FHIR R5](https://www.hl7.org/fhir/R5/)**：国际医疗数据交换标准
|
||
- **[NIST 网络安全框架 2.0](https://www.nist.gov/cyberframework)**：治理、风险管理、检测/响应功能
|
||
- **[NIST SP 800-66](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-66r1.pdf)**：HIPAA 安全实施指南
|
||
- **[NIST SP 800-188](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-188.pdf)**：个人信息去识别化
|
||
|
||
### 外部资源
|
||
- **[HHS HIPAA 指南](https://www.hhs.gov/hipaa)**：HIPAA 合规官方门户
|
||
- **[OCR 执法](https://www.hhs.gov/hipaa/for-professionals/special-topics/enforcement)**：HIPAA 违规及纠正行动计划
|
||
- **[HITRUST CSF](https://hitrustalliance.net/csf/)**：经认证的 HIPAA 合规框架
|
||
|
||
## 贡献
|
||
|
||
欢迎贡献！可改进的方向：
|
||
- 新增医疗数据格式支持
|
||
- 补充 HIPAA 规则映射
|
||
- 改进预提交钩子
|
||
- 优化特定语言的模式识别
|
||
|
||
具体贡献指南请参阅 `./skills/*/` 目录下各技能的文档。
|
||
|
||
## 文档
|
||
|
||
### 核心参考
|
||
- **[references/HIPAA-OVERVIEW.md](./references/HIPAA-OVERVIEW.md)** - 完整 HIPAA 规则参考
|
||
- **[references/HL7-FHIR-R5.md](./references/HL7-FHIR-R5.md)** - FHIR 资源规范
|
||
- **[references/NIST-CSF-2.0.md](./references/NIST-CSF-2.0.md)** - 网络安全框架
|
||
- **[references/HEALTHCARE-DATA-TYPES.md](./references/HEALTHCARE-DATA-TYPES.md)** - 医疗数据格式
|
||
|
||
### 技能文档
|
||
- **[skills/hipaa-guardian/](./skills/hipaa-guardian/)** - 核心 PHI 检测技能
|
||
- **[skills/fhir-hl7-validator/](./skills/fhir-hl7-validator/)** - 医疗格式验证
|
||
- **[skills/healthcare-audit-logger/](./skills/healthcare-audit-logger/)** - 审计日志
|
||
|
||
## 快速参考 - 激活短语
|
||
|
||
在 Claude、Cursor 或 Windsurf 中使用以下短语激活 HIPAA Guardian 技能：
|
||
|
||
### hipaa-guardian 技能
|
||
- "扫描 PHI" / "检测 PII"
|
||
- "HIPAA 合规检查" / "HIPAA 审计"
|
||
- "医疗数据安全" / "检查代码中的 PHI 泄露"
|
||
- "扫描日志中的 PHI" / "检查 PHI 端点的身份验证"
|
||
- "生成 HIPAA 审计报告" / "查找敏感医疗数据"
|
||
|
||
### fhir-hl7-validator 技能
|
||
- "验证 FHIR 资源" / "检查 HL7 消息"
|
||
- "医疗格式验证"
|
||
- "验证 FHIR R5" / "检查 HL7 v2"
|
||
|
||
### healthcare-audit-logger 技能
|
||
- "创建审计日志" / "合规日志"
|
||
- "跟踪医疗访问" / "审计跟踪"
|
||
|
||
## 常见问题
|
||
|
||
**Q：可以在生产环境中使用吗？**
|
||
A：本技能集旨在支持合规工作。请务必进行独立的安全审查，咨询您的法律/合规团队，并与外部服务提供商签订业务伙伴协议（BAA）。
|
||
|
||
**Q：能检测所有 PHI 吗？**
|
||
A：可以高置信度检测 18 项 HIPAA 安全港标识符。但部分依赖上下文的 PHI 可能需要人工审查。请始终将自动化检测与人工审查结合使用。
|
||
|
||
**Q：如何处理误报？**
|
||
A：每条发现均提供置信度评分（0-100%）。低置信度发现可能为误报，请结合上下文审查所有发现。
|
||
|
||
**Q：可以集成到 CI/CD 吗？**
|
||
A：可以！请查看 [skills/hipaa-guardian/](./skills/hipaa-guardian/) 中的 GitHub Actions、预提交钩子及自定义集成示例。
|
||
|
||
**Q：如何报告安全问题？**
|
||
A：请通过私信方式报告安全漏洞（请勿为安全问题创建公开的 GitHub Issue）。
|
||
|
||
## 故障排除
|
||
|
||
### 检测未找到预期的 PHI
|
||
|
||
1. **检查置信度阈值** - 可能过滤了低置信度匹配
|
||
2. **验证模式匹配** - 某些格式存在变体（如 SSN：123-45-6789 与 123456789）
|
||
3. **上下文很重要** - 测试数据可能已被有意去识别化
|
||
|
||
### 大型代码库扫描速度慢
|
||
|
||
1. **排除不必要的目录** - `.git`、`node_modules`、`dist`、`build`
|
||
2. **按文件类型过滤** - 聚焦相关文件（代码、配置，非二进制文件）
|
||
3. **批量扫描** - 将目录拆分为较小块分批处理
|
||
|
||
### 修复指导不清晰
|
||
|
||
1. **查看具体示例** - 参考技能示例了解最佳实践
|
||
2. **查阅参考文档** - [references/](./references/) 包含详细指南
|
||
3. **寻求帮助** - 针对具体使用场景创建 Issue
|
||
|
||
## 支持
|
||
|
||
- 📖 **文档**：[./references/](./references/) - 详细指南
|
||
- 🐛 **问题/功能请求**：[GitHub Issues](https://github.com/1Mangesh1/hipaa-guardian/issues)
|
||
- 🔒 **安全报告**：请负责任地报告漏洞（请勿创建公开 Issue）
|
||
- 💬 **讨论**：[GitHub Discussions](https://github.com/1Mangesh1/hipaa-guardian/discussions)
|
||
|
||
## 许可证
|
||
|
||
MIT 许可证 - 详见 [LICENSE.txt](./LICENSE.txt)
|
||
|
||
**权限**：✓ 商业使用 | ✓ 修改 | ✓ 分发 | ✓ 私人使用
|
||
**条件**：⚠️ 需保留许可证和版权声明
|
||
**限制**：✗ 不提供担保 | ✗ 不承担责任
|
||
|
||
---
|
||
|
||
**仓库**：[1Mangesh1/hipaa-guardian](https://github.com/1Mangesh1/hipaa-guardian)
|
||
**最后更新**：2026 年 2 月
|
||
**状态**：✅ 积极开发中
|
||
**最新版本**：1.2.0
|
||
**许可证**：MIT |