Hipaa Validate

/hipaa-validate - HIPAA Compliance Scanner

$ARGUMENTS

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

1. Run scanner script — execute scripts/hipaa_scan.py with passed arguments
2. Interpret results — analyze findings, add context, suggest specific fixes
3. 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:

python3 ${CLAUDE_SKILL_DIR}/scripts/hipaa_scan.py [path] [--mode developer|compliance] [--severity high|warn] [--keywords term1,term2] [--output json]

The script handles all scanning logic deterministically:

• Context gate — identifies PHI-adjacent files via healthcare keyword matching
• Language detection — detects project languages from manifest files
• 8 check categories — runs regex patterns and co-occurrence heuristics
• Deduplication — removes duplicate findings (same file+line+category)
• .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

Read reference/scanner-categories.md once before starting — you cannot judge a heuristic finding without the pattern that produced it.

For each finding from the script output:

1. Read the flagged file and line to understand the actual code context
2. Add a specific fix suggestion — not generic advice, but concrete code changes based on what you see
3. 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)
4. Mark confirmed false positives and suggest adding them to .hipaaignore

Scanner Reference

The eight scan categories are implemented in scripts/hipaa_scan.py. The pattern tables, severities, per-language coverage and rule citations live in reference/scanner-categories.md.

Read that file once, in full, before enriching findings in Step 2 — it is what lets you explain why a line matched and judge whether a heuristic hit is a false positive. The scan itself does not need it; the script already holds the patterns.

Categories 1 and 2 scan the full project; categories 3–8 scan only PHI-adjacent files. Compliance mode adds the heuristic categories 2, 5 and 6 to the developer set.

Step 3: Compile and Report

Present the scanner output to the user. Sort by severity (HIGH first), then by file path.

Output Format

## HIPAA Validation Report

### Summary
| Metric | Value |
|--------|-------|
| Mode | developer / compliance |
| PHI-adjacent files | N |
| Files scanned | N |
| Categories run | 1,3,4,7,8 (developer) / 1,2,3,4,5,6,7,8 (compliance) |
| Severity HIGH | N |
| Severity WARN | N |

### Findings

#### [HIGH] src/api/patients.ts:42
Category: PHI in Logs
Confidence: definitive (regex match)
Pattern: `console.log(patient.name)`
HIPAA Rule: §164.502(b) — Minimum Necessary Standard
Fix: Replace with `safeLog()` or remove PHI from log output

#### [HIGH] src/routes/patient-api.ts:15
Category: Missing Audit Logging
Confidence: heuristic (co-occurrence check — may be false positive)
Pattern: PHI route file without audit keywords
HIPAA Rule: §164.312(b) — Audit Controls
Fix: Verify audit logging exists in call chain; add AuditEvent creation if missing

#### [WARN] src/services/patient-sync.ts:88
Category: Unencrypted PHI Transmission
Confidence: definitive (regex match)
Pattern: `http://external-api.example.com/patients`
HIPAA Rule: §164.312(e)(1) — Transmission Security
Fix: Use HTTPS for all PHI transmission

Confidence values:

• definitive — Categories 1, 3, 4, 7, 8: regex matched actual code
• 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

• Check language_detection in the summary before trusting a zero. Category 1, 3, 4 and 7 patterns are language-tagged and only fire for a detected language. Manifests decide first (pyproject.toml, package.json, go.mod, …); without one the scanner falls back to file extensions. If it reports languages: ["any"] with language_detection: "none", the language rules never ran and HIGH: 0 means unscanned, not compliant — the scanner prints that warning to stderr, so a run whose stderr is discarded loses it.

• Scanning a monorepo package or a subdirectory can put you below the manifest. The extension fallback covers the common case, but a directory of .sql, .yaml or templates resolves to no language at all — scan from the level that holds the manifest.

• 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
• reference/phi-identifiers.md — The 18 HIPAA identifiers with detection patterns and detectability status