Scan a codebase for HIPAA compliance issues using pattern-matching heuristics. Detects PHI exposure in logs, missing audit trails, unencrypted transmission/storage, hardcoded patient data, access control gaps, and missing Business Associate Agreement references. Read-only — never modifies files.
Regulation basis: 45 CFR Parts 160, 162, 164 (HIPAA Administrative Simplification, as amended through March 26, 2013). Covers Security Rule (§164.302-318), Privacy Rule (§164.500-534), Breach Notification Rule (§164.400-414), and enforcement penalties (§160.400-426).
Usage
/hipaa-validate # Scan full project (developer mode — definitives only)
/hipaa-validate src/ # Scan specific path
/hipaa-validate --mode compliance # Full audit sweep including heuristic categories
/hipaa-validate --severity high # Filter to HIGH findings only
/hipaa-validate --keywords member,enrollee # Extend healthcare keyword list
/hipaa-validate --output json # Structured JSON output for CI integration
Modes:
developer (default): Categories 1, 3, 4, 7, 8 — definitive regex matches only, low false-positive rate, suited for daily use
compliance: All 8 categories — includes heuristic checks (Cat 2, 5, 6) for audit sweep coverage, suited for pre-audit sweeps
Severity filtering:--severity high shows only HIGH findings, --severity warn shows HIGH + WARN. Default shows all.
What This Command Does
Run scanner script — execute scripts/hipaa_scan.py with passed arguments
Interpret results — analyze findings, add context, suggest specific fixes
Report — present findings with file paths, line numbers, severity, confidence, and HIPAA rule citations
Steps
Step 1: Run the Scanner Script
Execute the Python scanner with the user's arguments:
.hipaaignore support — honors exclusion patterns from project root
.hipaa-config support — reads covered_vendors for BAA checks
If the script reports "No healthcare context detected", relay the message and suggest the --keywords flag with alternative terminology.
If --output json is used, the script outputs structured JSON suitable for CI pipelines. The exit code is 1 if any HIGH findings exist, 0 otherwise.
Step 2: Interpret and Enrich Results
For each finding from the script output:
Read the flagged file and line to understand the actual code context
Add a specific fix suggestion — not generic advice, but concrete code changes based on what you see
For heuristic findings (confidence: "heuristic"), check if the concern is actually addressed elsewhere in the codebase (e.g., auth middleware at router level, audit logging in a shared module)
Mark confirmed false positives and suggest adding them to .hipaaignore
Scanner Reference
The script implements the following scan categories. This reference is provided so you can explain findings to the user and verify edge cases.
Language coverage note: JS/TS and Python patterns are the most comprehensive. Go, Ruby, and Java have baseline coverage for common log patterns. Contributions for additional language-specific patterns are welcome.
Minimum Necessary violations (§164.502(b)):
Pattern
Severity
Language
Description
res\.(json|send)\(.*patient without field projection
WARN
JS/TS
Full patient object in API response
return.*patient in route handler without field selection
CRUD operations on patient resources without audit keywords in same file
HIGH
POTENTIAL gap: all PHI access must be logged
Admin operations without audit trail reference
WARN
POTENTIAL gap: administrative actions need recording
Bulk data operations (export, download, bulk, batch) on PHI resources without audit keywords in same file
HIGH
POTENTIAL gap: mass PHI access must be tracked
Note: This category uses co-occurrence heuristics — checking whether PHI route keywords and audit keywords appear in the same file. False positives are expected when audit logging is handled by middleware or a separate call chain. Use .hipaaignore to suppress confirmed false positives.
Note: Auth middleware is commonly applied at router-level or app-level. The co-occurrence heuristic checks the same file only. False positives expected when auth is configured globally. Use .hipaaignore to suppress.
See: reference/hipaa-rules.md §164.312(a)(1) and §164.312(d) for access control and authentication requirements.
Detects temporary file creation in PHI-adjacent code without secure deletion. Per §164.310(d)(2)(iii), media containing PHI must be sanitized before reuse or disposal.
Pattern
Severity
Description
/tmp/ or tempfile\. or os\.tmpdir\(\) or Path\.GetTempPath in PHI-adjacent code
WARN
§164.310(d)(2)(iii) — Temp files with PHI must be securely deleted
mktemp or NamedTemporaryFile or createTempFile near PHI keywords
WARN
Verify temp files are cleaned up after use
Cache directory writes (cache/, .cache, Cache.set) with PHI keywords
WARN
Cached PHI must be encrypted or purged on schedule
heuristic — Categories 2, 5, 6: co-occurrence/absence check, may be false positive
This distinction helps compliance officers prioritize immediate remediation (definitive) vs. investigation (heuristic).
Rules
MUST remain read-only — never modify any file. This skill reports findings only.
MUST cite a specific HIPAA rule section (§ number) for every finding — uncited findings are not actionable
MUST run the healthcare keyword context gate before applying PHI identifier regex (Category 4) — without it, false-positive rate is ~90%
NEVER label a heuristic finding as "definitive" — clearly mark POTENTIAL and confidence: heuristic
NEVER scan binary files, lock files (*.lock, package-lock.json, yarn.lock, pnpm-lock.yaml), or vendored dirs (node_modules/, vendor/, .git/, dist/, build/, out/, .next/) — noise and zero signal
CRITICAL: respect .hipaaignore exclusion patterns — teams use it to mark known-safe data fixtures
MANDATORY: flag PHI-adjacent config files without .env or secret-manager references as a WARN category, even when no PHI pattern matches
NEVER auto-fix in this version. Auto-fixing requires project-specific knowledge of logging and audit infrastructure that regex alone cannot provide.
Gotchas
Test fixtures and seed data often contain synthetic PHI that looks real (SSN-shaped IDs, formatted phone numbers, sample email addresses). Flag them but lower severity — production code handling the same patterns is the actual risk.
HIPAA §164.312(b) requires audit logging but does not specify a format. "Logs exist" is not evidence of compliance — the logs must capture WHO (authenticated user), WHAT (action), WHEN (timestamp), WHERE (resource), and they must be immutable (append-only or write-once storage).
Encryption-at-rest varies silently by storage layer. RDS auto-encrypts new volumes since 2017, but older DB snapshots may not be; S3 bucket policies can override instance-level encryption. Treat "encryption enabled" as a claim to verify with the cloud provider, not a state to trust.
PHI identifiers 1-18 differ from HIPAA's "limited data set" rules — date of service and city are permitted in a limited dataset but not in full PHI. Do not auto-flag any date as PHI without context; check for surrounding patient-name or diagnosis proximity.
PHI detection via regex misses data encoded in BLOBs, base64-embedded JSON, or encrypted-at-application-layer columns. A clean regex scan does not prove absence of PHI — document this explicitly in the report.
Healthcare keyword context gate has dialect drift: "patient" in a veterinary codebase is a dog, not a person under HIPAA. Review context before escalating findings from multi-tenant or vertical-adjacent codebases.
When NOT to Use
For generic security patterns (XSS, SQLi, CSRF) — use /security-patterns
For dependency vulnerabilities — use /cve-scan
For non-healthcare compliance regimes (PCI-DSS, SOC2, GDPR) — this skill is HIPAA-specific
For legal interpretation of compliance — this skill flags technical controls; only a QSA or attorney interprets compliance status
For PII/GDPR outside the HIPAA scope — overlapping but distinct; HIPAA covers PHI specifically
Reference Documents
reference/hipaa-rules.md — HIPAA Security Rule, Privacy Rule, and Breach Notification Rule mapped to technical controls
