Crate forensic_carve 

forensic-carve — the SecurityRonin fleet carving contract and single-pass sweep engine.

This crate owns the medium-agnostic carving contract — the Carver trait, Signature, CarveContext, CarvedItem, and the RecoveryMethod provenance vocabulary — plus (in later increments) the aho-corasick sweep engine that runs one detection pass over disk-unallocated or memory regions and dispatches capped windows to the matching carver.

Fleet ADR 0001 (ronin-issen/docs/decisions/) is the governing design. A carver sees only &[u8] windows and plain values, so the same carver serves disk and memory sweeps; medium attribution (PID/VA/PFN, volume/run ids) is wrapped by the driver after the call and never appears on CarvedItem.

Increment 1: the contract types only. The sweep engine lands in a later cycle.

Structs

CarveContext

The plain-values context handed to Carver::carve. Carries only values — the window’s absolute base offset in the source, and the confidence policy. It never carries a Read/Seek, a VFS handle, or a memory provider: a carver that must chase virtual pointers is a memory walker, not a medium-agnostic carver.

CarveOptions

Engine knobs. Public fields, medium defaults set by the caller’s driver.

CarvedItem

One recovered item. Medium-neutral: it never carries PID/VA/PFN (memory) or volume/run ids (disk) — that attribution is wrapped by the driver after the carve call (ADR 0001 §8, SweptItem). Constructed via CarvedItem::records / CarvedItem::artifact_bytes, never a struct literal.

CarverRegistration

A carver registration submitted by a parser crate. Holds a 'static reference to the carver so it can live in the inventory’s link-time set.

Region

A contiguous span of the source to sweep, plus an opaque medium-specific attribution tag (disk: volume/run id; memory: PID/VA) that rides back out on each SweptItem — keeping CarvedItem itself medium-neutral (ADR §8/C1).

Signature

A magic signature a carver recognises: the bytes, plus the offset at which they appear within the artifact, so a mid-artifact magic still anchors the window start correctly.

SweptItem

A carved item plus where it came from: the source-relative offset and the region’s attribution tag. Keeps CarvedItem medium-neutral (ADR §8/C1).

Enums

CarvedPayload

A carved item’s payload: either a bounded whole artifact (which re-enters the normal classify→parse pipeline) or already-decoded records (for a loose chunk with no containing file to re-parse — e.g. an orphaned ElfChnk).

ConfidencePolicy

What the engine does with carved items given their confidence. Defaults live in each medium’s driver, not hard-coded in the engine (ADR 0001 §8/C1).

RecoveryMethod

How (and how broadly) an artifact was recovered — the fleet-wide provenance vocabulary (ADR 0001 §3). Carving is a recovery method, so this general concept owns the plain name; the SQLite-record substrate detail lives in browser-forensic-carve as SqliteRecoveryMethod.

Traits

Carver

A per-format carver. One impl per format, living in that format’s PARSER crate, seeing only &[u8] windows — medium-agnostic by construction, so the same carver serves disk-unallocated and memory sweeps.

RegionSource

A positioned-read edge over the source being swept. Disk drivers implement it over forensic-vfs positioned reads; memory drivers over read_virt. A short read (fewer bytes than requested) signals a gap or end-of-source — the engine treats the window as truncated, never fabricating bytes.

Functions

registered_carvers

Every carver registered (via inventory::submit!) into the final binary.

sweep

Run one detection pass over regions, dispatching capped windows to the matching carver. Returns the carved items, each wrapped with its source offset and region tag. Panic-free: a build failure or empty pattern set yields no items rather than erroring.