phi-scan 0.3.0__tar.gz

phi_scan-0.3.0/.gitignore

@@ -0,0 +1,27 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment variables — never commit credentials or PHI values
+.env
+
+# SQLite databases — may contain PHI; exclude from version control
+*.db
+*.sqlite3
+
+# PhiScan internal state — stores SHA-256 hashes, never raw PHI
+.phi-scanner/
+
+# PhiScan scan output
+phi-report.json
+
+# Test coverage artifacts
+.coverage
+coverage.xml

phi_scan-0.3.0/.phi-scanner.yml

@@ -0,0 +1,90 @@
+# PhiScan default configuration
+# Generated by: phi-scan config init
+# Reference: phi-scan explain config
+
+# Schema version for forward-compatibility. Increment when breaking changes
+# are introduced to this file's structure so the config loader can migrate.
+version: 1
+
+scan:
+  # Minimum confidence score to report a finding (0.0–1.0).
+  # Set to 0.7 for this repo: context-dependent patterns without matching context
+  # keywords (e.g. HEALTH_PLAN_NUMBER matching any 8–20 char identifier) fire at
+  # 0.65 (_CONFIDENCE_CONTEXT_ABSENT) and generate false positives in source code.
+  # Context-confirmed findings (0.88) and structural patterns (SSN, MBI, etc.) are
+  # well above 0.7 and are unaffected. Clinical repos should set this to 0.5–0.6.
+  confidence_threshold: 0.7
+
+  # Minimum severity level to include in output and exit-code evaluation.
+  # Maps to the SeverityLevel enum (not RiskLevel — that is per-scan aggregate).
+  # Accepted values (lowercase): low, medium, high
+  # The config loader maps lowercase → enum: low → SeverityLevel.LOW, etc.
+  # ConfigurationError is raised on any value not in this set.
+  severity_threshold: low
+
+  # Maximum file size to scan. Files exceeding this limit are skipped and logged.
+  max_file_size_mb: 10
+
+  # SECURITY: Symlink following is disabled and must remain false.
+  # Setting this to true is a security violation — it allows traversal to escape
+  # the repository boundary and cause infinite loops in CI/CD environments.
+  # The config loader reads this field: if set to true, it raises ConfigurationError
+  # and the scan does not start. This field is not silently ignored.
+  follow_symlinks: false
+
+  # Optional allowlist of file extensions to scan.
+  # When set to null (default), all non-binary text files are scanned.
+  # Example: [".py", ".js", ".ts", ".yaml", ".yml"]  (.yaml and .yml are equivalent)
+  include_extensions: null
+
+  # Paths and patterns to exclude from scanning (gitignore-style via pathspec).
+  # Evaluated at every directory depth — node_modules/ matches at any level.
+  exclude_paths:
+    - .git/
+    - .venv/
+    - node_modules/
+    - dist/
+    - build/
+    - "*.egg-info/"
+    - __pycache__/
+    - .mypy_cache/
+    - .ruff_cache/
+    - .pytest_cache/
+    - htmlcov/
+    - "*.pyc"
+    - "*.pyo"
+
+output:
+  # Default output format when --output flag is not specified.
+  # Accepted values: table, json, sarif, csv, pdf, html, junit, codequality, gitlab-sast
+  # All values map directly by name to OutputFormat (e.g., table → OutputFormat.TABLE),
+  # except gitlab-sast which must be mapped explicitly to OutputFormat.GITLAB_SAST —
+  # not via a generic replace/upper transform.
+  # ConfigurationError is raised on any value not in this set.
+  # Run: phi-scan explain config for authoritative descriptions of each format.
+  format: table
+
+  # Suppress all Rich terminal output.
+  # Spec: findings must still be written to the audit log when quiet: true.
+  # Exit code is NOT affected — violations must still produce a non-zero exit code
+  # when quiet: true, ensuring CI gates continue to work correctly.
+  quiet: false
+
+audit:
+  # Path to the SQLite audit database.
+  # Audit logs are immutable — never DELETE or UPDATE rows (HIPAA 45 CFR §164.530(j)).
+  # Note: ~ is expanded via Path(database_path).expanduser() at runtime — not by the
+  # YAML parser. Ensure the runtime handles this before using the value as a file path.
+  database_path: "~/.phi-scanner/audit.db"
+
+  # HIPAA 45 CFR §164.530(j) requires audit records for a minimum of 6 years.
+  # Any 6-year span contains at most 2 leap years: 4×365 + 2×366 = 2192.
+  # This is the mathematical maximum — 3+ leap years in 6 years is impossible.
+  # AUDIT_RETENTION_DAYS in constants.py must equal this value.
+  retention_days: 2192
+
+ai:
+  # Claude API review is disabled by default — all scanning is local.
+  # Enabling this sends only redacted code structure (never raw PHI) to the API.
+  # See CLAUDE.md AI Integration Rules before enabling.
+  enable_claude_review: false

phi_scan-0.3.0/.pre-commit-hooks.yaml

@@ -0,0 +1,24 @@
+# PhiScan pre-commit hook definition.
+#
+# This file registers phi-scan with the pre-commit framework (https://pre-commit.com).
+# Add the hook to your project by creating or editing .pre-commit-config.yaml:
+#
+#   repos:
+#     - repo: https://github.com/joeyessak/phi-scan
+#       rev: v0.1.0
+#       hooks:
+#         - id: phi-scan
+#
+# See docs/ci-cd-integration.md for full configuration options.
+- id: phi-scan
+  name: "PhiScan \u2014 PHI/PII Detection"
+  description: >
+    Scan staged changes for HIPAA-covered Protected Health Information (PHI) and PII.
+    Blocks the commit when new findings are detected. All scanning runs locally —
+    no data is transmitted to any external service.
+  entry: phi-scan scan --diff HEAD
+  language: python
+  types: [text]
+  pass_filenames: false
+  stages: [pre-commit, pre-push]
+  minimum_pre_commit_version: "2.0.0"

phi_scan-0.3.0/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to PhiScan will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-03-30
+
+### Added
+
+- **Detection engine — 4 layers:**
+  - Layer 1: Regex pattern registry covering all 18 HIPAA Safe Harbor identifiers plus MBI,
+    HICN, DEA number, genetic identifiers (rs-IDs, VCF, Ensembl), SUD-related field names,
+    age >90, quasi-identifier combinations (ZIP + DOB + sex), and NPI type distinction
+  - Layer 2: NLP named entity recognition via Presidio + spaCy (`phi-scan[nlp]` optional extra)
+  - Layer 3: FHIR R4 structured field scanning and HL7 v2 segment scanning (PID, NK1, IN1)
+    via `phi-scan[fhir]` and `phi-scan[hl7]` optional extras
+  - Layer 4: AI-assisted confidence scoring via Claude API (optional, disabled by default,
+    PHI is always redacted before any API call)
+- **CLI commands:** `scan`, `scan --diff`, `scan --file`, `watch`, `report`, `history`,
+  `init`, `setup`, `fix`, `explain`, `baseline`, `install-hook`, `uninstall-hook`,
+  `config init`, `dashboard`, `plugins list`
+- **Output formats:** `table`, `json`, `csv`, `sarif`, `junit`, `codequality`, `gitlab-sast`
+- **Baseline management:** `phi-scan baseline create|show|clear|update|diff` — adopt
+  PhiScan incrementally in existing codebases; only new findings block CI
+- **Auto-fix engine:** `phi-scan fix --dry-run|--apply|--patch` — replace PHI with
+  deterministic synthetic data (requires `faker`)
+- **Inline suppression:** `# phi-scan:ignore`, `# phi-scan:ignore[SSN,MRN]`,
+  `# phi-scan:ignore-next-line`, `# phi-scan:ignore-file` with language-aware prefixes
+- **SQLite audit log:** immutable HIPAA-compliant scan history; SHA-256 hashes only,
+  raw PHI values never stored
+- **Structured output cache:** content-hash based scan cache to skip unchanged files
+- **Pre-commit framework integration:** `.pre-commit-hooks.yaml` registers phi-scan as a
+  pre-commit hook; `phi-scan install-hook` installs a native git pre-commit hook
+- **Rich terminal UI:** progress bar, findings table, file tree, code context panels,
+  ASCII banner; suppressed automatically for piped/serialised output formats
+- **Graceful degradation:** NLP, FHIR, HL7, and AI layers each degrade to a logged
+  warning when their optional dependency group is not installed
+- **PHI hygiene at detection layer:** matched PHI values are redacted to `[REDACTED]` in
+  `code_context` before `ScanFinding` is constructed — raw values never stored or displayed
+- **Rich markup safety:** user-derived strings (file paths, source lines) are escaped
+  before Rich rendering to prevent `MarkupError` crashes on source containing `[` characters
+
+### Changed
+
+- Version bumped from `0.1.0` to `0.3.0` (Phases 1–3C complete per version table in PLAN.md)
+- Dependency bounds narrowed to compatible-release pins (`~=`) for predictable installs
+
+## [0.1.0] - 2026-03-01
+
+### Added
+
+- Project scaffolding: `pyproject.toml`, CI workflows (lint, typecheck, test, release,
+  Claude PR review), MIT license, `README.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`
+- Typer CLI skeleton with Rich terminal UI and pyfiglet ASCII banner
+- Structured logging (`--log-level`, `--log-file`)
+- YAML configuration loading and validation (`.phi-scanner.yml`)
+- Git diff file extraction (`--diff` mode)
+- `.phi-scanignore` exclusion pattern support (gitignore-style via pathspec)
+
+[Unreleased]: https://github.com/joeyessak/phi-scan/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/joeyessak/phi-scan/compare/v0.1.0...v0.3.0
+[0.1.0]: https://github.com/joeyessak/phi-scan/releases/tag/v0.1.0

phi_scan-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joey Essak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

phi_scan-0.3.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: phi-scan
+Version: 0.3.0
+Summary: PHI/PII Scanner for CI/CD pipelines. HIPAA & FHIR compliant. Local execution only.
+Project-URL: Homepage, https://github.com/joeyessak/phi-scan
+Project-URL: Repository, https://github.com/joeyessak/phi-scan
+Project-URL: Issues, https://github.com/joeyessak/phi-scan/issues
+Project-URL: Changelog, https://github.com/joeyessak/phi-scan/blob/main/CHANGELOG.md
+Author-email: Joey Essak <joey.essak@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Joey Essak
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cicd,compliance,fhir,hipaa,phi,pii,scanner,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx~=0.27
+Requires-Dist: pathspec~=0.12
+Requires-Dist: pyfiglet~=1.0
+Requires-Dist: python-dotenv~=1.2
+Requires-Dist: pyyaml~=6.0
+Requires-Dist: rich~=13.7
+Requires-Dist: typer[all]~=0.24.1
+Requires-Dist: watchdog~=4.0
+Provides-Extra: fhir
+Requires-Dist: fhir-resources>=7.0; extra == 'fhir'
+Provides-Extra: full
+Requires-Dist: fhir-resources>=7.0; extra == 'full'
+Requires-Dist: fpdf2>=2.7; extra == 'full'
+Requires-Dist: hl7>=0.4; extra == 'full'
+Requires-Dist: jinja2>=3.1; extra == 'full'
+Requires-Dist: matplotlib>=3.8; extra == 'full'
+Requires-Dist: presidio-analyzer>=2.0; extra == 'full'
+Requires-Dist: presidio-anonymizer>=2.0; extra == 'full'
+Requires-Dist: spacy>=3.7; extra == 'full'
+Provides-Extra: hl7
+Requires-Dist: hl7>=0.4; extra == 'hl7'
+Provides-Extra: nlp
+Requires-Dist: presidio-analyzer>=2.0; extra == 'nlp'
+Requires-Dist: presidio-anonymizer>=2.0; extra == 'nlp'
+Requires-Dist: spacy>=3.7; extra == 'nlp'
+Provides-Extra: reports
+Requires-Dist: fpdf2>=2.7; extra == 'reports'
+Requires-Dist: jinja2>=3.1; extra == 'reports'
+Requires-Dist: matplotlib>=3.8; extra == 'reports'
+Description-Content-Type: text/markdown
+
+# PhiScan
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
+[![CI](https://github.com/joeyessak/phi-scan/actions/workflows/ci.yml/badge.svg)](https://github.com/joeyessak/phi-scan/actions/workflows/ci.yml)
+
+HIPAA & FHIR compliant PHI/PII scanner for CI/CD pipelines. Local execution only — no PHI ever leaves your infrastructure.
+
+---
+
+## What it does
+
+PhiScan scans source code for Protected Health Information (PHI) and Personally Identifiable Information (PII) before it reaches your main branch. It integrates into CI/CD pipelines to block pull requests that contain exposed PHI.
+
+All scanning runs locally inside your pipeline runner. Nothing is sent to an external API.
+
+---
+
+## Install
+
+```bash
+pipx install phi-scan
+```
+
+Or with uv:
+
+```bash
+uv tool install phi-scan
+```
+
+---
+
+## Usage
+
+```bash
+# Scan a directory
+phi-scan scan ./src
+
+# Scan only files changed in the last commit
+phi-scan scan --diff HEAD~1
+
+# Scan a single file
+phi-scan scan --file path/to/handler.py
+
+# Output as JSON
+phi-scan scan ./src --output json
+
+# Show help
+phi-scan --help
+```
+
+---
+
+## Contributing
+
+### Branch protection rules
+
+The `main` branch is protected. All changes arrive via pull request. No one pushes directly to `main`.
+
+| Rule | Setting |
+| ---- | ------- |
+| Require CI to pass before merge | All jobs in `ci.yml` must pass (lint, typecheck, tests on all 3 platforms) |
+| Require at least one review | Enforced when collaborators join the project |
+| No direct pushes to `main` | Branch protection enforced via GitHub settings |
+
+To configure these rules: **Settings → Branches → Add branch protection rule → `main`**, then enable:
+- "Require a pull request before merging"
+- "Require status checks to pass before merging" → select the `CI` workflow jobs
+- "Do not allow bypassing the above settings"
+
+### CI workflows
+
+| Workflow | Trigger | What it does |
+| -------- | ------- | ------------ |
+| `ci.yml` | Every push and PR targeting `main` | Lint (ruff), typecheck (mypy), tests (pytest + coverage) on Python 3.12 × ubuntu/macos/windows |
+| `release.yml` | Push of a `v*` tag | Runs tests, builds sdist + wheel, publishes to PyPI, creates GitHub Release |
+| `claude-review.yml` | Every PR open/update | Posts an automated Claude code review comment |
+
+---
+
+## License
+
+[MIT](LICENSE)

phi_scan-0.3.0/README.md

@@ -0,0 +1,83 @@
+# PhiScan
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
+[![CI](https://github.com/joeyessak/phi-scan/actions/workflows/ci.yml/badge.svg)](https://github.com/joeyessak/phi-scan/actions/workflows/ci.yml)
+
+HIPAA & FHIR compliant PHI/PII scanner for CI/CD pipelines. Local execution only — no PHI ever leaves your infrastructure.
+
+---
+
+## What it does
+
+PhiScan scans source code for Protected Health Information (PHI) and Personally Identifiable Information (PII) before it reaches your main branch. It integrates into CI/CD pipelines to block pull requests that contain exposed PHI.
+
+All scanning runs locally inside your pipeline runner. Nothing is sent to an external API.
+
+---
+
+## Install
+
+```bash
+pipx install phi-scan
+```
+
+Or with uv:
+
+```bash
+uv tool install phi-scan
+```
+
+---
+
+## Usage
+
+```bash
+# Scan a directory
+phi-scan scan ./src
+
+# Scan only files changed in the last commit
+phi-scan scan --diff HEAD~1
+
+# Scan a single file
+phi-scan scan --file path/to/handler.py
+
+# Output as JSON
+phi-scan scan ./src --output json
+
+# Show help
+phi-scan --help
+```
+
+---
+
+## Contributing
+
+### Branch protection rules
+
+The `main` branch is protected. All changes arrive via pull request. No one pushes directly to `main`.
+
+| Rule | Setting |
+| ---- | ------- |
+| Require CI to pass before merge | All jobs in `ci.yml` must pass (lint, typecheck, tests on all 3 platforms) |
+| Require at least one review | Enforced when collaborators join the project |
+| No direct pushes to `main` | Branch protection enforced via GitHub settings |
+
+To configure these rules: **Settings → Branches → Add branch protection rule → `main`**, then enable:
+- "Require a pull request before merging"
+- "Require status checks to pass before merging" → select the `CI` workflow jobs
+- "Do not allow bypassing the above settings"
+
+### CI workflows
+
+| Workflow | Trigger | What it does |
+| -------- | ------- | ------------ |
+| `ci.yml` | Every push and PR targeting `main` | Lint (ruff), typecheck (mypy), tests (pytest + coverage) on Python 3.12 × ubuntu/macos/windows |
+| `release.yml` | Push of a `v*` tag | Runs tests, builds sdist + wheel, publishes to PyPI, creates GitHub Release |
+| `claude-review.yml` | Every PR open/update | Posts an automated Claude code review comment |
+
+---
+
+## License
+
+[MIT](LICENSE)

phi_scan-0.3.0/phi_scan/__init__.py

@@ -0,0 +1,4 @@
+"""PhiScan — HIPAA & FHIR compliant PHI/PII scanner for CI/CD pipelines."""
+
+__version__ = "0.3.0"
+__app_name__ = "phi-scan"