2 unstable releases

0.2.0 Nov 5, 2024
0.1.0 Oct 19, 2023

#1311 in Parser implementations

Download history 3/week @ 2024-09-23 3/week @ 2024-09-30 113/week @ 2024-11-04

113 downloads per month

Apache-2.0

18KB
311 lines

usnrs - USN Journal parser

This project is a parser for $UsnJrnl:$J files, which tracks file system changes at the file level. It only handles USN_RECORD_V2 records, which are the most common in our experience.

The tool can also optionally use an MFT file to try to reconstruct full paths to files mentioned in the journal.

Other similar projects:

This one is written in Rust, and exposes both a binary (usnrs-cli) to process USN Journal files, and a library (usnrs) which can be used in other applications.

Installation

You will need a Rust compiler and the Cargo package manager to build this project. Both can be automatically installed by rustup.

Alternatively, you can use nix-shell to automatically setup all this.

Building the project is as simple as running:

$ cargo build --features=usnrs-cli --release

Usage

The usnrs-cli binary can be used to parse $UsnJrnl:$J files and output the extracted USN records. The USN Journal file is a sparse file, which means that it is usually mostly empty (filled with 0x00 bytes).

Some forensics acquisition tools are able to only extract the non-empty data, while others acquire the full, mostly empty file. usnrs-cli supports both types of files.

Basic usage

$ usnrs-cli PATH-TO-USNJRNL-J

Outputs the file in a format similar to USN-Journal-Parser, Timestamp | Filename | Attributes | Reasons.

Bodyfile format output

$ usnrs-cli -f bodyfile PATH-TO-USNJRNL-J

Outputs the file in Body file format (version 3.X), for use with mactime or other tools.

Full path reconstruction

If you also have the Master File Table file for the disk from which you extracted the USN Journal, you can give it as an option to reconstruct the full path to each file.

$ usnrs-cli --mft PATH-TO-MFT PATH-TO-USNJRNL-J

Path reconstruction is based on the MFT entry number stored in the USN record. Simple checks are in place to prevent the tool from giving out false paths when dealing with reallocated entry numbers (when dealing with deleted files for example).

Specifying the start offset manually

Because USN Journal files usually start with a bunch of null bytes, it can take some time before usnrs-cli starts outputting results. You can manually specify the offset at which your first USN entry starts with --start.

$ usnrs-cli --start OFFSET PATH-TO-USNJRNL-J

Dependencies

~10–17MB
~183K SLoC