disk_forensic/lib.rs
1//! # disk-forensic
2//!
3//! Point it at any disk image — raw or wrapped in a forensic container — and it
4//! decodes the container, identifies the partitioning scheme (MBR, GPT, or Apple
5//! Partition Map), and dispatches to the matching forensic parser, so you get the
6//! right structural analysis without choosing a crate up front.
7//!
8//! [`container::open`] sniffs the wrapper by content and decodes E01/EWF, VMDK,
9//! VHDX, VHD, QCOW2, and DMG to a `Read + Seek` view of the raw disk; ISO 9660
10//! optical images are a filesystem rather than a partitioned disk and are routed
11//! to [`iso9660_forensic`]. Everything else is pure orchestration: scheme
12//! detection comes from the
13//! [`forensicnomicon`](https://docs.rs/forensicnomicon) knowledge base, and every
14//! real parse is delegated to a sibling crate
15//! ([`mbr_partition_forensic`], [`gpt_partition_forensic`], [`apm_partition_forensic`]).
16//!
17//! ```no_run
18//! // Decode whatever container the evidence arrived in, then analyse the disk.
19//! let opened = disk_forensic::container::open(std::path::Path::new("evidence.E01"))?;
20//! let mut img = opened.reader;
21//! match disk_forensic::analyse_disk(&mut img, opened.size)? {
22//! disk_forensic::DiskReport::Gpt(a) => println!("GPT, {} partitions", a.partitions.len()),
23//! disk_forensic::DiskReport::Mbr(a) => println!("MBR, {} partitions", a.partitions.len()),
24//! disk_forensic::DiskReport::Apm(a) => println!("APM, {} partitions", a.partitions.len()),
25//! }
26//! # Ok::<(), Box<dyn std::error::Error>>(())
27//! ```
28
29use std::io::{Read, Seek, SeekFrom};
30
31pub mod container;
32pub mod normalize;
33pub mod report;
34mod vhd;
35
36pub use forensicnomicon::partition_schemes::Scheme;
37
38/// Bytes read from the start (LBA 0 + LBA 1) for scheme detection.
39const BOOT_AREA_BYTES: usize = 1024;
40/// Upper bound on bytes the APM parser reads — the map lives in the first blocks.
41const APM_MAX_BYTES: usize = 1 << 20;
42
43/// Crate-level error.
44#[derive(Debug, thiserror::Error)]
45pub enum Error {
46 /// No MBR, GPT, or APM signature was found in the boot area (e.g. a disk
47 /// with a filesystem written directly to it, or unrecognised media).
48 #[error("unrecognised partitioning scheme (no MBR, GPT, or APM signature found)")]
49 UnknownScheme,
50 /// The Apple Partition Map parser failed.
51 #[error("APM analysis failed: {0}")]
52 Apm(#[from] apm_partition_forensic::Error),
53 /// The MBR/GPT parser failed.
54 #[error("MBR/GPT analysis failed: {0}")]
55 Mbr(#[from] mbr_partition_forensic::Error),
56 /// I/O failure while reading the disk image.
57 #[error("I/O error: {0}")]
58 Io(#[from] std::io::Error),
59}
60
61/// A full forensic analysis, tagged by the partitioning scheme that was found.
62///
63/// The `Gpt` variant carries the protective-MBR analysis with its parsed GPT
64/// (`.gpt` is `Some`); `Mbr` is a classic MBR with no GPT.
65#[derive(Debug)]
66#[cfg_attr(feature = "serde", derive(serde::Serialize))]
67pub enum DiskReport {
68 /// Apple Partition Map.
69 Apm(apm_partition_forensic::ApmAnalysis),
70 /// Classic Master Boot Record (no GPT).
71 Mbr(Box<mbr_partition_forensic::MbrAnalysis>),
72 /// GUID Partition Table (protective MBR + parsed GPT).
73 Gpt(Box<mbr_partition_forensic::MbrAnalysis>),
74}
75
76impl DiskReport {
77 /// The detected partitioning scheme.
78 #[must_use]
79 pub fn scheme(&self) -> Scheme {
80 match self {
81 DiskReport::Apm(_) => Scheme::Apm,
82 DiskReport::Mbr(_) => Scheme::Mbr,
83 DiskReport::Gpt(_) => Scheme::Gpt,
84 }
85 }
86
87 /// `true` when the analysis recorded at least one anomaly — the CLI's
88 /// non-zero exit signal for triage pipelines.
89 #[must_use]
90 pub fn has_anomalies(&self) -> bool {
91 match self {
92 DiskReport::Apm(a) => !a.anomalies.is_empty(),
93 DiskReport::Mbr(m) | DiskReport::Gpt(m) => !m.anomalies.is_empty(),
94 }
95 }
96}
97
98/// Detect the partitioning scheme of the disk behind `reader` and run the
99/// matching forensic parser.
100///
101/// `disk_size_bytes` bounds MBR/GPT gap and out-of-bounds analysis (pass the
102/// image length; `0` skips it). The reader is rewound before each parser runs.
103///
104/// # Errors
105/// [`Error::UnknownScheme`] when no scheme signature is present, [`Error::Apm`] /
106/// [`Error::Mbr`] when the chosen parser fails, or [`Error::Io`] on a read error.
107pub fn analyse_disk<R: Read + Seek>(
108 reader: &mut R,
109 disk_size_bytes: u64,
110) -> Result<DiskReport, Error> {
111 let boot = read_boot_area(reader)?;
112 match forensicnomicon::partition_schemes::detect_scheme(&boot) {
113 Some(Scheme::Apm) => Ok(DiskReport::Apm(apm_partition_forensic::analyse_reader(
114 reader,
115 APM_MAX_BYTES,
116 )?)),
117 Some(Scheme::Gpt | Scheme::Mbr) => {
118 let mbr = mbr_partition_forensic::analyse(reader, disk_size_bytes)?;
119 // The parser's own GPT detection is authoritative for the label: a
120 // protective MBR with a parseable GPT → Gpt, otherwise classic Mbr.
121 if mbr.gpt.is_some() {
122 Ok(DiskReport::Gpt(Box::new(mbr)))
123 } else {
124 Ok(DiskReport::Mbr(Box::new(mbr)))
125 }
126 }
127 None => Err(Error::UnknownScheme),
128 }
129}
130
131/// Read up to [`BOOT_AREA_BYTES`] from the start, tolerating short reads and EOF.
132fn read_boot_area<R: Read + Seek>(reader: &mut R) -> Result<Vec<u8>, std::io::Error> {
133 reader.seek(SeekFrom::Start(0))?;
134 let mut buf = vec![0u8; BOOT_AREA_BYTES];
135 let mut filled = 0;
136 while filled < BOOT_AREA_BYTES {
137 match reader.read(&mut buf[filled..]) {
138 Ok(0) => break,
139 Ok(n) => filled += n,
140 Err(e) if e.kind() == std::io::ErrorKind::Interrupted => {}
141 Err(e) => return Err(e),
142 }
143 }
144 buf.truncate(filled);
145 Ok(buf)
146}
147
148#[cfg(test)]
149mod tests {
150 use super::*;
151 use std::io::{Error as IoError, ErrorKind};
152
153 #[test]
154 fn error_display_covers_every_variant() {
155 assert!(Error::UnknownScheme.to_string().contains("unrecognised"));
156 let apm: Error = apm_partition_forensic::Error::NotApm.into();
157 assert!(apm.to_string().contains("APM"));
158 let mbr: Error = mbr_partition_forensic::Error::TooShort(1).into();
159 assert!(mbr.to_string().contains("MBR"));
160 let io: Error = IoError::other("boom").into();
161 assert!(io.to_string().contains("I/O"));
162 }
163
164 /// Yields `Interrupted` once (must be retried), then a hard error.
165 struct FlakyReader {
166 interrupted_once: bool,
167 }
168 impl Read for FlakyReader {
169 fn read(&mut self, _buf: &mut [u8]) -> std::io::Result<usize> {
170 if self.interrupted_once {
171 Err(IoError::other("hard read failure"))
172 } else {
173 self.interrupted_once = true;
174 Err(IoError::from(ErrorKind::Interrupted))
175 }
176 }
177 }
178 impl Seek for FlakyReader {
179 fn seek(&mut self, _: SeekFrom) -> std::io::Result<u64> {
180 Ok(0)
181 }
182 }
183
184 #[test]
185 fn read_boot_area_retries_interrupted_then_propagates_error() {
186 let mut r = FlakyReader {
187 interrupted_once: false,
188 };
189 let err = read_boot_area(&mut r).unwrap_err();
190 assert_eq!(err.to_string(), "hard read failure");
191 }
192
193 #[test]
194 fn read_boot_area_stops_at_eof_on_short_image() {
195 // A sub-1024-byte reader hits the `Ok(0) => break` path.
196 let mut r = std::io::Cursor::new(vec![0u8; 16]);
197 let boot = read_boot_area(&mut r).unwrap();
198 assert_eq!(boot.len(), 16);
199 }
200}