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.