Forensic triage instrument for binary-level video container structure analysis.
ContainerForensics is a forensic triage instrument that performs binary-level container structure analysis to identify video files warranting further forensic examination. It does not authenticate media content.
It examines the atom/box hierarchy, edit list structure, chunk offset consistency, interleaving patterns, and internal metadata of MP4/MOV/AVI files — surfacing structural features that an examiner should review. A triage finding is a prompt for further examination, not an authentication opinion.
Part of the RK Tools suite by Rami Khashmel.
Forensic examiners examining video container provenance currently have no open-source tool that:
- Renders the MPEG-4 atom hierarchy as a forensically interpretable structure map
- Flags specific container anomalies with documented evidentiary significance
- Cross-validates declared recording parameters against internally consistent device-class signatures
- Produces output formatted for inclusion in forensic reports
FFmpeg surfaces container metadata as raw terminal output that cannot be included directly in a court report. ContainerForensics produces structured forensic exhibits from the same underlying data.
ContainerForensics accepts MP4, MOV, MXF, and AVI files and performs binary-level container structure analysis:
| Analysis | What It Examines |
|---|---|
| Atom Structure Mapping | Complete MPEG-4 box/atom hierarchy visualised as a structure map |
| Edit List Examination | Presence and content of edit list boxes indicating post-capture modification |
| Chunk Offset Consistency | Chunk offset table validation against expected single-generation recording patterns |
| Metadata Cross-Validation | Declared recording parameters compared against device-class signature database |
| Interleaving Analysis | Audio/video interleaving pattern consistency with stated capture device |
Each analysis produces a forensic exhibit. Anomalies are annotated with their evidentiary significance and the published standard they deviate from.
- Visual container structure map (SVG/PNG)
- Anomaly flag report with forensic interpretation per finding
- Metadata cross-validation table
- Device-class signature comparison output
- All outputs formatted for inclusion in forensic triage documentation and examiner review.
- Python 3.8 or later (required)
- Graphviz (optional — required only for the visual atom map SVG; the tool degrades gracefully without it)
- Python dependencies installed automatically via pip
ContainerForensics performs binary parsing directly using Python's struct module. FFmpeg is not required.
pip install containerforensicsOr clone and install locally:
git clone https://github.com/ramikhashmel/ContainerForensics.git
cd ContainerForensics
pip install -r requirements.txtAnalyse a video file:
containerforensics --input evidence.mp4 --output report/Run a specific analysis only:
containerforensics --input evidence.mp4 --output report/ --analysis atoms
containerforensics --input evidence.mp4 --output report/ --analysis editlist
containerforensics --input evidence.mp4 --output report/ --analysis metadataFull options:
containerforensics --helpAfter running ContainerForensics, the output directory contains:
report/
├── index.html ← Main annotated report (open in browser)
├── atom_map.svg ← Visual container structure map
├── anomalies.json ← Structured anomaly flag log
├── metadata_table.html ← Cross-validation table
├── device_comparison.html ← Device-class signature comparison
└── methodology.md ← Cited methodology documentation
ContainerForensics is designed for use within a SWGDE-aligned forensic methodology. Container structure analysis is typically the first analytical step on any video evidence file — it establishes provenance before content-level analysis begins.
All tool outputs include the tool name, version number, parameters used, and the date and time of analysis — fields required for forensic report documentation.
This tool does not produce a verdict. It produces documented findings for examiner interpretation.
ContainerForensics implements analysis methods from published peer-reviewed research and technical standards:
- Hall, C. (2015). Analysis of MP4 Container File Format Forensics. University of Denver. (Required IAI CFVE reference)
- ISO/IEC 14496-12. Base Media File Format Specification.
SWGDE alignment: methodology follows SWGDE Technical Overview of Digital Video Files and SWGDE Best Practices for Data Acquisition from Digital Video Recorders.
ContainerForensics is part of the RK Tools suite for multimedia forensic authentication:
| Tool | Purpose |
|---|---|
| SyntheticTrace | Multi-signal deepfake detection |
| ForensicELA | Batch Error Level Analysis |
| VoiceForge-Detect | Audio deepfake detection |
| ContainerForensics | MPEG-4 container structure analysis |
| DeepArtifactDB | Synthetic media artifact reference database |
Contributions from forensic practitioners, researchers, and developers are welcome.
- Bug reports: Open an issue with a description of the problem and the input that produced it
- Feature requests: Open an issue describing the forensic use case the feature addresses
- Pull requests: Please include a description of the change and, where applicable, the academic or standards basis for any new detection methodology
Rami Khashmel — Forensic Video Examiner, AI-Generated & Synthetic Media Authentication
Website: ramikhashmel.github.io RK Tools: ramikhashmel.github.io/tools
MIT License — see LICENSE for details.
You are free to use, modify, and distribute this tool in both personal and commercial forensic investigations. Attribution appreciated but not required.
ContainerForensics is part of RK Tools — open-source forensic instrumentation for the multimedia authentication community.