Windows execution evidence is spread across independent binary artifacts. Analysts often have to export and correlate them with separate tools before reconstructing host activity.
Windows Forensic Timeline Correlator
A command-line Python engine that parses disparate Windows artifacts, normalizes timestamps, correlates execution activity, and exports reviewable timelines.
30-second summary
WFCR parses, normalizes, and correlates five core Windows artifact families through a modular command-line pipeline, then exports unified JSON and CSV timelines.
The engine reduces manual context switching and turns artifact-specific timestamps, executable records, and identities into an analyst-readable event chain.
System architecture
wfcr.py owns argument parsing, file validation, configuration state, and the end-to-end pipeline.
mft_parser, amcache_parser, shim_parser, bam_parser, and srum_parser isolate artifact-specific extraction from shared timeline logic.
time_utils.py converts Windows FILETIME, Unix epochs, and local offsets into UTC-aware timestamp objects.
schema.py defines stable event contracts. correlator.py creates execution chains and reporter.py exports JSON and CSV output.
How it works
Artifact coverage
| Source | Evidence | Analytical role |
|---|---|---|
| NTFS $MFT | File and timestamp records | Reconstruct file activity and compare MFT timestamp attributes |
| Amcache | Program execution metadata | Correlate known executable activity with host timelines |
| Shimcache | Application compatibility records | Identify executables associated with compatibility telemetry |
| BAM / DAM | Background activity metadata | Trace program execution and activity context |
| SRUM | JET/ESE resource utilization records | Map database IDs to executables and identify resource activity |
Core correlation models
Windows FILETIME counts 100-nanosecond intervals since 1601. WFCR removes the 1601-to-1970 epoch offset to produce a Unix timestamp.
The engine compares $STANDARD_INFORMATION and $FILE_NAME modification timestamps and flags meaningful differences.
Events from the same executable are grouped when adjacent activity falls within the configured temporal window.
Analytical capabilities
Windows FILETIME values, Unix epochs, and offset-aware timestamps are converted into one reviewable schema.
A sliding temporal window groups events from the same executable into coherent activity chains.
Timestamp differences between MFT $STANDARD_INFORMATION and $FILE_NAME attributes can indicate metadata tampering.
Artifact identity fields can be inspected for unmapped Security Identifiers and incomplete account context.
The SruDbIdMapTable maps internal database identifiers to readable executable names and security IDs.
Aggregated timelines and anomaly indicators are available as JSON for automation and CSV for analyst review.
Engineering decisions
Each artifact family owns its extraction logic instead of forcing one parser to understand every binary layout.
Why: Different artifact formats change independently and should not destabilize shared normalization.Every detector receives timestamp, executable identity, context, and source fields through a common event contract.
Why: Normalized schemas make correlation and reporting predictable.The SRUM parser reads the database structure rather than relying solely on hard-coded record offsets.
Why: ESE column layouts can differ across Windows versions and builds.Parsing and correlation produce structured findings before JSON and CSV formatting.
Why: Analysts can use one timeline for both human review and downstream processing.Engineering quality
- Automated testing: The parser and correlation components are covered through Python tests.
- Continuous integration: GitHub Actions validates the project through a Windows-native CI runner and a Python version matrix.
- Packaging: The CLI is structured as an installable Python package with a
pyproject.tomlconfiguration. - CLI presentation: Click-based command routing and Rich terminal output provide an analyst-focused interface.
- Dependency resilience: CI includes an import guard and mocked parser dependencies for test environments that cannot load native parser components.
Problems solved
Artifact layouts differ across Windows versions
Problem: Hard-coded ESE offsets can stop working when the internal column layout changes.
Fix: WFCR reads the relevant database structure at runtime before interpreting records.
Lesson: Binary parsers should encode schemas and layouts, not assume every Windows build uses identical offsets.
Independent timestamps hide relationships
Problem: FILETIME, Unix epoch, and application-specific records are not immediately comparable.
Fix: Time conversion occurs before timeline correlation and export.
Lesson: Timestamp normalization belongs before analysis so every downstream component uses the same reference.
CI dependencies vary by platform
Problem: Some native parser dependencies are unsuitable for every headless CI configuration.
Fix: The tests use guarded imports and mocked dependencies when native components are unavailable.
Lesson: Validation infrastructure should test business logic without silently hiding parser failures.
Limitations
Findings depend on whether the source artifacts exist, are intact, and were captured from the relevant system.
Temporal clustering is a correlation technique, not proof that each grouped event represents a malicious or causal sequence.
MFT, Registry, and ESE findings should be verified against the original evidence and supporting host context.
How I built it
I modeled the engine around the investigation workflow: isolate each artifact parser, convert every source into a shared UTC event contract, correlate related execution activity, preserve anomalous evidence, and export both machine-readable and analyst-readable results.
Project outcome