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: ```bash 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 ```markdown ## 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](reference/hipaa-rules.md) — HIPAA Security Rule, Privacy Rule, and Breach Notification Rule mapped to technical controls - [reference/phi-identifiers.md](reference/phi-identifiers.md) — The 18 HIPAA identifiers with detection patterns and detectability status