v1.2.0 — USN Journal Rewind

USN Journal Rewind

ResidentReaper now reconstructs historically accurate parent paths for every USN Journal event — not just the file's current location on disk.

The Problem

When a file is deleted or renamed after a USN event is recorded, standard MFT-based path resolution shows where the file ended up, not where it was. Forensic tools including MFTECmd mark these as PathUnknown. This hides staging directories, exfiltration paths, and malware drop locations.

The Solution

v1.2.0 implements true reverse-chronological rewind — the same technique described in CyberCX's USN Journal Rewind research:

• Collects all journal records, then walks newest → oldest
• RenameOldName events overwrite the path map, exposing the pre-rename name for all earlier records
• All other events use or_insert — first-seen going backwards = most recent state
• Each record's ParentPath is resolved before updating the map, so it reflects filesystem state at the exact moment of the event
• MFT supplements the rewind map for entries that never appeared in the journal

Results (328,613 records, real-world sample)

Metric	Value
Agreement with usnjrnl_rewind.py (CyberCX)	98.62%
Records resolved that py cannot	+4,547 (deleted parents in journal, not MFT)
Records py resolves that we cannot	0
Remaining differences	4 (rename timing edge case)

New Flag

--raw    Disable rewind — fall back to MFT-only path resolution (pre-v1.2 behavior)

New Files

• ARCHITECTURE.md — full module map, data flow diagrams, CSV column specs
• CLAUDE.md — project constraints and algorithm invariants for AI-assisted development

Usage

# Rewind active by default — resolves historical paths
ResidentReaper usn -f $J

# Rewind + MFT — also writes MFT CSV, fills entries absent from journal
ResidentReaper usn -f $J -m $MFT

# Disable rewind — MFT-only, current state (pre-v1.2 behavior)
ResidentReaper usn -f $J -m $MFT --raw

Full Changelog: v1.1.0...v1.2.0