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 "$(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.

Pattern	Severity	Language	Description
console\.log\(.*patient	HIGH	JS/TS	Patient data in console
console\.\w+\(.*req\.body	WARN	JS/TS	Raw request body may contain PHI
JSON\.stringify\(.*patient	WARN	JS/TS	Full patient object serialization
print\(.*\b(patient|ssn|social.security)	HIGH	Python	PHI in print statements
(logging|logger|pprint)\.\w+\(.*\b(patient|ssn|mrn|dob)	HIGH	Python	PHI in logger/named logger/pprint output
print\(.*request\.(data|json|form|POST|body)	WARN	Python	Raw request body may contain PHI (Django/Flask/FastAPI)
(logging|logger)\.\w+\(.*request\.(data|json|form|POST|body)	WARN	Python	Raw request body in logger
\brepr\(.*\b(patient|ssn|mrn)	WARN	Python	repr() may expose PHI fields
\bvars\(.*\b(patient|ssn|mrn)	WARN	Python	vars() dumps all PHI fields
fmt\.Print.*\b(patient|ssn|mrn)	HIGH	Go	PHI in fmt output
log\.\w+\(.*\b(patient|ssn|mrn)	HIGH	Go/Any	PHI in log calls
System\.out\.print.*\b(patient|ssn|mrn)	HIGH	Java	PHI in stdout
logger\.\w+\(.*\b(patient|ssn|mrn|dob)	HIGH	Java/Any	PHI fields in logger
puts.*\b(patient|ssn|mrn)	HIGH	Ruby	PHI in puts
Rails\.logger.*\b(patient|ssn|mrn)	HIGH	Ruby	PHI in Rails logger
Console\.Write.*\b(patient|ssn|mrn)	HIGH	C#	PHI in Console output
_logger\.\w+\(.*\b(patient|ssn|mrn|dob)	HIGH	C#	PHI in ILogger calls

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

Pattern	Severity	Language	Description
res\.(json|send)\(.*patient without field projection	WARN	JS/TS	Full patient object in API response
return.*patient in route handler without field selection	WARN	Any	May expose unnecessary PHI fields
SELECT\s+\*.*FROM.*(patient|member|enrollee)	WARN	SQL	SELECT * on PHI tables violates minimum necessary
JSON\.stringify\(.*patient	WARN	JS/TS	Full patient object serialization
json\.dumps\(.*patient	WARN	Python	Full patient object serialization
JsonConvert\.Serialize.*patient	WARN	C#	Full patient object serialization

---

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

Pattern	Severity	Description
PHI route file without any audit keywords in same file	HIGH	§164.312(b) — POTENTIAL audit gap: verify audit controls exist in call chain
CRUD operations on patient resources without audit keywords in same file	HIGH	POTENTIAL gap: all PHI access must be logged
Admin operations without audit trail reference	WARN	POTENTIAL gap: administrative actions need recording
Bulk data operations (export, download, bulk, batch) on PHI resources without audit keywords in same file	HIGH	POTENTIAL gap: mass PHI access must be tracked

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.

Pattern	Severity	Language	Description
http:// in API calls (not localhost/127.0.0.1)	HIGH	Any	§164.312(e)(1) requires encryption in transit
Missing TLS/SSL config in database connections	HIGH	Any	Database connections must be encrypted
rejectUnauthorized:\s*false	HIGH	Any	TLS verification disabled
ws:// (WebSocket without TLS)	WARN	Any	Unencrypted WebSocket may carry PHI
verify\s*=\s*False	HIGH	Python	TLS verification disabled (requests/httpx)
InsecureRequestWarning	WARN	Python	TLS warning suppressed
[,(]\s*ssl\s*=\s*False\b	HIGH	Python	SSL disabled in connector call (anchored to arg position to avoid matching is_ssl_enabled = False)
ssl\.CERT_NONE	HIGH	Python	TLS certificate verification disabled (anchored to ssl. module)
check_hostname\s*=\s*False	HIGH	Python	TLS hostname verification disabled
urllib3\.disable_warnings	WARN	Python	TLS warnings suppressed (urllib3)
SECURE_SSL_REDIRECT\s*=\s*False	WARN	Python	Django HTTPS redirect disabled (commonly False in dev settings — verify production config)
NODE_TLS_REJECT_UNAUTHORIZED.*0	HIGH	JS/TS	TLS rejection disabled globally

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.

Pattern	Severity	Description
\d{3}-\d{2}-\d{4} in PHI-adjacent source files	HIGH	Hardcoded SSNs
MRN patterns near healthcare keywords	HIGH	Medical record numbers in code
\b\d{5}(-\d{4})?\b near zip|postal|address keywords	WARN	ZIP codes in healthcare context (§164.514(b)(2)(i)(B))
Real-looking patient names in seed/fixture data	WARN	Use synthetic data generators
Date of birth + name co-occurrence in same file	WARN	Combined identifiers = PHI
Phone/email/IP regex matches in PHI-adjacent files	WARN	HIPAA identifiers in healthcare context
\d{3}[\s.-]?\d{3}[\s.-]?\d{4} near phone keyword	WARN	Phone numbers in healthcare context

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)

Pattern	Severity	Language	Description
PHI route file without any auth keywords in same file	WARN	Any	POTENTIAL access control gap — verify auth middleware covers these routes (§164.312(d))
Access-Control-Allow-Origin:\s*\* or origin:\s*(true|\*) in PHI-adjacent files	HIGH	Any	Unrestricted cross-origin access to PHI endpoints
Routes marked public, noAuth, anonymous exposing PHI keywords	HIGH	Any	PHI must require authentication
permission_classes\s*=.*AllowAny	WARN	Python	DRF AllowAny — verify no PHI exposed

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.

Pattern	Severity	Language	Description
encrypt\s*[:=]\s*false in database config files	HIGH	Any	§164.312(a)(2)(iv) — Encryption explicitly disabled
File write operations (writeFile, fs.write, open(.*w, File.Create) in PHI-adjacent code without encryption references	WARN	Any	PHI written to disk may lack encryption at rest
Database connection without ssl, encrypt, or tls keywords in PHI-adjacent config	WARN	Any	Database storing PHI should enforce encrypted connections
localStorage.setItem or sessionStorage.setItem with PHI keywords	HIGH	JS/TS	Browser storage is unencrypted — PHI must not be stored client-side without encryption
SharedPreferences or UserDefaults with PHI keywords	HIGH	Java/Any	Mobile local storage is unencrypted by default
pickle\.(dump|dumps)\( with PHI keywords	HIGH	Python	pickle serialization is unencrypted — PHI must be encrypted at rest
shelve\.open\( with PHI keywords	HIGH	Python	shelve storage is unencrypted — PHI must be encrypted at rest

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.

Pattern	Severity	Description
/tmp/ or tempfile\. or os\.tmpdir\(\) or Path\.GetTempPath in PHI-adjacent code	WARN	§164.310(d)(2)(iii) — Temp files with PHI must be securely deleted
mktemp or NamedTemporaryFile or createTempFile near PHI keywords	WARN	Verify temp files are cleaned up after use
Cache directory writes (cache/, .cache, Cache.set) with PHI keywords	WARN	Cached PHI must be encrypted or purged on schedule

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