USNJournal2EventLog v0.0.5 (pre-alpha)

[OnyxOmega]

v0.0.5 — Initial source-available preview

First public, source-available preview of USNJornal2EventLog — a headless
Windows service that tails the NTFS USN Change Journal and writes enriched,
structured file-change events to a custom FileSystem Windows Event Log, built
as a DFIR telemetry source that backstops Sysmon and carries retroactive journal
history.

⚠️ Preview / early-stage. Run from source on a disposable VM, not a
production host — this service manipulates the live USN journal and Windows
Event Log. No signed binary is provided yet (see Installation).

Highlights

• USN journal capture with V2/V3/V4 record-format negotiation and
  boundary-correct, cached path resolution.
• Multi-drive monitoring — one journal-reader per fixed NTFS/ReFS volume,
  with per-drive volume serial in each event.
• --all mode — monitor every change on every drive (CLI flag and GUI
  checkbox), persisted to config.
• Roots + excludes path model — store only top-most monitored roots plus
  carve-out excludes; tiny config, auto-covers new sub-dirs and new user
  profiles (portable across machines).
• Forensic enrichment per event — TargetFilename, UtcTime (Sysmon-format),
  Reason, Usn, JournalId, host context (Hostname/FQDN/Domain/MachineGuid/
  MachineSID/SourceIP/MAC/OSBuild), and per-drive VolumeSerial.
• Distinct Event IDs by category (100 Create, 101 Modify, 102 Delete,
  103 Rename, 104 SecurityChange, 105 Other, 106 RangeChange).
• EvtxECmd maps (Events 100–106) that regex-extract every field into
  Timeline Explorer columns for side-by-side Sysmon correlation.
• Event Log Explorer support via positional {PARAM[n]} fields.
• Event-log sizing — sets the FileSystem log to ~4 GB on first creation;
  interactive prompt to enlarge if below the 1 GB recommended minimum.
• Rolling archives to C:\FileSystem_Archives with configurable per-log
  rotation (default 3.5 GB) and total cap (default 60 GB, FIFO eviction).
• Configuration GUI — drive tree with three-state markers
  ([X] monitored / [-] excluded / [ ] off), "Mark to Exclude" button,
  editable rotation/storage fields, and folder search.

Installation (run from source)

No signed executable is published in this release — run from source:

1. Windows with Python 3 and pywin32 installed.
2. Get the code: clone the repo or download the source zip from this release.
3. Configure: launch the GUI (python usn_monitor.py) to pick monitored roots
   and excludes, or edit monitor_config.json.
4. Test first (recommended): set USN_VERBOSE=1 && python usn_monitor.py debug
5. Install as a service:
   python usn_monitor.py --startup delayed install then ... start
   (add --all to monitor every drive).

For EvtxECmd/Timeline Explorer integration, copy the maps/*.map files into
EvtxECmd's Maps folder. See DEPLOYMENT.md for fleet rollout and WEF→WEC.

Known limitations

• No signed binary yet — endpoint security may flag running from source; a
  PyInstaller-frozen, Authenticode-signed .exe is planned for a later release.
• Classic event format — EventData renders as a single block; field access
  is by regex (EvtxECmd) or positional {PARAM[n]} (Event Log Explorer). Named
  EventData fields await an instrumentation-manifest build (planned).
• 106 RangeChange only occurs on ReFS volumes (none on NTFS — expected).
• Tested on a small number of systems; treat as preview-quality.

Schema

Event field contract: SCHEMA_VERSION 1.0. Field order/names are stable for
the 1.x line; changes will bump the version and update the maps accordingly.

License

Source-available under the PolyForm Noncommercial License 1.0.0. Free for
noncommercial use (including nonprofit, education, and government). Commercial
use requires a separate license — see COMMERCIAL.md.

---

Feedback and real-world results welcome via Issues and Discussions. Report
security issues privately — see SECURITY.md.

---

This discussion was created from the release USNJournal2EventLog v0.0.5 (pre-alpha).