Projects / Windows DFIR

Windows Forensic Timeline Correlator

A command-line Python engine that parses disparate Windows artifacts, normalizes timestamps, correlates execution activity, and exports reviewable timelines.

PythonNTFS MFTAmcacheShimcacheBAM / DAM SRUM / ESERegistry forensicsTimeline correlationJSONCSVGitHub Actions

30-second summary

Problem

Windows execution evidence is spread across independent binary artifacts. Analysts often have to export and correlate them with separate tools before reconstructing host activity.

What I built

WFCR parses, normalizes, and correlates five core Windows artifact families through a modular command-line pipeline, then exports unified JSON and CSV timelines.

Why it matters

The engine reduces manual context switching and turns artifact-specific timestamps, executable records, and identities into an analyst-readable event chain.

System architecture

CLI controller

wfcr.py owns argument parsing, file validation, configuration state, and the end-to-end pipeline.

Artifact parsers

mft_parser, amcache_parser, shim_parser, bam_parser, and srum_parser isolate artifact-specific extraction from shared timeline logic.

Normalization

time_utils.py converts Windows FILETIME, Unix epochs, and local offsets into UTC-aware timestamp objects.

Correlation and export

schema.py defines stable event contracts. correlator.py creates execution chains and reporter.py exports JSON and CSV output.

How it works

Windows artifacts
Dedicated parsers
Time normalization
Schema contracts
Execution correlation
Anomaly flags
JSON / CSV

Artifact coverage

SourceEvidenceAnalytical role
NTFS $MFTFile and timestamp recordsReconstruct file activity and compare MFT timestamp attributes
AmcacheProgram execution metadataCorrelate known executable activity with host timelines
ShimcacheApplication compatibility recordsIdentify executables associated with compatibility telemetry
BAM / DAMBackground activity metadataTrace program execution and activity context
SRUMJET/ESE resource utilization recordsMap database IDs to executables and identify resource activity

Core correlation models

FILETIME normalization TUnix=TFT-116444736000000000107

Windows FILETIME counts 100-nanosecond intervals since 1601. WFCR removes the 1601-to-1970 epoch offset to produce a Unix timestamp.

MFT timestamp anomaly Ats=1if |tmSI-tmFN|>τ0otherwise

The engine compares $STANDARD_INFORMATION and $FILE_NAME modification timestamps and flags meaningful differences.

Execution-chain clustering exec(ei)=exec(ej)∧0≤|tj-ti|≤Δt

Events from the same executable are grouped when adjacent activity falls within the configured temporal window.

Analytical capabilities

UTC timeline normalization

Windows FILETIME values, Unix epochs, and offset-aware timestamps are converted into one reviewable schema.

Execution-chain grouping

A sliding temporal window groups events from the same executable into coherent activity chains.

MFT timestomp detection

Timestamp differences between MFT $STANDARD_INFORMATION and $FILE_NAME attributes can indicate metadata tampering.

Security identifier context

Artifact identity fields can be inspected for unmapped Security Identifiers and incomplete account context.

SRUM name resolution

The SruDbIdMapTable maps internal database identifiers to readable executable names and security IDs.

Machine and analyst exports

Aggregated timelines and anomaly indicators are available as JSON for automation and CSV for analyst review.

Engineering decisions

Separate parser responsibilities

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.
Define a strict timeline schema

Every detector receives timestamp, executable identity, context, and source fields through a common event contract.

Why: Normalized schemas make correlation and reporting predictable.
Use runtime-aware ESE handling

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.
Separate export from analysis

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.toml configuration.
  • 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

Artifact availability

Findings depend on whether the source artifacts exist, are intact, and were captured from the relevant system.

Correlation confidence

Temporal clustering is a correlation technique, not proof that each grouped event represents a malicious or causal sequence.

Analyst review

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

A unified starting point for Windows host timeline review.