Metadata-Version: 2.4
Name: dicom-fuzzer
Version: 1.12.0
Summary: A professional-grade DICOM fuzzing tool for healthcare security testing
Project-URL: Homepage, https://github.com/Dashtid/dicom-fuzzer
Project-URL: Documentation, https://github.com/Dashtid/dicom-fuzzer/tree/main/docs
Project-URL: Repository, https://github.com/Dashtid/dicom-fuzzer.git
Project-URL: Bug Tracker, https://github.com/Dashtid/dicom-fuzzer/issues
Project-URL: Changelog, https://github.com/Dashtid/dicom-fuzzer/blob/main/CHANGELOG.md
Author-email: David Dashti <david@dashti.se>
License: MIT
License-File: LICENSE
Keywords: cybersecurity,dicom,fuzzing,healthcare,medical-imaging,pacs,security,vulnerability-testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: cryptography>=46.0.7
Requires-Dist: numpy>=1.24.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydicom>=2.4.0
Requires-Dist: pynetdicom>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: structlog>=23.0.0
Requires-Dist: tqdm>=4.66.0
Provides-Extra: all
Requires-Dist: cyclonedx-bom>=4.0.0; extra == 'all'
Requires-Dist: matplotlib>=3.5.0; extra == 'all'
Requires-Dist: minidump>=0.0.21; extra == 'all'
Requires-Dist: pip-audit>=2.7.0; extra == 'all'
Requires-Dist: plotly>=5.0.0; extra == 'all'
Requires-Dist: prometheus-client>=0.21.0; extra == 'all'
Requires-Dist: pynetdicom[apps]>=2.0.0; extra == 'all'
Requires-Dist: redis>=5.2.0; extra == 'all'
Requires-Dist: seaborn>=0.12.0; extra == 'all'
Provides-Extra: distributed
Requires-Dist: redis>=5.2.0; extra == 'distributed'
Provides-Extra: metrics
Requires-Dist: prometheus-client>=0.21.0; extra == 'metrics'
Provides-Extra: network
Requires-Dist: pynetdicom[apps]>=2.0.0; extra == 'network'
Provides-Extra: security
Requires-Dist: cyclonedx-bom>=4.0.0; extra == 'security'
Requires-Dist: minidump>=0.0.21; extra == 'security'
Requires-Dist: pip-audit>=2.7.0; extra == 'security'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5.0; extra == 'viz'
Requires-Dist: plotly>=5.0.0; extra == 'viz'
Requires-Dist: seaborn>=0.12.0; extra == 'viz'
Description-Content-Type: text/markdown

# DICOM Fuzzer

Mutation-based fuzzer for robustness testing of DICOM medical imaging viewers and parsers. Generates malformed DICOM files and feeds them into target applications to find crashes and vulnerabilities.

[![CI](https://github.com/Dashtid/dicom-fuzzer/actions/workflows/ci.yml/badge.svg)](https://github.com/Dashtid/dicom-fuzzer/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/Dashtid/dicom-fuzzer/branch/main/graph/badge.svg)](https://codecov.io/gh/Dashtid/dicom-fuzzer)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Dashtid/dicom-fuzzer/badge)](https://scorecard.dev/viewer/?uri=github.com/Dashtid/dicom-fuzzer)
[![Python Versions](https://img.shields.io/pypi/pyversions/dicom-fuzzer.svg)](https://pypi.org/project/dicom-fuzzer/)
[![PyPI](https://img.shields.io/pypi/v/dicom-fuzzer.svg)](https://pypi.org/project/dicom-fuzzer/)
[![License: MIT](https://img.shields.io/badge/License-MIT-lightgrey.svg)](LICENSE)

## Installation

### For end users (run the CLI)

Install from PyPI as an isolated tool so `dicom-fuzzer` is on your PATH everywhere, without polluting your system Python:

```bash
# Recommended: uv (fast, modern)
uv tool install dicom-fuzzer

# Alternative: pipx (same idea, different manager)
pipx install dicom-fuzzer

# Alternative: pip into the active environment
pip install dicom-fuzzer
```

After installation:

```bash
dicom-fuzzer --help
```

Optional extras are needed only for specific features (target process monitoring, Windows crash dump parsing, HTML reports, GUI automation):

```bash
uv tool install "dicom-fuzzer[all]"
# or, if you only need specific extras:
pip install dicom-fuzzer psutil minidump tqdm rich matplotlib jinja2 pywinauto
```

### For contributors (develop the code)

```bash
git clone https://github.com/Dashtid/DICOM-Fuzzer.git
cd DICOM-Fuzzer
uv sync
source .venv/Scripts/activate  # Windows/Git Bash
# source .venv/bin/activate    # macOS/Linux
```

To run your local checkout as a global CLI while developing:

```bash
uv tool install --editable .
```

Source edits take effect immediately with no reinstall.

## Quick Start

```bash
# Generate 100 fuzzed DICOM files
dicom-fuzzer input.dcm -c 100 -o ./artifacts/output

# Fuzz and test against a target viewer
dicom-fuzzer input.dcm -c 1000 -t ./viewer.exe --timeout 10

# Generate seed corpus for AFL/WinAFL
dicom-fuzzer generate-seeds input.dcm -c 500 -o ./seeds/
```

## Features

### Fuzzing

- **Format fuzzing (production):** 24 single-file mutation strategies targeting VR types, pixel data, sequences, encoding, and modality-specific tags
- Modality-specific fuzzers: CT/MR calibration, NM, PET, RT Dose, RT Structure Set, Segmentation, Secondary Capture, Encapsulated PDF, Pixel Reencoding
- Target scope filtering (`--target-type viewer|web|pacs`)
- Multiframe fuzzing (WIP): 10 strategies for enhanced imaging objects -- functional groups, frame counts, dimension indices
- Series/study fuzzing (WIP): cross-series geometry, temporal ordering, patient consistency
- Network protocol fuzzing (WIP): PDU construction, DIMSE commands, state machine, TLS

### Supported SOP classes

Seed corpus plus dedicated fuzzer coverage (mutations are only
meaningful when both exist):

| Modality          | SOP Class UID                 | Modality fuzzer     |
| ----------------- | ----------------------------- | ------------------- |
| CT Image          | 1.2.840.10008.5.1.4.1.1.2     | `calibration`       |
| MR Image          | 1.2.840.10008.5.1.4.1.1.4     | `calibration`       |
| NM Image          | 1.2.840.10008.5.1.4.1.1.20    | `nuclear_medicine`  |
| PET Image         | 1.2.840.10008.5.1.4.1.1.128   | `pet`               |
| RT Dose           | 1.2.840.10008.5.1.4.1.1.481.2 | `rt_dose`           |
| RT Structure Set  | 1.2.840.10008.5.1.4.1.1.481.3 | `rt_structure_set`  |
| Segmentation      | 1.2.840.10008.5.1.4.1.1.66.4  | `segmentation`      |
| Secondary Capture | 1.2.840.10008.5.1.4.1.1.7     | `secondary_capture` |
| Encapsulated PDF  | 1.2.840.10008.5.1.4.1.1.104.1 | `encapsulated_pdf`  |

Generic fuzzers (`structure`, `metadata`, `header`, `preamble`,
`sequence`, `dictionary`, etc.) run across all modalities.

### Analysis

- Automatic crash detection and deduplication
- Crash triaging with severity and exploitability scoring
- Test case minimization
- Corpus management
- Markdown campaign reports with per-strategy hit rates

### Integration

- CLI with 14 subcommands
- Python API for custom workflows
- Docker container for isolated execution
- CI/CD compatible

## CLI Reference

```bash
dicom-fuzzer --help                 # Main fuzzing campaign
dicom-fuzzer target --help          # Target testing
dicom-fuzzer generate-seeds --help  # Seed corpus generation
dicom-fuzzer sanitize --help        # Strip PHI from seed files
dicom-fuzzer replay --help          # Decompose fuzzed files
dicom-fuzzer report --help          # Report generation
dicom-fuzzer triage --help          # Crash triaging
dicom-fuzzer corpus --help          # Corpus management
```

Run `dicom-fuzzer --help` (and `dicom-fuzzer <subcommand> --help`) for the authoritative command reference.

## Python API

```python
from dicom_fuzzer.core.mutation.mutator import DicomMutator
import pydicom

mutator = DicomMutator()
dataset = pydicom.dcmread("input.dcm")

for i in range(100):
    fuzzed = mutator.apply_mutations(dataset)
    fuzzed.save_as(f"artifacts/output/fuzz_{i:04d}.dcm")
```

## Project Structure

```text
dicom-fuzzer/
├── dicom_fuzzer/    # Main package (installed by `pip install dicom-fuzzer`)
│   ├── attacks/     # Attack modules (format, series, network, multiframe)
│   ├── cli/         # Command-line interface (14 subcommands)
│   ├── core/        # Engine, mutation, corpus, crash analysis, harness, reporting
│   └── utils/       # Logging, hashing, identifiers
├── tests/           # Test suite
├── docs/            # Documentation
├── examples/        # Reference targets + maintainer tooling (not installed)
└── artifacts/       # Runtime output (gitignored)
```

`examples/` holds the fo-dicom network harness (DIMSE SCP the network fuzzer points at) and the pydicom smoke analyzer (post-campaign corpus QA). See [examples/README.md](examples/README.md).

## Documentation

- [Quick Start Guide](docs/QUICKSTART.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Contributing](CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)

## Security

This tool is for authorized security testing only. See [SECURITY.md](SECURITY.md).

## License

MIT - see [LICENSE](LICENSE)
