mbr-forensic

Forensic-grade Master Boot Record (MBR) parser for Rust. Goes beyond partition enumeration to surface structural anomalies, slack-space content, anti-forensic indicators, and cross-field inconsistencies that every other MBR crate silently ignores.

Command-line tool

$ cargo run --bin mbr-forensic -- disk.img

MBR Forensic Analysis
  disk signature : 0x00000000
  boot code      : AllZeros
  partitioning   : Unknown

Partition table (1 entries):
  [0] GPT Protective MBR       LBA            1..=8191          fs=Unknown

Anomalies (2):
  [INFO] MBR-BOOT-PROTECTIVE-EMPTY @ 0x0: MBR boot code is empty (all zeros), which is expected on a GPT/UEFI disk — the protective MBR's boot code is never executed
  [INFO] MBR-BOOT-NONE @ 0x1be: No partition is marked bootable

GPT cross-check: 2 partition entries, 0 GPT anomalies

Highest severity: INFO

The binary exits 0 when clean and 1 when any anomaly is present, so it drops straight into a triage pipeline. Add --json (with --features serde) for machine-readable output. When a protective MBR is found, the real GPT is parsed automatically (via gpt-forensic) and cross-checked.

Rust library

[dependencies]
mbr-forensic = "0.1"

Quick start

use mbr_forensic::{parse_mbr_sector, analyse};
use std::fs::File;

// Pure parsing from a 512-byte buffer — no I/O, no panics:
let mut f = File::open("disk.img")?;
let analysis = analyse(&mut f, disk_size_bytes)?;

for anomaly in &analysis.anomalies {
    println!("[{:?}] offset {:#x}  {}", anomaly.severity, anomaly.offset, anomaly.note);
}
# Ok::<(), mbr_forensic::Error>(())

What makes this different from every other MBR crate

Most MBR crates answer one question: "what partitions are on this disk?" mbr-forensic answers the questions a digital forensics examiner actually needs:

Anomaly types

Every detected condition is returned as an Anomaly { severity, kind, offset, note }:

NonZeroReserved          bytes 444–445 non-zero
MultipleBootable         > 1 partition has 0x80 status
NoBootablePartition      active partitions but none marked bootable
ResidualEntry            type=0x00 but non-zero LBA fields → deleted partition
OverlappingPartitions    LBA range intersection between two entries
OutOfBounds              partition end exceeds reported disk size
ChsLbaInconsistency      CHS-encoded values disagree with LBA
EbrCycle                 EBR next-pointer forms a loop
EbrExcessiveDepth        EBR chain exceeds 64 levels
EbrSlackData             EBR entries 2–3 contain non-zero bytes
PrePartitionSpace        sectors before the first partition
InterPartitionGap        unpartitioned space between partitions
PostPartitionSpace       trailing space after the last partition
SignatureMismatch        declared type ≠ detected filesystem magic
WipedBootCode            boot code is all zeros
ErasedBootCode           boot code is all 0xFF
UnknownBootCode          boot code matches no known signature
HighEntropySlack         high-entropy bytes in a slack region

Filesystem fingerprinting

mbr-forensic reads the first sector of each partition and matches it against known magic bytes, independently of the declared partition type. A mismatch between the declared type and the detected filesystem is surfaced as a SignatureMismatch anomaly.

Detected filesystem types: Ext (ext2/3/4), Ntfs, Fat, ExFat, Apfs, Xfs, LinuxSwap, LinuxLvm, Luks, AllZeros, Unknown.

Boot code identification

The first 446 bytes of the MBR are matched against signatures for known bootloaders:

API

Parse a raw 512-byte MBR sector (pure, no I/O)

use mbr_forensic::parse_mbr_sector;

let sector = std::fs::read("disk.img")?;
let mbr = parse_mbr_sector(&sector[..512])?;

println!("Disk serial: {:#010X}", mbr.disk_serial);
for (i, entry) in mbr.entries.iter().enumerate() {
    if !entry.is_empty() {
        println!("  [{i}] type={} lba={} count={}", entry.type_code.name(), entry.lba_start, entry.lba_count);
    }
}
# Ok::<(), mbr_forensic::Error>(())

Full forensic analysis from any Read + Seek

use mbr_forensic::analyse;
use std::fs::File;

let mut f = File::open("disk.img")?;
let meta = f.metadata()?;
let analysis = analyse(&mut f, meta.len())?;

println!("Boot code: {:?}", analysis.boot_code_id);
println!("Partitions: {}", analysis.partitions.len());
println!("Gaps: {}", analysis.gaps.len());
println!("Anomalies: {}", analysis.anomalies.len());

for a in analysis.anomalies.iter().filter(|a| a.severity >= mbr_forensic::Severity::Medium) {
    println!("  [{:?}] {}", a.severity, a.note);
}
# Ok::<(), mbr_forensic::Error>(())

Entropy analysis on slack regions

use mbr_forensic::entropy;

let slack = &sector[446..512]; // example: partition table area
let e = entropy::shannon(slack);
if e > 6.0 {
    println!("High-entropy slack ({e:.2} bits/byte) — possible hidden data");
}

Security

mbr-forensic is designed for use on untrusted disk images from potentially compromised systems:

• No panics on malicious input — all arithmetic uses checked or saturating operations; fuzz-tested with cargo fuzz
• EBR cycle detection — visited-LBA set prevents infinite loops
• Overflow-safe EBR chain — checked_add terminates the chain on arithmetic overflow
• Depth cap — EBR chains exceeding 64 levels are flagged and stopped
• Truncation-safe — read errors on truncated images terminate traversal gracefully rather than propagating

Running the fuzz targets

# Requires nightly Rust and cargo-fuzz
rustup install nightly
cargo install cargo-fuzz

cargo +nightly fuzz run parse_mbr_sector
cargo +nightly fuzz run analyse_full

Debugging with the trace feature

mbr-forensic has no logging dependency by default. Enable the trace feature to forward every analysis event — each recorded anomaly, the run summary, EBR walk failures, and partition read errors — to the tracing ecosystem:

[dependencies]
mbr-forensic = { version = "0.1", features = ["trace"] }

tracing_subscriber::fmt().with_max_level(tracing::Level::DEBUG).init();
let analysis = mbr_forensic::analyse(&mut reader, disk_size)?;
// → DEBUG analyse: anomaly recorded code="MBR-PART-OVERLAP" severity=CRITICAL offset=0x1be ...
# Ok::<(), mbr_forensic::Error>(())

All diagnostics live in one place (src/diag.rs), so the full set of observable events is discoverable at a glance.

Testing

224 tests (unit + integration) covering every public API, every error path, every anomaly kind, and adversarial inputs (overflowing EBR chains, truncated images, seek failures). 100% function coverage with no uncovered lines — verified in CI.

cargo test                 # default features
cargo test --features trace

For coverage:

cargo install cargo-llvm-cov
cargo llvm-cov --show-missing-lines

Aggregate line coverage can read slightly under 100% because the generic, reader-agnostic functions are monomorphized once per reader type in the tests; --show-missing-lines confirms no source line is left uncovered.

Related

mbr-forensic analyses the partition layout. To read the actual filesystem data that lives inside each partition, these crates provide Read + Seek over common disk container formats:

Sibling crates

One forensic parser per partitioning scheme — each a pure Read + Seek library that composes with the container crates above:

For forensic integrity analysis of container formats:

Privacy Policy · Terms of Service · © 2026 Security Ronin Ltd