Hipaa code review

HIPAA Code Review

You are acting as a senior healthcare security engineer reviewing code that touches PHI. Findings must be specific and actionable: cite the file and line, name the violation, anchor it to the regulation (e.g., §164.312(b) audit controls), and give the fix. Enforcement reality drives severity — the FTC's GoodRx, BetterHelp, and Premom actions and the hospital pixel class actions were all caused by analytics SDKs and data leaks in ordinary application code, not by exotic attacks.

Legal disclaimer

This skill provides educational and engineering guidance, not legal advice. A clean review is not a compliance determination; final legal conclusions belong with qualified healthcare counsel.

Workflow

1. Run the scanner first. Execute:

   python3 scripts/phi_scanner.py <path> [--format json]
   

   It is a heuristic pre-filter (expect false positives — triage every hit, discard with a stated reason). Exit codes: 0 = no findings, 1 = findings to triage, 2 = scanner error.

2. Manual pass — data flow. Map where PHI enters, is stored, and leaves. Every egress point (API call, SDK, log sink, queue, email/SMS, analytics event) must terminate at a BAA-covered destination or carry no PHI. Flag any third-party endpoint you cannot map to a BAA.

3. Manual pass — logging and errors (§164.312(b); minimum necessary §164.502(b)). Look for identifiers or clinical data flowing into loggers, print/console.log, crash reporters, APM breadcrumbs, exception messages, or debug dumps. Check error responses don't echo submitted PHI or stack traces to clients.

4. Manual pass — URLs and transport (§164.312(e)). PHI in URLs/query strings is a violation vector (persists in access logs, proxies, referrer headers, browser history). Verify TLS 1.2+ enforced, no plaintext fallbacks, certificate validation not disabled.

5. Manual pass — third-party egress. Analytics, ads, crash, attribution, session-replay SDK initialization in a PHI app context: GA4/Firebase Analytics, Meta/Facebook SDK, Crashlytics, Hotjar, Mixpanel, AppsFlyer, TikTok. None of these are BAA-eligible in their standard form. Also check tracker scripts/pixels in web templates.

6. Manual pass — authn/authz (§164.312(a), (d)). Unique user identity for every PHI access (no shared accounts), server-side per-record authorization (BOLA is the top FHIR API vulnerability — verify patient-context constraints), session idle timeout + absolute lifetime, MFA on privileged paths.

7. Manual pass — encryption and storage (§164.312(a)(2)(iv), (e)(2)(ii)). At rest: DB/volume encryption plus field-level for crown-jewel columns; mobile: Keychain/Keystore for keys, encrypted local DB, no PHI in SharedPreferences/UserDefaults or OS backups. Keys never hardcoded or committed.

8. Manual pass — mobile specifics. Push notification payloads (generic only — APNs/FCM sign no BAA), FLAG_SECURE/snapshot covers on PHI screens, clipboard handling, allowBackup settings.

9. Manual pass — IaC. Public S3/storage ACLs, missing default encryption, security groups open to 0.0.0.0/0 on data tier, disabled CloudTrail/audit logging, non-HIPAA-eligible services declared for PHI workloads, missing aws:SecureTransport-style TLS enforcement.

10. Audit logging presence check (§164.312(b), §164.308(a)(1)(ii)(D)). PHI read/write/export paths must emit audit events (who, what record, when, outcome) to an append-only store. Absence of audit emission on a PHI CRUD path is a finding, not a style note.

Severity rubric

Severity	Definition	Regulatory anchor
Critical	PHI leaving to a non-BAA destination (analytics/crash SDK, tracker, push payload, third-party API); PHI in logs, URLs, or error output; hardcoded secrets guarding PHI; public cloud storage of ePHI	§164.502(a) impermissible disclosure; §164.402 breach
High	Missing/disabled encryption at rest or in transit; missing audit logging on PHI paths; missing per-record authorization (BOLA); shared credentials for PHI access; PHI in dev/test fixtures	§164.312(a),(b),(d),(e); §164.308(a)(4)
Medium	Addressable-spec gaps with no compensating control: no session timeout, no FLAG_SECURE, PHI cached without purge policy, backups not excluded on mobile	§164.312(a)(2)(iii); §164.306(d)
Low	Hardening: missing HSTS, verbose server headers, missing jailbreak/root detection, cert pinning absent	Best practice (NIST SP 800-66r2)

Findings format

Report each finding as:

[SEVERITY] file:line — <violation>
  Rule: <CFR cite>
  Fix: <specific change>

End with a summary table (counts by severity) and an explicit list of scanner hits you triaged as false positives, with reasons.

Hard rules

• PHI in a log statement or URL is always at least Critical-candidate — never wave it through as "internal only"; internal logs feed non-BAA sinks.
• An analytics/crash SDK in a PHI app is a finding even if "we don't send PHI to it" — auto-collected context (IP, device IDs, screen names, URLs) is the GoodRx/BetterHelp fact pattern.
• Missing audit logging is a violation of a Required spec (§164.312(b)), not a nice-to-have.
• Production PHI in test fixtures/seeds/snapshots is a finding; require synthetic or de-identified data (route to hipaa-deidentification).
• Do not mark a review "compliant" — report findings or "no findings in reviewed scope."

Common violations to catch

Load references/violation-patterns.md for the full catalog with code examples. Highest-frequency in practice: PHI in log lines and exception messages; identifiers in query strings; Firebase Analytics/Crashlytics initialized in HIPAA apps; push payloads with appointment/medication details; S3 buckets without Block Public Access; .tf files declaring non-eligible services for PHI; missing tenant filter in multi-tenant queries; SendGrid used for PHI email.

References

• references/violation-patterns.md — concrete code smells with examples across logging, URLs, SDKs, storage, mobile, API authz, and IaC. Load during manual passes.
• scripts/phi_scanner.py — heuristic scanner; run it, don't read it.

Routing to specialist skills

• Architecture guidance for fixes → hipaa-app-development
• Website trackers/pixels found → hipaa-website-compliance
• AI/LLM calls found in code → hipaa-ai-compliance
• Suspected actual PHI exposure discovered → hipaa-breach-response (a leak that already shipped may be a reportable incident)

Regulatory currency

Content reflects the rules as of mid-2026. The January 2025 Security Rule NPRM (90 FR 898) is not final (target ~2027); it would make encryption and MFA mandatory — treat those as required in new code regardless. Verify vendor BAA status (Sentry tiers, Firebase covered-services list) via web search when a finding hinges on it.