hipaa-validate
starsforks
How to install hipaa-validate?
softspark/ai-toolkit/hipaa-validate
$npx -y skills add softspark/ai-toolkit --skill hipaa-validateHIPAA validator: PHI exposure, audit logging, encryption, access control, BAA refs. Triggers: HIPAA, PHI, healthcare compliance, audit log, BAA.
SKILL.md
| 1 | # /hipaa-validate - HIPAA Compliance Scanner |
| 2 | |
| 3 | $ARGUMENTS |
| 4 | |
| 5 | 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. |
| 6 | |
| 7 | **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). |
| 8 | |
| 9 | ## Usage |
| 10 | |
| 11 | ``` |
| 12 | /hipaa-validate # Scan full project (developer mode — definitives only) |
| 13 | /hipaa-validate src/ # Scan specific path |
| 14 | /hipaa-validate --mode compliance # Full audit sweep including heuristic categories |
| 15 | /hipaa-validate --severity high # Filter to HIGH findings only |
| 16 | /hipaa-validate --keywords member,enrollee # Extend healthcare keyword list |
| 17 | /hipaa-validate --output json # Structured JSON output for CI integration |
| 18 | ``` |
| 19 | |
| 20 | **Modes:** |
| 21 | - `developer` (default): Categories 1, 3, 4, 7, 8 — definitive regex matches only, low false-positive rate, suited for daily use |
| 22 | - `compliance`: All 8 categories — includes heuristic checks (Cat 2, 5, 6) for audit sweep coverage, suited for pre-audit sweeps |
| 23 | |
| 24 | **Severity filtering:** `--severity high` shows only HIGH findings, `--severity warn` shows HIGH + WARN. Default shows all. |
| 25 | |
| 26 | ## What This Command Does |
| 27 | |
| 28 | 1. **Run scanner script** — execute `scripts/hipaa_scan.py` with passed arguments |
| 29 | 2. **Interpret results** — analyze findings, add context, suggest specific fixes |
| 30 | 3. **Report** — present findings with file paths, line numbers, severity, confidence, and HIPAA rule citations |
| 31 | |
| 32 | ## Steps |
| 33 | |
| 34 | ### Step 1: Run the Scanner Script |
| 35 | |
| 36 | Execute the Python scanner with the user's arguments: |
| 37 | |
| 38 | ```bash |
| 39 | python3 "$(dirname "$0")/../app/skills/hipaa-validate/scripts/hipaa_scan.py" [path] [--mode developer|compliance] [--severity high|warn] [--keywords term1,term2] [--output json] |
| 40 | ``` |
| 41 | |
| 42 | The script handles all scanning logic deterministically: |
| 43 | - **Context gate** — identifies PHI-adjacent files via healthcare keyword matching |
| 44 | - **Language detection** — detects project languages from manifest files |
| 45 | - **8 check categories** — runs regex patterns and co-occurrence heuristics |
| 46 | - **Deduplication** — removes duplicate findings (same file+line+category) |
| 47 | - **`.hipaaignore` support** — honors exclusion patterns from project root |
| 48 | - **`.hipaa-config` support** — reads `covered_vendors` for BAA checks |
| 49 | |
| 50 | If the script reports "No healthcare context detected", relay the message and suggest the `--keywords` flag with alternative terminology. |
| 51 | |
| 52 | 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. |
| 53 | |
| 54 | ### Step 2: Interpret and Enrich Results |
| 55 | |
| 56 | For each finding from the script output: |
| 57 | |
| 58 | 1. **Read the flagged file and line** to understand the actual code context |
| 59 | 2. **Add a specific fix suggestion** — not generic advice, but concrete code changes based on what you see |
| 60 | 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) |
| 61 | 4. **Mark confirmed false positives** and suggest adding them to `.hipaaignore` |
| 62 | |
| 63 | ### Scanner Reference |
| 64 | |
| 65 | The script implements the following scan categories. This reference is provided so you can explain findings to the user and verify edge cases. |
| 66 | |
| 67 | **Modes:** |
| 68 | - `developer` (default): Categories 1, 3, 4, 7, 8 — definitive regex matches only, low false-positive rate |
| 69 | - `compliance`: All 8 categories — includes heuristic checks (Cat 2, 5, 6) |
| 70 | |
| 71 | **Default keywords**: `patient`, `diagnosis`, `medication`, `clinical`, `healthcare`, `medical`, `fhir`, `hl7`, `hipaa`, `phi`, `protected.health`, `health-record`, `health-plan`, `health-insurance` |
| 72 | |
| 73 | > **Note**: Bare `health` is deliberately excluded — it matches infrastructure health checks in nearly every codebase. |
| 74 | |
| 75 | **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. |
| 76 | |
| 77 | Categories 1 and 2 scan the full project. Categories 3–8 scan only PHI-adjacent files. |
| 78 | |
| 79 | --- |
| 80 | |
| 81 | #### Category 1: P |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
