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 "$(dirname "$0")/../app/skills/hipaa-validate/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

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 script implements the following scan categories. This reference is provided so you can explain findings to the user and verify edge cases.

Modes:

• developer (default): Categories 1, 3, 4, 7, 8 — definitive regex matches only, low false-positive rate
• compliance: All 8 categories — includes heuristic checks (Cat 2, 5, 6)

Default keywords: patient, diagnosis, medication, clinical, healthcare, medical, fhir, hl7, hipaa, phi, protected.health, health-record, health-plan, health-insurance

Note: Bare health is deliberately excluded — it matches infrastructure health checks in nearly every codebase.

Built-in exclusions: Binary files, lock files, vendored directories (node_modules/, vendor/, .git/, dist/, build/, out/, .next/). Test directories (test/, tests/, __tests__/, spec/, fixtures/, mocks/) are excluded for Category 4 only.

Categories 1 and 2 scan the full project. Categories 3–8 scan only PHI-adjacent files.

Category 1: PHI in Logs/Console Output

Scan the full project for log/print statements that reference PHI keywords.

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)):

Category 2: Missing Audit Logging

Compliance mode only. Heuristic — flags potential gaps, not definitive findings.

Developer mode: This category is skipped. Run with --mode compliance to include audit gap checks.

Scan the full project for files that handle PHI data operations but lack audit-related keywords.

PHI route file definition: A file qualifies if it contains BOTH:

1. A healthcare keyword from Step 0 (patient, diagnosis, medication, etc.)
2. A data operation pattern: router, app.get, app.post, app.put, app.delete, @RequestMapping, @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, Model.find, Model.save, Model.update, db.query, db.execute, cursor.execute, repository., findBy, save(, delete(, @app.route, @blueprint.route, @api_view, ViewSet, APIView, \bsession.(query|add|execute|delete|merge)\b (word-anchored — SQLAlchemy only, avoids matching Express req.session.save)

Files with a healthcare keyword but no data operation pattern are excluded.

Audit keywords (co-occurrence check): audit, AuditEvent, auditLog, logAccess, logEvent, createAuditEntry, recordAccess, ActivityLog, trail, writeAudit

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.

See: reference/hipaa-rules.md §164.312(b) for audit control requirements.

Category 3: Unencrypted PHI Transmission

Context-gated: scans PHI-adjacent files only.

See: reference/hipaa-rules.md §164.312(e)(1) for transmission security requirements.

Category 4: Hardcoded PHI/Test Data

Context-gated: scans PHI-adjacent files only.

Built-in test directory exclusions: Skip files in test/, tests/, __tests__/, spec/, fixtures/, mocks/, __mocks__/, testdata/, test-data/ — test fixtures legitimately contain synthetic PHI.

See: reference/phi-identifiers.md for the full list of 18 HIPAA identifiers and detection patterns.

Category 5: Access Control Gaps

Context-gated: scans PHI-adjacent files only. Heuristic — flags potential gaps.

Auth keywords (co-occurrence check): auth, authenticate, requireAuth, isAuthenticated, protect, guard, Authorize, login_required, Permission, permission_required, LoginRequiredMixin, PermissionRequiredMixin, IsAuthenticated, Depends, Security

Data operation patterns (Python frameworks): @app.route, @blueprint.route, @api_view, ViewSet, APIView, cursor.execute, \bsession.(query|execute)\b (word-anchored — SQLAlchemy only)

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.

Category 6: Missing BAA References

Compliance mode only. Context-gated: scans PHI-adjacent files only.

Developer mode: This category is skipped. Run with --mode compliance to include BAA checks.

Instead of per-finding rows, emit a single BAA Verification Checklist in the compliance report:

1. Grep PHI-adjacent files for HTTP client calls (fetch(, axios., requests., http.Get, HttpClient, RestTemplate, urllib). Extract external domains.
2. Grep for cloud storage calls (S3, GCS, BlobStorage, putObject, upload). Note each service.
3. Grep for cloud database connections (mongodb+srv://, postgres://, mysql://, firestore, dynamodb, CosmosClient, MongoClient, connection strings with cloud hostnames). Note each service.
4. Grep for message queue / event streaming services (SQS, SNS, RabbitMQ, redis://, kafka, EventBridge, PubSub). Note each service.
5. Grep for CDN references (CloudFront, Cloudflare, Akamai, Fastly, cdn.) serving PHI-adjacent paths. Note each service.
6. Grep for observability / logging SDKs (datadog, splunk, newrelic, sentry, logstash, elasticsearch, bugsnag, rollbar). Note each SDK.
7. Grep for analytics SDK calls (analytics., gtag, mixpanel, segment, amplitude, posthog). Note each SDK.
8. Read .hipaa-config at project root if it exists. Suppress vendors listed under covered_vendors.
9. Emit one checklist row per unverified domain/service.

.hipaa-config format (suppress known-covered vendors):

{
  "covered_vendors": ["aws", "twilio", "sendgrid", "stripe"]
}

Output format for compliance mode:

### BAA Verification Checklist
| Service/Domain | Pattern Detected | BAA Status |
|----------------|-----------------|------------|
| AWS S3 | `putObject` in src/storage/patient-files.ts | ✓ covered (covered_vendors) |
| sendgrid.com | `axios.post` in src/notifications/email.ts | ⚠️ verify BAA exists |
| analytics.google.com | `gtag` in src/components/Dashboard.tsx | ❌ verify no PHI flows here |

Note: This is a documentation checklist, not a legal review. Items marked ⚠️ or ❌ require human verification, not code changes.

Category 7: Encryption at Rest

Context-gated: scans PHI-adjacent files only. Developer mode.

Detects PHI storage patterns without encryption references. Per §164.312(a)(2)(iv), ePHI must be encrypted when stored.

See: reference/hipaa-rules.md §164.312(a)(2)(iv) for encryption requirements.

Category 8: PHI Temp File Exposure

Context-gated: scans PHI-adjacent files only. Developer mode.

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.

See: reference/hipaa-rules.md §164.310(d)(2)(iii) for disposal requirements.

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

• 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