ufedlib-py 1.0.0

ufedlib_py is Python port of UFEDLib (.ufdr/report.xml parser)

UFEDLib_py

UFEDLib_py library parses Cellebrite UFED/UFDR output files into Python dataclasses and provides a high-level ReportData object for easier access and processing of forensic report data.

inspired by or complementary to the C# UFEDLib project originally created by Sönke Eilers [(https://github.com/SEilers/UFEDLib)]. Thanks to the author for the outstanding C# foundation!

Features

• Reads Cellebrite UFED outputs:
  • .ufdr files (zip containing report.xml)
  • raw report.xml
• Scans available model types
• Parses a single model type or all models + metadata (ReportData)
• Single-pass parse_all for large UFDR files
• CLI + Python API

Install

Editable install (for development):

python -m pip install -e .

Install from a built wheel:

python -m pip install dist\ufedlib_py-1.0.0-py3-none-any.whl

CLI

Scan model types:

ufedlib_py scan --input "C:\path\to\case.ufdr"

Parse a model type:

ufedlib_py parse --input "C:\path\to\case.ufdr" --model "Contact"

Parse all supported models + metadata:

ufedlib_py parse-all --input "C:\path\to\case.ufdr" --json

Limit parse-all to specific models and log progress:

ufedlib_py parse-all --input "C:\path\to\case.ufdr" --model "Call" --model "Contact" --progress-every 1000

Include unknown model types detected in the file:

ufedlib_py parse-all --input "C:\path\to\case.ufdr" --include-unknown-models

Python API

Parse all models + metadata:

from ufedlib_py import parse_all

def on_progress(model_type: str, count: int) -> None:
    print(f"{model_type}: {count}")

report = parse_all(
    r"C:\path\to\case.ufdr",
    model_types=["Call", "Contact"],
    progress_callback=on_progress,
    progress_every=1000,
)

print(report.DeviceInfo)
print(len(report.Models.get("Call", [])))

Parse a single model:

from ufedlib_py import parse_data

calls = parse_data(r"C:\path\to\case.ufdr", "Call")

Discover models:

from ufedlib_py import scan_models, get_supported_models

all_in_file = scan_models(r"C:\path\to\case.ufdr")
supported = get_supported_models()

Performance tips

• Use model_types in parse_all to limit work.
• parse_all uses a single-pass XML stream for large files.
• Use progress_every for visibility on long-running parses.

Model coverage

List models detected in a report:

ufedlib_py scan --input "C:\path\to\case.ufdr"

Check which models are supported by this library:

from ufedlib_py import get_supported_models, get_unsupported_models

supported = get_supported_models()
unsupported = get_unsupported_models(r"C:\path\to\case.ufdr")

Schema notes

• UFED XML often stores scalar values inside <field><value>...</value></field>.
• Nested <model> blocks are parsed into typed dataclasses when a type attribute is present.
• Some nested fields are post-processed into dictionaries and lists for easier consumption.

Troubleshooting

• Progress errors or missing callbacks: reinstall the package in the active venv using python -m pip install -e . to ensure you are running the latest code.
• Model not registered: confirm the model appears in scan output and is included in get_supported_models().
• Large file performance: use parse_all(..., model_types=[...]) to limit work.

Build a wheel

python -m pip install build
python -m build