peripheral_core/lib.rs
1//! `peripheral-core` — external-device (peripheral) connection forensic reader.
2//!
3//! Parses Windows `setupapi.dev.log` device-installation logs into a uniform
4//! [`DeviceConnection`] stream: bus-classified, with each timestamp tagged
5//! authoritative-vs-inferred and the USB iSerial kept distinct from any volume
6//! serial. The input is attacker-controllable evidence — parsing is lenient
7//! (lossy UTF-8), bounds-checked, and never panics. No `unsafe`.
8//!
9//! Findings (DMA-capable device, mass-storage, HID/BadUSB, OS-generated serial)
10//! live in the sibling `peripheral-forensic` crate; this crate only decodes.
11//!
12//! ## v0.2 enrichment (not in this release)
13//!
14//! The richest source — the Windows registry `SYSTEM\CurrentControlSet\Enum\`
15//! keys (USBSTOR/USB), `MountedDevices`, and the device-property `0066`/`0067`
16//! Last-Arrival/Last-Removal `FILETIME`s — plus EVTX device events require the
17//! (unpublished) `winreg-core` and `winevt-forensic` crates. They are deferred
18//! to v0.2; v0.1 is scoped to the self-contained `setupapi.dev.log` source.
19
20#![forbid(unsafe_code)]
21
22pub mod setupapi;
23
24/// The physical/logical bus a peripheral attached through.
25///
26/// The variant drives the DMA-capability and storage-class threat lenses
27/// downstream (see [`DeviceConnection::dma_capable`]).
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
29pub enum Bus {
30 /// USB (host-controller mediated; not directly DMA-capable as mass storage).
31 Usb,
32 /// Media Transfer Protocol (phones/cameras) — surfaced via `WpdBusEnumRoot`.
33 Mtp,
34 /// IEEE 1394 FireWire — bus-mastering DMA.
35 FireWire,
36 /// Thunderbolt — PCIe tunnelled, bus-mastering DMA.
37 Thunderbolt,
38 /// PCI Express — bus-mastering DMA.
39 Pcie,
40 /// External SATA — SATA/storage transport, explicitly NOT DMA.
41 Esata,
42 /// SD/MMC card.
43 SdMmc,
44 /// Bluetooth (typically HID/wireless).
45 Bluetooth,
46 /// ExpressCard — PCIe-backed, bus-mastering DMA.
47 ExpressCard,
48 /// SCSI / SAS storage transport.
49 ScsiSas,
50 /// NVMe storage.
51 Nvme,
52 /// Bus could not be determined from the enumerator.
53 Unknown,
54}
55
56impl Bus {
57 /// Classify a bus from a setupapi/instance-id **enumerator** prefix — the
58 /// leading token of a device instance id (`USBSTOR`, `USB`, `1394`, `PCI`,
59 /// `SCSI`, `SD`, `WpdBusEnumRoot`, …), matched case-insensitively.
60 ///
61 /// Returns [`Bus::Unknown`] for an unrecognized or empty enumerator; the
62 /// caller never gets a panic.
63 #[must_use]
64 pub fn from_enumerator(enumerator: &str) -> Self {
65 let e = enumerator.trim().to_ascii_uppercase();
66 match e.as_str() {
67 "USBSTOR" | "USB" => Self::Usb,
68 "1394" => Self::FireWire,
69 "THUNDERBOLT" => Self::Thunderbolt,
70 "PCI" | "PCIE" => Self::Pcie,
71 "SCSI" | "SAS" => Self::ScsiSas,
72 "NVME" => Self::Nvme,
73 "SD" | "MMC" | "SDBUS" => Self::SdMmc,
74 "ESATA" => Self::Esata,
75 "BTHENUM" | "BTHLE" | "BLUETOOTH" => Self::Bluetooth,
76 "EXPRESSCARD" => Self::ExpressCard,
77 "WPDBUSENUMROOT" | "MTP" => Self::Mtp,
78 _ => Self::Unknown,
79 }
80 }
81
82 /// Whether this bus can perform **bus-mastering DMA**, the property that
83 /// makes a device a direct-memory-access attack surface (MITRE T1200).
84 ///
85 /// DMA-capable: FireWire, Thunderbolt, PCIe, ExpressCard. Storage-class
86 /// transports (USB mass storage, eSATA, SD/MMC, SCSI/SAS, NVMe) and
87 /// HID/wireless transports (USB-HID, Bluetooth) are NOT DMA in this model.
88 ///
89 /// Caveat: SD-Express tunnels PCIe and *can* be DMA-capable; this v0.1
90 /// classifier treats bare `SD` as the legacy non-DMA SD/MMC bus, the common
91 /// case. Distinguishing SD-Express needs the device-capability bits that the
92 /// registry/EVTX v0.2 source carries.
93 #[must_use]
94 pub fn is_dma_capable(self) -> bool {
95 matches!(
96 self,
97 Self::FireWire | Self::Thunderbolt | Self::Pcie | Self::ExpressCard
98 )
99 }
100
101 /// Whether this bus is a removable mass-storage transport (the
102 /// data-exfiltration / autorun lens, MITRE T1052.001 / T1091).
103 #[must_use]
104 pub fn is_mass_storage(self) -> bool {
105 matches!(
106 self,
107 Self::Usb | Self::Esata | Self::SdMmc | Self::ScsiSas | Self::Nvme
108 )
109 }
110}
111
112/// How much trust a timestamp carries.
113#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
114pub enum Confidence {
115 /// Directly recorded by the source as the stated event
116 /// (e.g. the setupapi section-header install time → first-seen).
117 Authoritative,
118 /// Derived/undocumented — the value's meaning is inferred, not stated by the
119 /// source (e.g. the registry `0066`/`0067` Last-Arrival/Last-Removal
120 /// device-property `FILETIME`s, which are undocumented).
121 Inferred,
122}
123
124/// A timestamp tagged with its evidentiary confidence.
125///
126/// Pairing the value with its [`Confidence`] in the type makes the
127/// authoritative-vs-inferred distinction impossible to drop on the floor: a
128/// consumer cannot read `value` without also seeing how trustworthy it is.
129#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
130pub struct Stamp {
131 /// Unix epoch seconds.
132 pub value: i64,
133 /// How the value should be trusted.
134 pub confidence: Confidence,
135}
136
137impl Stamp {
138 /// An authoritative (source-stated) timestamp.
139 #[must_use]
140 pub fn authoritative(value: i64) -> Self {
141 Self {
142 value,
143 confidence: Confidence::Authoritative,
144 }
145 }
146
147 /// An inferred (derived/undocumented) timestamp.
148 #[must_use]
149 pub fn inferred(value: i64) -> Self {
150 Self {
151 value,
152 confidence: Confidence::Inferred,
153 }
154 }
155}
156
157/// A MITRE ATT&CK technique a connection is *consistent with* — never a verdict.
158#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
159pub struct MitreRef(pub &'static str);
160
161/// One external-device connection, normalized across sources.
162///
163/// The forensic cautions are baked into the type, not just the docs:
164/// - [`device_serial`](Self::device_serial) is the **USB iSerial** and is a
165/// distinct field from [`volume_serial`](Self::volume_serial) (a filesystem
166/// volume serial), so the two can never be conflated.
167/// - [`serial_is_os_generated`](Self::serial_is_os_generated) records that the
168/// device had no real iSerial (Windows synthesized one), weakening attribution.
169/// - Each timestamp is a [`Stamp`] carrying its authoritative-vs-inferred
170/// [`Confidence`].
171#[derive(Debug, Clone, PartialEq, Eq)]
172pub struct DeviceConnection {
173 // ── Identity ────────────────────────────────────────────────────────────
174 /// The classified bus.
175 pub bus: Bus,
176 /// Device setup-class GUID, when known.
177 pub device_class_guid: Option<String>,
178 /// USB vendor id (`VID_xxxx`).
179 pub vid: Option<u16>,
180 /// USB product id (`PID_xxxx`).
181 pub pid: Option<u16>,
182 /// The **USB iSerial** — the device-unique serial reported by the device.
183 /// DISTINCT from any [`volume_serial`](Self::volume_serial).
184 pub device_serial: Option<String>,
185 /// `true` when the instance-id serial was synthesized by Windows (the
186 /// serial's 2nd character is `&`) — the device exposed no real iSerial, so
187 /// attribution is weaker.
188 pub serial_is_os_generated: bool,
189 /// Human-readable friendly name, when present.
190 pub friendly_name: Option<String>,
191 /// The full device instance id (e.g.
192 /// `USB\VID_0781&PID_5583\1234567890AB`) — the primary key.
193 pub device_instance_id: String,
194
195 // ── Timestamps (each tagged authoritative-vs-inferred) ───────────────────
196 /// First-seen / first-install — authoritative when from the setupapi
197 /// section header.
198 pub first_install: Option<Stamp>,
199 /// Last install/driver event.
200 pub last_install: Option<Stamp>,
201 /// Last arrival (connect). INFERRED — derived from the undocumented registry
202 /// `0066` device property (v0.2).
203 pub last_arrival: Option<Stamp>,
204 /// Last removal (disconnect). INFERRED — derived from the undocumented
205 /// registry `0067` device property (v0.2).
206 pub last_removal: Option<Stamp>,
207
208 // ── Correlation join keys (volume_serial kept DISTINCT from device_serial) ─
209 /// `ParentIdPrefix` — joins the storage device to its volume.
210 pub parent_id_prefix: Option<String>,
211 /// Volume GUID (`\\?\Volume{...}`).
212 pub volume_guid: Option<String>,
213 /// Mounted drive letter.
214 pub drive_letter: Option<char>,
215 /// Filesystem **volume** serial (NTFS/FAT) — DISTINCT from the device's
216 /// USB [`device_serial`](Self::device_serial).
217 pub volume_serial: Option<u32>,
218 /// MBR disk signature.
219 pub disk_signature: Option<u32>,
220
221 // ── Threat lens ──────────────────────────────────────────────────────────
222 /// Whether the bus is bus-mastering DMA-capable (see [`Bus::is_dma_capable`]).
223 pub dma_capable: bool,
224 /// MITRE ATT&CK techniques this connection is *consistent with*.
225 pub mitre: Vec<MitreRef>,
226
227 // ── Provenance ───────────────────────────────────────────────────────────
228 /// Where this record came from (source file + 1-based line).
229 pub source: Provenance,
230}
231
232/// Where a [`DeviceConnection`] was decoded from.
233#[derive(Debug, Clone, PartialEq, Eq)]
234pub struct Provenance {
235 /// The source file (e.g. `setupapi.dev.log`).
236 pub file: String,
237 /// 1-based line number of the section header the record came from.
238 pub line: usize,
239}
240
241#[cfg(test)]
242mod tests {
243 use super::*;
244
245 #[test]
246 fn usb_enumerators_classify_as_usb() {
247 assert_eq!(Bus::from_enumerator("USBSTOR"), Bus::Usb);
248 assert_eq!(Bus::from_enumerator("USB"), Bus::Usb);
249 assert_eq!(Bus::from_enumerator("usbstor"), Bus::Usb); // case-insensitive
250 }
251
252 #[test]
253 fn bus_specific_enumerators_classify() {
254 assert_eq!(Bus::from_enumerator("1394"), Bus::FireWire);
255 assert_eq!(Bus::from_enumerator("SCSI"), Bus::ScsiSas);
256 assert_eq!(Bus::from_enumerator("PCI"), Bus::Pcie);
257 assert_eq!(Bus::from_enumerator("SD"), Bus::SdMmc);
258 assert_eq!(Bus::from_enumerator("WpdBusEnumRoot"), Bus::Mtp);
259 assert_eq!(Bus::from_enumerator("THUNDERBOLT"), Bus::Thunderbolt);
260 assert_eq!(Bus::from_enumerator("ESATA"), Bus::Esata);
261 assert_eq!(Bus::from_enumerator("EXPRESSCARD"), Bus::ExpressCard);
262 assert_eq!(Bus::from_enumerator("BTHENUM"), Bus::Bluetooth);
263 assert_eq!(Bus::from_enumerator("NVME"), Bus::Nvme);
264 }
265
266 #[test]
267 fn unknown_enumerator_is_unknown_never_panics() {
268 assert_eq!(Bus::from_enumerator("HID"), Bus::Unknown);
269 assert_eq!(Bus::from_enumerator(""), Bus::Unknown);
270 assert_eq!(Bus::from_enumerator(" "), Bus::Unknown);
271 }
272
273 #[test]
274 fn dma_capable_is_exactly_firewire_thunderbolt_pcie_expresscard() {
275 for b in [Bus::FireWire, Bus::Thunderbolt, Bus::Pcie, Bus::ExpressCard] {
276 assert!(b.is_dma_capable(), "{b:?} must be DMA-capable");
277 }
278 // Storage-only transports are explicitly NOT DMA (eSATA is SATA/storage).
279 for b in [Bus::Usb, Bus::Esata, Bus::SdMmc, Bus::ScsiSas, Bus::Nvme] {
280 assert!(!b.is_dma_capable(), "{b:?} must NOT be DMA-capable");
281 }
282 // HID/wireless transports are not DMA either.
283 for b in [Bus::Bluetooth, Bus::Mtp, Bus::Unknown] {
284 assert!(!b.is_dma_capable(), "{b:?} must NOT be DMA-capable");
285 }
286 }
287
288 #[test]
289 fn mass_storage_classes() {
290 for b in [Bus::Usb, Bus::Esata, Bus::SdMmc, Bus::ScsiSas, Bus::Nvme] {
291 assert!(b.is_mass_storage(), "{b:?} should be mass storage");
292 }
293 for b in [Bus::FireWire, Bus::Thunderbolt, Bus::Bluetooth, Bus::Mtp] {
294 assert!(!b.is_mass_storage(), "{b:?} should not be mass storage");
295 }
296 }
297
298 #[test]
299 fn stamp_carries_confidence() {
300 assert_eq!(
301 Stamp::authoritative(10).confidence,
302 Confidence::Authoritative
303 );
304 assert_eq!(Stamp::inferred(10).confidence, Confidence::Inferred);
305 }
306}