/hipaa-validate

name: hipaa-validate
description: "HIPAA validator: PHI exposure, audit logging, encryption, access control, BAA refs. Triggers: HIPAA, PHI, healthcare compliance, audit log, BAA."
user-invocable: true
effort: medium
disable-model-invocation: true
context: fork
agent: security-auditor
argument-hint: "[path] [--mode developer|compliance] [--severity high|warn] [--keywords term1,term2] [--output json]"
allowed-tools: Read, Grep, Glob, Bash

/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](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](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.

| # | Category | Scope | Mode | |---|----------|-------|------| | 1 | PHI in logs / console output (+ minimum-necessary violations) | full project | developer | | 2 | Missing audit logging | full project | compliance only, heuristic | | 3 | Unencrypted transmission | PHI-adjacent | developer | | 4 | Hardcoded PHI test data | PHI-adjacent | developer | | 5 | Access control gaps | PHI-adjacent | compliance only, heuristic | | 6 | Missing BAA references | PHI-adjacent | compliance only, heuristic | | 7 | Encryption at rest | PHI-adjacent | developer | | 8 | PHI temp file exposure | PHI-adjacent | developer |

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