Crate usb_forensic 

usb-forensic — the USB device-history correlation engine.

A thin orchestration / correlation crate — it parses no raw format itself. It consumes the fleet’s reader crates, normalizes their output into one uniform USB-history Claim, and cross-correlates values across sources, grading each by how well its independent storage containers agree (Consistency) so an examiner can tell a reliable first-connected time from a partial or contradicted one. Every finding is an observation (“consistent with …”), a forensicnomicon::report::Finding; the examiner draws the conclusions.

What runs today

• Correlation core: correlate() / correlate_sources → DeviceHistory with per-attribute Consistency + retained provenance; to_jsonl output.
• Findings: audit → forensicnomicon findings (conflicts graded, MITRE T1070.006 consistent-with; corroborations as reliable history).
• Sources: PeripheralSource (peripheral-core — setupapi.dev.log, SYSTEM-hive Enum\{USBSTOR,SCSI,USB} device keys, and Linux kernel logs) and LnkSource (lnk-core — the volume-serial file join).
• CLI: the usb4n6 binary runs the pipeline over setupapi, a SYSTEM hive, .lnk, jump-list, and Linux syslog evidence (type auto-detected).

Correlation across the setupapi device serial and the LNK volume serial awaits the registry MountedDevices bridge; event-log and macOS sources follow. See docs/roadmap.md and docs/feature-parity.md.

The wedge (why it is not a USB Detective clone)

Headless, library-embeddable, pipeline-native, and reproducible — every reported value re-derivable from hive → key → raw bytes → decoding rule. It targets the pipeline operator (lab automation, Velociraptor/KAPE), not the GUI examiner. See the README for the full, adversarially-pressure-tested positioning.

Re-exports

pub use correlate::correlate;

pub use correlate::to_jsonl;

pub use correlate::CorrelatedAttribute;

pub use correlate::DeviceHistory;

pub use correlate::ProvenancedValue;

pub use docx::render_docx;

pub use model::ArtifactContainer;

pub use model::Attribute;

pub use model::Claim;

pub use model::DeviceKey;

pub use model::Provenance;

pub use model::SourceKind;

pub use model::Value;

pub use pdf::render_pdf;

pub use reconcile::canonicalize_mounted_volumes;

pub use reconcile::reconcile_volume_serials;

pub use render::format_epoch;

pub use render::render_accessed_files;

pub use render::render_report;

pub use render::render_table;

pub use report::audit;

pub use source::correlate_sources;

pub use source::HistorySource;

pub use sources::apple_ipod::parse_ipod_plist;

pub use sources::apple_ipod::AppleDevice;

pub use sources::apple_ipod::AppleIPodSource;

pub use sources::device_image::analyse_device_image;

pub use sources::device_image::export_mbr_hex;

pub use sources::device_image::parse_boot_sectors;

pub use sources::device_image::DeviceImage;

pub use sources::device_image::DeviceImageSource;

pub use sources::device_image::EncryptionKind;

pub use sources::emdmgmt::EmdMgmtSource;

pub use sources::jumplist::JumpListArtifact;

pub use sources::jumplist::JumpListSource;

pub use sources::kernel_pnp::kernel_pnp_events;

pub use sources::kernel_pnp::KernelPnpEvent;

pub use sources::kernel_pnp::KernelPnpSource;

pub use sources::lnk::LnkArtifact;

pub use sources::lnk::LnkSource;

pub use sources::macos_unified_log::parse_unified_log;

pub use sources::macos_unified_log::MacUnifiedLogSource;

pub use sources::macos_unified_log::UsbEnumeration;

pub use sources::macos_usb::parse_system_profiler;

pub use sources::macos_usb::MacUsbDevice;

pub use sources::macos_usb::MacUsbSource;

pub use sources::mountpoints2::MountPoints2Source;

pub use sources::partition_diag::PartitionDiagSource;

pub use sources::peripheral::PeripheralSource;

pub use sources::volume_cache::VolumeCacheSource;

pub use timeline::super_timeline;

pub use timeline::timeline_to_jsonl;

pub use timeline::TimelineEvent;

pub use tz::normalize_local_clocks;

Modules

correlate

The correlation core: group atomic Claims into per-device histories and grade each attribute’s cross-source Consistency.

docx

Native DOCX export — the court-ready report as an Office Open XML .docx, with no dependency: a .docx is a ZIP of a few XML parts, so this writes a minimal stored (uncompressed) ZIP by hand. The report text comes from render_report; each line becomes a Word paragraph.

model

The source-agnostic domain model: atomic claims a source adapter emits, which the correlation core groups and grades.

pdf

Native PDF export — the court report as a multi-page PDF with no dependency.

reconcile

Volume-serial reconciliation: attribute volume-keyed claims (LNK/jump-list file access) to the physical device that carries that volume — the file-to-device link.

render

Human view: a readable results grid (one block per device). The machine view is to_jsonl — faithful and round-trippable; this view renders for eyes (datetimes formatted, consistency labelled, values unwrapped).

report

Fleet-standard output: turn correlated DeviceHistory into forensicnomicon::report::Findings so Issen and a future GUI render USB findings uniformly with every other analyzer.

source

The HistorySource contract: the stable integration point every reader-crate adapter implements.

sources

Reader-crate adapters: pure mappings from each fleet reader’s already-decoded output into the source-agnostic Claim model.

timeline

Aggregate super-timeline: a single chronological stream of every timestamped event across all correlated devices — the cross-device view an examiner scans to see what happened when, regardless of which device or which source recorded it.

tz

Timezone normalization — correct host-local timestamps to UTC.

Enums

Consistency

The cross-source agreement grade for one reported attribute (first-connected time, volume name, serial, …) — the defining output of the correlation engine.