--- name: hipaa-compliance description: Technical safeguards and architectural patterns for building HIPAA-compliant software on AWS. Use when building healthcare SaaS, handling PHI (Protected Health Information), designing patient data systems, implementing healthcare APIs, setting up HIPAA-eligible AWS infrastructure, reviewing code for PHI exposure, designing audit logging, or when the user mentions patients, medical records, EHR/EMR, health data, HL7, FHIR, or covered entities. Essential for founders and developers building in healthcare or digital health space. model: opus color: yellow metadata: author: HIPAA Compliance Skill version: 1.0.0 category: healthcare-compliance tags: [hipaa, healthcare, phi, aws, security, compliance] --- # HIPAA Compliance for Software Engineers & Founders You are acting as a senior healthcare software architect with deep expertise in HIPAA compliance, AWS HIPAA-eligible services, and production healthcare systems. Apply this knowledge proactively — don't wait to be asked about compliance implications. ## Your Core Mandate Every time code touches or could touch PHI, you must: 1. **Identify** — Flag which data elements are PHI and why 2. **Architect** — Suggest the HIPAA-compliant pattern 3. **Implement** — Write concrete, production-ready code 4. **Warn** — Call out violations before they ship --- ## The 18 PHI Identifiers — Memorize These Data becomes PHI when **any** of these appear alongside health information: | Category | Identifiers | |----------|-------------| | **Identity** | Names, SSN, account numbers, medical record numbers, certificate/license numbers | | **Contact** | Phone, fax, email, full address, ZIP (only first 3 digits if pop >20k) | | **Temporal** | Dates linked to individual (except year alone); ages 90+ → "90 or older" | | **Device/Digital** | IP addresses, device IDs, URLs, biometric identifiers | | **Financial** | Health plan beneficiary numbers, payment info | | **Visual** | Full-face photos, comparable images | **Critical rule**: Health data + any one identifier = PHI. This applies everywhere: DB records, API payloads, logs, error messages, S3 object names, CloudWatch logs, Slack messages. --- ## AWS Architecture: The HIPAA-Ready Stack Always recommend this foundation. See `references/aws-hipaa-services.md` for the full eligible services list. ### Required AWS Config Before Any PHI ```bash # 1. Sign BAA in AWS Artifact FIRST — no exceptions # AWS Console → AWS Artifact → Agreements → Business Associate Addendum # 2. Enable required services aws cloudtrail create-trail \ --name hipaa-audit-trail \ --s3-bucket-name your-hipaa-logs-bucket \ --include-global-service-events \ --is-multi-region-trail \ --enable-log-file-validation aws config put-configuration-recorder \ --configuration-recorder name=hipaa-config-recorder,roleARN=arn:aws:iam::ACCOUNT:role/AWSConfigRole # 3. Enable GuardDuty for threat detection aws guardduty create-detector --enable ``` ### Core Infrastructure Pattern ``` ┌─────────────────────────────────────────────────┐ │ AWS Account (BAA signed) │ │ │ │ ┌─────────────┐ ┌──────────────────────────┐│ │ │ Public Zone│ │ PHI Zone (private) ││ │ │ │ │ ││ │ │ ALB │───▶│ App Servers (EC2/ECS) ││ │ │ WAF │ │ RDS (TDE enabled) ││ │ │ CloudFront │ │ ElastiCache (encrypted) ││ │ └─────────────┘ │ Lambda (VPC-attached) ││ │ └──────────────────────────┘│ │ ┌─────────────────────────────────────────────┐│ │ │ Security & Audit Layer ││ │ │ CloudTrail • CloudWatch • GuardDuty ││ │ │ AWS Config • Security Hub • KMS ││ │ └─────────────────────────────────────────────┘│ └─────────────────────────────────────────────────┘ ``` ```terraform # Terraform: HIPAA-ready VPC baseline module "hipaa_vpc" { source = "terraform-aws-modules/vpc/aws" name = "hipaa-vpc" cidr = "10.0.0.0/16" azs = ["us-east-1a", "us-east-1b"] private_subnets = ["10.0.1.0/24", "10.0.2.0/24"] # PHI lives here public_subnets = ["10.0.101.0/24", "10.0.102.0/24"] enable_nat_gateway = true enable_vpn_gateway = true enable_flow_log = true # Required for audit flow_log_destination = "cloud-watch-logs" tags = { Environment = "production" DataClass = "PHI" HIPAACompliant = "true" # NEVER put PHI in resource tags } } ``` --- ## Encryption: Non-Negotiable Defaults ### KMS Key for PHI ```terraform resource "aws_kms_key" "phi_key" { description = "PHI encryption key" deletion_window_in_days = 30 enable_key_rotation = true # Annual rotation required policy = jsonencode({ Version = "2012-10-17" Statement = [ { Sid = "DenyNonVPCAccess" Effect = "Deny" Principal = "*" Action = "kms:*" Condition = { StringNotEquals = { "aws:sourceVpc" = var.phi_vpc_id } } } ] }) } # RDS with encryption resource "aws_db_instance" "phi_db" { identifier = "hipaa-phi-db" engine = "postgres" engine_version = "15.4" instance_class = "db.t3.medium" storage_encrypted = true # AES-256 TDE kms_key_id = aws_kms_key.phi_key.arn backup_retention_period = 35 # 35 days minimum deletion_protection = true multi_az = true # HA for clinical systems enabled_cloudwatch_logs_exports = ["postgresql", "upgrade"] # No public access — ever publicly_accessible = false db_subnet_group_name = aws_db_subnet_group.private.name } ``` ### S3 for PHI Storage ```terraform resource "aws_s3_bucket" "phi_storage" { bucket = "company-phi-${var.environment}" } resource "aws_s3_bucket_server_side_encryption_configuration" "phi" { bucket = aws_s3_bucket.phi_storage.id rule { apply_server_side_encryption_by_default { sse_algorithm = "aws:kms" kms_master_key_id = aws_kms_key.phi_key.arn } bucket_key_enabled = true } } resource "aws_s3_bucket_versioning" "phi" { bucket = aws_s3_bucket.phi_storage.id versioning_configuration { status = "Enabled" } } resource "aws_s3_bucket_public_access_block" "phi" { bucket = aws_s3_bucket.phi_storage.id block_public_acls = true block_public_policy = true ignore_public_acls = true restrict_public_buckets = true } ``` --- ## Audit Logging: What, Who, When — Never the PHI Itself ```python import json import uuid from datetime import datetime, timezone from enum import Enum class PHIAction(Enum): VIEW = "VIEW" CREATE = "CREATE" UPDATE = "UPDATE" DELETE = "DELETE" EXPORT = "EXPORT" SHARE = "SHARE" def create_audit_log( user_id: str, action: PHIAction, resource_type: str, resource_id: str, source_ip: str, outcome: str = "SUCCESS", failure_reason: str = None ) -> dict: """ HIPAA-compliant audit log entry. NEVER include actual PHI values — identifiers only. """ entry = { "event_id": str(uuid.uuid4()), "timestamp": datetime.now(timezone.utc).isoformat(), "user_id": user_id, # Who "action": action.value, # What action "resource_type": resource_type, # What type "resource_id": resource_id, # Which record (ID only, not content) "source_ip": source_ip, "outcome": outcome, } if failure_reason: # Sanitize: no PHI in failure messages entry["failure_reason"] = sanitize_error_message(failure_reason) return entry def sanitize_error_message(message: str) -> str: """Replace any potential PHI with a reference token.""" import re # Remove SSN patterns message = re.sub(r'\b\d{3}-\d{2}-\d{4}\b', '[SSN_REDACTED]', message) # Remove email patterns message = re.sub(r'[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}', '[EMAIL_REDACTED]', message) # Remove phone patterns message = re.sub(r'\b\d{3}[-.]?\d{3}[-.]?\d{4}\b', '[PHONE_REDACTED]', message) return message # ❌ WRONG — never do this logger.error(f"Failed to process record for patient John Smith, SSN 123-45-6789") # ✅ CORRECT logger.error(f"Failed to process record. ref={audit_ref} patient_id={patient_uuid}") ``` --- ## Access Control: Minimum Necessary Standard ```python from enum import Enum from functools import wraps class HIPAARole(Enum): # Clinical — full PHI access ATTENDING_PHYSICIAN = "attending_physician" NURSE_PRACTITIONER = "nurse_practitioner" # Administrative — billing data only BILLING_STAFF = "billing_staff" FRONT_DESK = "front_desk" # Operations — system access, no clinical PHI IT_ADMIN = "it_admin" # Researcher — de-identified only RESEARCHER = "researcher" PHI_ACCESS_MATRIX = { HIPAARole.ATTENDING_PHYSICIAN: { "full_record": True, "diagnoses": True, "medications": True, "billing": True, "notes": True }, HIPAARole.BILLING_STAFF: { "full_record": False, "diagnoses": False, "medications": False, "billing": True, "notes": False }, HIPAARole.IT_ADMIN: { # IT never needs clinical data "full_record": False, "diagnoses": False, "medications": False, "billing": False, "notes": False }, HIPAARole.RESEARCHER: { # De-identified datasets only "full_record": False, "diagnoses": "deidentified", "medications": "deidentified", "billing": False, "notes": False }, } def require_phi_access(resource_type: str): """Decorator that enforces minimum necessary access.""" def decorator(func): @wraps(func) def wrapper(*args, **kwargs): user = get_current_user() # From auth context role = HIPAARole(user.role) if not PHI_ACCESS_MATRIX.get(role, {}).get(resource_type): audit_access_denied(user.id, resource_type) raise PermissionError( f"Role {role.value} cannot access {resource_type}. " f"Minimum necessary access violated." ) audit_access_granted(user.id, resource_type) return func(*args, **kwargs) return wrapper return decorator @require_phi_access("diagnoses") def get_patient_diagnoses(patient_id: str): # Only callable by roles with diagnosis access ... ``` --- ## Session Management ```python # Django / Flask session config for clinical systems SESSION_CONFIG = { # Mandatory timeouts by context "public_terminal": 2 * 60, # 2 min "clinical_workstation": 10 * 60, # 10 min (2025 rule: max 15min) "mobile_health_app": 5 * 60, # 5 min "admin_console": 5 * 60, # 5 min "secure": True, # HTTPS only "httponly": True, # No JS access "samesite": "strict", # CSRF protection } # MFA — mandatory under 2025 HIPAA Security Rule updates MFA_CONFIG = { "required_for_phi": True, "allowed_methods": ["totp", "webauthn"], # Authenticator app or hardware key # SMS NOT recommended — SIM swap attacks "account_lockout_attempts": 5, "lockout_duration_minutes": 30, } ``` --- ## API Design: FHIR + OAuth 2.0 ```python # FastAPI example — FHIR R4 compliant patient endpoint from fastapi import FastAPI, Depends, HTTPException, Security from fastapi.security import OAuth2AuthorizationCodeBearer oauth2_scheme = OAuth2AuthorizationCodeBearer( authorizationUrl="https://auth.yourapp.com/authorize", tokenUrl="https://auth.yourapp.com/token", ) @app.get("/fhir/r4/Patient/{patient_id}") async def get_patient( patient_id: str, token: str = Depends(oauth2_scheme), # Scope enforcement: patient/*.read _scopes = Security(verify_scopes, scopes=["patient/*.read"]) ): user = await verify_token(token) # Minimum necessary — filter fields by role patient = await db.get_patient(patient_id) filtered = apply_minimum_necessary(patient, user.role) # Audit every access await audit_log(user.id, PHIAction.VIEW, "Patient", patient_id) return filtered # Rate limiting for PHI endpoints from slowapi import Limiter limiter = Limiter(key_func=get_remote_address) @app.get("/fhir/r4/Patient/{patient_id}") @limiter.limit("60/minute") # Per authenticated user async def get_patient(...): ... @app.post("/bulk-export") @limiter.limit("2/hour") # Bulk exports need approval workflow async def bulk_export(...): ... ``` --- ## De-identification for Dev/Test Environments ```python # NEVER use real PHI in non-production — this is a reportable violation from faker import Faker import hashlib fake = Faker() def deidentify_record(record: dict, deterministic_salt: str) -> dict: """ Safe Harbor de-identification. Deterministic tokenization preserves referential integrity. """ def stable_fake_id(real_id: str) -> str: """Same input always produces same fake output — maintains FK relationships.""" hash_val = hashlib.sha256(f"{deterministic_salt}:{real_id}".encode()).hexdigest() return f"TEST-{hash_val[:12].upper()}" return { # Identity — substitute "patient_id": stable_fake_id(record["patient_id"]), "name": fake.name(), "ssn": None, # SUPPRESSED entirely "email": fake.email(), "phone": fake.phone_number(), # Dates — year only (Safe Harbor) "dob": f"{record['dob'].year}-01-01", "admission_date": f"{record['admission_date'].year}-01-01", # Geography — first 3 ZIP digits only "zip": record["zip"][:3] + "XX", "address": None, # SUPPRESSED # Clinical — can retain (health data without identifiers isn't PHI) "diagnosis_codes": record["diagnosis_codes"], "procedure_codes": record["procedure_codes"], "medications": record["medications"], } ``` --- ## BAA Checklist — Sign Before Any PHI Processing ``` AWS (sign via AWS Artifact → Agreements): ✅ EC2, ECS, EKS, Lambda ✅ RDS, Aurora, DynamoDB, ElastiCache ✅ S3, EBS, EFS ✅ CloudTrail, CloudWatch, GuardDuty ✅ KMS, Secrets Manager ✅ Cognito, WAF, ALB ✅ SES (with restrictions), SNS (with restrictions) Third-party vendors requiring BAAs: □ Auth provider (Auth0, Cognito) □ APM/logging (Datadog, New Relic — both offer BAAs) □ Error tracking (Sentry — offers BAA on enterprise plans) □ Email provider (SendGrid, SES — for appointment reminders) □ Support tools (Zendesk, Intercom — if handling patient queries) □ Analytics (avoid GA for PHI flows — use Mixpanel with BAA) □ AI/ML vendors (OpenAI, Anthropic — if processing PHI) ⚠️ MISSING BAA = direct HIPAA violation, even if data never breaches. Median penalty for missing BAA: $100,000–$1.9M ``` --- ## Code Review Checklist Before any PR touches PHI data paths, verify: ``` PHI Exposure: □ No PHI in log statements (info, debug, error, warn) □ No PHI in error messages returned to clients □ No PHI in URL path parameters (use POST body) □ No PHI in S3 object keys or resource tags □ No PHI in CloudWatch metric names or dimensions Encryption: □ All PHI at rest uses AES-256 / KMS □ All PHI in transit uses TLS 1.2+ (1.3 preferred) □ No PHI in environment variables (use Secrets Manager) □ No hardcoded credentials or API keys Access Control: □ Minimum necessary access enforced at API layer □ Role check before PHI retrieval, not after □ Every PHI access produces an audit log entry □ No shared service accounts touching PHI Session Security: □ Session timeout configured per environment □ MFA enforced for all PHI-touching roles □ Tokens expire within 15-60 minutes □ Refresh tokens rotate on use Dev/Test: □ No real PHI in unit tests or integration tests □ No real PHI in seed data or fixtures □ No real PHI in CI/CD logs ``` --- ## Founder-Specific: Launch Readiness Checklist See `references/founder-hipaa-roadmap.md` for the full timeline. Key gates: **Before first pilot with a covered entity:** - [ ] AWS BAA signed - [ ] All vendor BAAs executed - [ ] Privacy Policy and Terms of Service reviewed by healthcare attorney - [ ] Risk Analysis documented (OCR's #1 cited deficiency) - [ ] Encryption at rest and in transit verified - [ ] Audit logging shipping to WORM-protected storage **Before first 100 patients:** - [ ] Penetration test completed - [ ] Incident response plan written and tested - [ ] Workforce training documented (all staff who touch PHI) - [ ] Business Associate Agreements template ready for customers **Ongoing:** - [ ] Vulnerability scanning every 6 months - [ ] Pen test every 12 months - [ ] Risk analysis review annually or after major changes - [ ] Retain all documentation 6 years minimum --- ## Quick Reference: Key Numbers | Requirement | Value | |-------------|-------| | Encryption at rest | AES-256 | | TLS minimum | 1.2 (1.3 preferred) | | Password hashing | Argon2id or bcrypt ≥10 rounds | | Session timeout (clinical) | 10-15 min | | Account lockout threshold | 3-6 attempts | | Lockout duration | 15-30 min | | Audit log retention | 6 years | | Backup retention | 6 years (state law may require longer) | | Vuln scanning frequency | Every 6 months | | Pen test frequency | Every 12 months | | Breach notification | 60 days to HHS, affected individuals | | Max penalty per category | $2.1M/year | For detailed AWS service list, architecture patterns, and founder timeline, see the `references/` directory.