https://github.com/securityronin/usb-forensic
USB device-history forensic correlation engine — reconstructs USB connection history from Windows registry/SetupAPI/event-log/LNK artifacts and scores cross-source timestamp consistency. Pipeline-native, reproducible, panic-free.
https://github.com/securityronin/usb-forensic
dfir digital-forensics forensics incident-response registry rust timeline usb usb-forensics windows
Last synced: 28 days ago
JSON representation
USB device-history forensic correlation engine — reconstructs USB connection history from Windows registry/SetupAPI/event-log/LNK artifacts and scores cross-source timestamp consistency. Pipeline-native, reproducible, panic-free.
- Host: GitHub
- URL: https://github.com/securityronin/usb-forensic
- Owner: SecurityRonin
- License: other
- Created: 2026-07-09T13:54:57.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-07-10T01:01:49.000Z (30 days ago)
- Last Synced: 2026-07-10T01:09:46.698Z (30 days ago)
- Topics: dfir, digital-forensics, forensics, incident-response, registry, rust, timeline, usb, usb-forensics, windows
- Language: Rust
- Size: 677 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Roadmap: docs/roadmap.md
Awesome Lists containing this project
README
# usb-forensic
[](https://github.com/SecurityRonin/usb-forensic/actions)
[](https://www.rust-lang.org)
[](https://github.com/rust-secure-code/safety-dance)
[](LICENSE)
[](https://github.com/sponsors/h4x0r)
**The first USB-history correlation engine built for pipelines and courtrooms rather than a viewer window — USB Detective-grade Windows artifact depth, running headless on any OS at fleet scale, with every timestamp traceable to its raw bytes and every conclusion re-derivable by anyone, including the other side's expert.**
> **Status: working alpha.** The correlation core, two sources (`setupapi.dev.log` via
> `peripheral-core`, `.lnk` via `lnk-core`), `forensicnomicon` findings output, and the
> `usb4n6` CLI all run and are tested. The registry decoder (USBSTOR/SCSI/USB) is
> [validated and in review](https://github.com/SecurityRonin/peripheral-forensic/pull/1);
> event-log, macOS/Linux, and court-report output are next (`docs/roadmap.md`,
> `docs/feature-parity.md`). `Cargo.toml` keeps `publish = false` until the source set
> and validation are release-ready; crates.io / docs.rs / coverage badges join then.
## Run it
```console
$ usb4n6 path/to/setupapi.dev.log path/to/RecentItem.lnk
{"device":"7&12a3b4c5&0&0000","attributes":[{"attribute":"FirstConnected","consistency":"SingleSource","values":[{"value":{"Timestamp":1681760520},"provenance":{"source":"SetupApi","locator":"setupapi.dev.log:27"}}]}]}
{"device":"DEAD-BEEF","attributes":[{"attribute":"AccessedFile","consistency":"SingleSource","values":[{"value":{"Text":"E:\\payload.exe"},"provenance":{"source":"Lnk","locator":"RecentItem.lnk"}}]}]}
usb4n6: 6 device(s) from 6 source record(s), 0 finding(s)
```
Each device history is one JSONL object carrying every value with its source and
locator; findings (cross-source conflicts and corroborations) print to stderr.
## What this is
A thin **orchestration / correlation** crate — it parses no raw format itself. It
consumes the fleet's already-built reader crates, normalizes their output into one
uniform USB-device-history event, and cross-correlates the timestamps across sources,
reporting each value as *consistent with* or *not consistent with* the others so an
examiner can tell a reliable first-connected time from a partial or contradicted one.
USB history is a **multi-source artifact domain**, not a single-parser job. On Windows
the evidence is spread across:
- **Registry** — `USBSTOR`, `Enum\USB`, `MountedDevices` (SYSTEM); Windows Portable
Devices / `WPDBUSENUM`, `VolumeInfoCache` (SOFTWARE); `MountPoints2` (NTUSER.DAT);
`Amcache.hve` (execution / first-seen signal)
- **`Enum\SCSI`** — UASP / USB-3 drives (`uaspstor.sys`, Win8+) enumerate here, **not**
under `USBSTOR`; a correlator reading only `USBSTOR` silently misses the modern drives
most likely to matter in an exfiltration case
- **SetupAPI** device-install logs (`setupapi.dev.log`) — local time, no TZ marker
- **Event Logs** (the Partition/Diagnostic log for volume serial numbers)
- **LNK files, jump lists, shellbags** — files opened and directories touched on the device
## Where it sits in the fleet
An **artifact-domain analyzer**, a layer above the data-source parsers — it **consumes**
them rather than reimplement them, and emits `forensicnomicon::report::Finding`s that
Issen renders alongside every other analyzer.
```
usb-forensic ── correlates USB device history, scores cross-source timestamp consistency
├── consumes winreg-artifacts ── USBSTOR / MountedDevices / WPDBUSENUM / Amcache / …
├── consumes peripheral-core ── setupapi.dev.log device-install events
├── consumes winevt-forensic ── Partition/Diagnostic event log (volume serials)
└── consumes lnk-core ── recent-file LNK volume-serial join
```
It is the deep, USB-specific sibling of
[`useract-forensic`](https://github.com/SecurityRonin/useract-forensic): that crate
treats a device connection as one input to a broad user-activity timeline;
`usb-forensic` is the focused consistency-scoring engine for the USB domain itself.
## Why build it — the whitespace (adversarially pressure-tested)
The reference product is [USB Detective](https://usbdetective.com/): Windows-only,
closed-source, GUI, ~6 years mature. Its moat is **cross-source timestamp consistency
scoring + per-value provenance** — the defensibility an expert witness needs.
An earlier draft of this thesis claimed we could go *cross-platform with the same
confidence model* and be "better." A deep analysis (Fable 5) and a hostile critique
(Codex) both rejected that. What survives:
**Rejected — not the wedge:**
1. **"Same confidence model on macOS/Linux" is illusory.** Consistency scoring needs
several *independent, persistent* sources with different update semantics to
cross-check — a Windows-specific property. macOS ≈ one strongly timestamped source
(unified logs / USBMSC, days-to-weeks retention) plus name-only plists; Linux ≈
single-source journald. With 1–2 sources there is nothing to score against.
2. **"Match USB Detective on Windows" is not a cheap phase 1.** The scoring *algorithm*
is a weekend; the semantic model under it (per-build timestamp-rewrite quirks,
`Enum\SCSI`/UASP coverage, Win10 30-day cleanup, local-vs-UTC traps) is ~12–24 months
of corpus-driven differential validation.
3. **"Open-source = court-defensible" is narrow.** Courts admit closed tools under
Daubert routinely; source availability aids *testimony*, not admissibility (and it
hands the opposing expert your bug tracker).
**The actual wedge — structural, not feature gaps the incumbent can patch:**
1. **Form factor USB Detective cannot match without ceasing to be itself:** headless,
library-embeddable, pipeline-native, diffable JSONL, running on any OS to analyse
*Windows* evidence at fleet scale. Nothing open does scored multi-source USB
correlation as a CLI/library (RegRipper = raw plugins; USBFT = unscored GUI).
2. **Reproducibility by construction** — a `--reproduce` mode re-deriving every value
from `hive → key → raw bytes → decoding rule`, hashable and runnable by the opposing
expert. The durable half of "court-ready"; the PDF/DOCX *format* is a weekend feature.
3. **The customer is the pipeline operator, not the GUI examiner** (who has a free
Community edition and zero switching pressure): lab automation, Velociraptor/KAPE,
fleet integration. Smaller, quieter market — infrastructure, not a hero product.
Full landscape, sources, and competitor matrix:
[`docs/competitive-landscape.md`](docs/competitive-landscape.md). Build sequence:
[`docs/roadmap.md`](docs/roadmap.md).
## Kill criteria — build only if none of these trip
1. **The 80%-clone trap.** Community edition is free; a 90%-of-Windows clone offers the
examiner nothing. The only viable sequencing is the **inverse**: ship the
pipeline/library form factor first (zero incumbent there), let Windows depth accrete
under differential test.
2. **No sustained validation corpus.** An unvalidated correlator is a liability
generator — a miscorrelation that flags a legitimate timestamp, in a report with the
examiner's name on it, is worse than no tool. v1 must say "consistent with / not
consistent with" and **refuse** "spoofed." Requires a maintained XP→11 image corpus
with documented ground truth.
3. **Can't generalize past USB.** Rational only as the fleet's **first general
artifact-domain correlation engine**, not a one-off USB tool.
Useful lever: **USB Detective Community edition is a free differential oracle** — run
both over the same evidence; every disagreement is either a bug or a documentable edge
case, converting the incumbent's moat into the test suite.
## Trust, but verify
`#![forbid(unsafe_code)]`, panic-free (the workspace denies `unwrap`/`expect` in
production), and gated on 100% library line coverage. The correlation logic will be
validated **differentially against an independent oracle** (USB Detective Community
edition, RegRipper) on real disk images — see
[`docs/validation.md`](docs/validation.md). Findings are **observations**, never
verdicts: "consistent with …", the examiner draws the conclusions.
---
[Privacy Policy](https://securityronin.github.io/usb-forensic/privacy/) · [Terms of Service](https://securityronin.github.io/usb-forensic/terms/) · © 2026 Security Ronin Ltd