Repository navigation
Releases: kaveen-ai/dicom-clean
Releases · kaveen-ai/dicom-clean
Release list
dicom-clean v1.0.0 — Initial Release
🩺 dicom-clean v1.0.0 — Initial Release
First public release of dicom-clean — a fast, local-first, HIPAA-compliant DICOM metadata anonymization CLI.
De-identify patient DICOM files in seconds — from your terminal, from your laptop, with zero cloud calls.
✨ What's New
- 🎯 Modern CLI — Built with Typer + Rich for a sleek, colorized terminal experience with live progress bars and summary tables
- 🔒 HIPAA Safe Harbor — Strips / blanks all 18 HIPAA Patient Identifiers (names, birth dates, addresses, MRNs, institution names, referring physicians, accession numbers, and more)
- 🧠 Deterministic UID Pseudonymization — Re-hashes
StudyInstanceUID,SeriesInstanceUID, andSOPInstanceUIDusing SHA-256 with an optional salt — preserving study/series relationships without exposing originals - 🖼️ Image Integrity Guaranteed — Pixel data, windowing, spacing, and modality tags are never touched. PACS and viewers continue to render the image normally
- 🔐 Private Tag Stripping — Vendor private tags (which often contain embedded PHI) are removed by default
- 📅 Date Reduction —
StudyDate/SeriesDate/AcquisitionDateare reduced to year-only (YYYY0101), as permitted by Safe Harbor - 📁 Batch Processing — Recursively processes entire directory trees, preserving the original subfolder structure
- 🛡️ Robust — Non-DICOM files are skipped with a warning instead of crashing. Per-file errors are collected into a summary
- 📦 Zero-Dependency Build — Ships as a standalone single-file executable (
.exeon Windows) requiring no Python installation
📦 Installation
🪟 Windows — Standalone Executable (Recommended)
No Python required. No dependencies. Just download and run.
- Download
dicom-clean.exefrom the Assets section below - Save it to a permanent location (e.g.,
C:\Tools\dicom-clean\) - Open Command Prompt (Win+R →
cmd→ Enter) - Navigate to the folder and run:
cd C:\Tools\dicom-clean
dicom-clean.exe --help
⚠️ Windows SmartScreen: Because the binary is unsigned, Windows may display an "Unknown publisher" prompt. Click More info → Run anyway.
🍎 macOS / 🐧 Linux — Standalone Binary
# Download the binary for your platform from Assets below
chmod +x dicom-clean
sudo mv dicom-clean /usr/local/bin/
# On macOS, remove the quarantine attribute:
sudo xattr -d com.apple.quarantine /usr/local/bin/dicom-clean🐍 From Source (For Developers)
Requirements: Python 3.10+ and pip.
# 1. Clone the repository
git clone https://github.com/kaveen-ai/dicom-clean.git
cd dicom-clean
# 2. (Recommended) Create a virtual environment
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS / Linux:
source .venv/bin/activate
# 3. Install dependencies
pip install -r requirements.txt
# 4. Run the CLI
python anonymizer.py --helpBuild your own standalone binary:
python build.py --clean
# → dist/dicom-clean.exe (or dist/dicom-clean on Unix)🧪 Quick Usage
Anonymize a single DICOM file
dicom-clean sanitize patient_scan.dcm ./output/ --salt "my-secret"Anonymize an entire directory (recursive)
dicom-clean sanitize /data/hospital_pacs /data/research_export --salt "my_secret_salt_2024"Full command reference
dicom-clean sanitize [OPTIONS] INPUT_PATH OUTPUT_PATH| Option | Short | Description |
|---|---|---|
--salt "value" |
-s |
Recommended. Secret salt for UID pseudonymization |
--keep-private |
Keep vendor private tags ( |
|
--verbose |
-v |
Enable detailed DEBUG-level logging |
--help |
Show help and exit |
📊 Sample Output
╭─ MedAnonym / DICOM-Clean CLI ─────────────────────────────╮
│ HIPAA Safe Harbor DICOM De-Identification │
│ UID salt: enabled Private tags: stripped │
╰───────────────────────────────────────────────────────────╯
⠋ Anonymizing DICOM files ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% • 1,248/1,248 • 00:00:42
Anonymization Summary
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ Metric ┃ Count ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
│ Total Files Scanned │ 1250 │
│ Successfully Anonymized │ 1248 │
│ Skipped (Non-DICOM) │ 2 │
│ Errors / Failed │ 0 │
└───────────────────────────┴───────┘
✔ Done. Output is ready.
🔒 Security & Compliance
Fully Local Execution — dicom-clean never opens a network socket, never phones home, and never writes to a remote service.
- ✅ 100% offline. You can (and should) run it on an air-gapped workstation
- ✅ No telemetry. No analytics. No usage tracking
- ✅ No cloud SDKs are imported
- ✅ Open source. Every line of code is auditable under AGPL-3.0
HIPAA Safe Harbor De-Identification — This tool implements the Safe Harbor method defined in 45 CFR §164.514(b)(2)(i), removing or generalizing all 18 categories of identifiers:
- Names
- Geographic subdivisions smaller than a state
- Dates (other than year) directly related to an individual
- Phone numbers
- Fax numbers
- Email addresses
- Social Security numbers
- Medical record numbers
- Health plan beneficiary numbers
- Account numbers
- Certificate / license numbers
- Vehicle identifiers and serial numbers
- Device identifiers and serial numbers
- Web URLs
- IP addresses
- Biometric identifiers
- Full-face photographs and comparable images
- Any other unique identifying number, characteristic, or code
⚠️ Not legal advice. De-identification is a legal process, not a technical one. Before deploying in a production clinical workflow, validate the output against your institution's Privacy Officer and applicable regulations.
🏗️ Architecture
dicom-clean/
├── anonymizer.py # Core engine + Typer/Rich CLI
├── build.py # Automated PyInstaller build script
├── requirements.txt # Runtime dependencies
├── LICENSE # AGPL-3.0 full text
├── NOTICE # Dual-licensing notice
├── LICENSE-COMMERCIAL.md # Commercial license terms
├── CLA.md # Contributor License Agreement
├── CONTRIBUTING.md # Contribution guidelines
└── README.md
Core stack:
- pydicom — DICOM parsing & serialization
- Typer — CLI framework
- Rich — Terminal UI
- PyInstaller — Standalone binary packaging
Processing pipeline:
[input DICOM] → [parse via pydicom]
→ [pseudonymize UIDs (SHA-256 + salt)]
→ [blank HIPAA scalar tags]
→ [remove PHI sequences]
→ [reduce dates to year-only]
→ [strip private tags]
→ [sanitize file meta]
→ [write to output directory]
📜 License
Dual-licensed:
- AGPL-3.0-or-later — for open-source use (personal, academic, non-profit)
- Commercial License — for commercial hospitals, SaaS deployments, and closed-source integrations
See LICENSE for the full AGPL-3.0 text and LICENSE-COMMERCIAL.md for commercial terms.
For commercial licensing inquiries: hello@medanonym.dev
🗺️ Roadmap
✅ Phase 1 — Open Core (This Release)
- CLI with Typer + Rich
- HIPAA Safe Harbor metadata anonymization
- Deterministic SHA-256 UID pseudonymization
- Directory batch processing
- Standalone
.exebuild (PyInstaller)
🔜 Phase 2 — Community Release
- GitHub Actions CI (Python 3.10–3.13, Windows/macOS/Linux)
- Signed release artifacts + SHA-256 checksums
- Docker image (
ghcr.io/kaveen-ai/dicom-clean) -
pip install dicom-clean(PyPI publication)
🚧 Phase 3 — MedAnonym Commercial Edition (Planned)
- 🖼️ Pixel OCR text redaction (burns out PHI in image pixels)
- 📡 PACS DICOM Listener (C-STORE SCP)
- 📜 HIPAA Compliance Certificates (JSON + PDF audit reports)
- 🏥 Enterprise deployment (MSI installer, SIEM integration)
🙏 Acknowledgements
- pydicom — the backbone of this tool
- Typer and Rich — for making CLI tools delightful
- The DICOM Standard — for the tag dictionary that makes all of this possible
- The HHS Office for Civil Rights — for the Safe Harbor guidance that informs this implementation
🐛 Found a Bug? Have a Feature Request?
- Bug reports: Open an issue
- Feature requests: Start a discussion
- Security issues: Email
security@medanonym.dev(do NOT open a public issue)
📥 Download
Attached files below:
- 📦
dicom-clean.exe— Windows standalone executable (~25 MB)
Made with ❤️ for the medical imaging community.
⭐ If dicom-clean saves you time, consider ...