use std::collections::{HashSet, VecDeque};
use std::io::{Read, Seek, SeekFrom, Write};
use crate::csum::{Checksummer, Crc32c};
use crate::extent::{ExtentNode, MAX_EXTENT_DEPTH, parse_node, tail_offset};
use crate::feature::{FeatureSet, Incompat, LARGE_FILE_MIN_SIZE, Profile};
use crate::model::ROOT_INO;
use crate::ondisk::{
BG_BLOCK_UNINIT, BG_INODE_UNINIT, DIR_TAIL_LEN, DX_CHECKSUM_OFFSET, DX_ENTRY_LEN,
DX_NODE_COUNT_OFFSET, DX_ROOT_COUNT_OFFSET, DX_TAIL_LEN, DirEntry, EXTENT_ENTRY_SIZE,
EXTENT_TAIL_LEN, FileType, GOOD_OLD_FIRST_INODE, GOOD_OLD_INODE_SIZE, GroupDescriptor, Inode,
InodeFlags, ParseError, SuperBlock, Xattr, decode_device, dx_tail_offset, get_u16, get_u32,
orphan_entries_len, parse_block, parse_inline, put_u16, read_dx_entries, read_dx_root_info,
read_orphan_tail,
};
const SUPPORTED_INCOMPAT: u32 = Incompat::FILETYPE.bits()
| Incompat::EXTENTS.bits()
| Incompat::SIXTY_FOUR_BIT.bits()
| Incompat::FLEX_BG.bits()
| Incompat::CSUM_SEED.bits();
fn unsupported_incompat(incompat: Incompat) -> u32 {
incompat.bits() & !SUPPORTED_INCOMPAT
}
const UNMODELLED_INCOMPAT: &[(&str, u32)] = &[
("compression", 0x0000_0001),
("needs_recovery", 0x0000_0004),
("journal_dev", 0x0000_0008),
("mmp", 0x0000_0100),
("ea_inode", 0x0000_0400),
("dirdata", 0x0000_1000),
("large_dir", 0x0000_4000),
("inline_data", 0x0000_8000),
("encrypt", 0x0001_0000),
("casefold", 0x0002_0000),
];
fn describe_unsupported_incompat(bits: u32) -> String {
let mut parts: Vec<String> = Vec::new();
let mut undefined = 0u32;
for i in 0..u32::BITS {
let bit = 1u32 << i;
if bits & bit == 0 {
continue;
}
if let Some(name) = Incompat::from_bits(bit).names().first() {
parts.push((*name).to_string());
} else if let Some((name, _)) = UNMODELLED_INCOMPAT.iter().find(|(_, b)| *b == bit) {
parts.push((*name).to_string());
} else {
undefined |= bit;
}
}
if undefined != 0 {
parts.push(format!("{undefined:#010x}"));
}
format!(
"unsupported incompatible feature(s) {}: the reader cannot be certain it \
interprets the on-disk format correctly",
parts.join(", ")
)
}
const DIRECT_BLOCKS: usize = 12;
const INDIRECT_LEVELS: u32 = 3;
const MAP_WINDOW_BLOCKS: usize = 4096;
const MAX_LOGICAL_BLOCKS: u64 = 1 << 32;
pub const MAX_SYMLINK_HOPS: u32 = 40;
const MAX_PATH: usize = 4096;
pub const MIN_DIRENT_LEN: u64 = 12;
fn components(path: &[u8]) -> VecDeque<Vec<u8>> {
path.split(|&b| b == b'/')
.filter(|c| !c.is_empty() && *c != b".")
.map(<[u8]>::to_vec)
.collect()
}
fn is_dir(inode: &Inode) -> bool {
inode.mode & 0o170000 == 0o040000
}
fn is_symlink(inode: &Inode) -> bool {
inode.mode & 0o170000 == 0o120000
}
fn is_regular(inode: &Inode) -> bool {
inode.mode & 0o170000 == 0o100000
}
fn name_is_hostile(name: &[u8]) -> bool {
name.contains(&b'/') || name.contains(&0)
}
fn is_fast_symlink(inode: &Inode, block_size: usize) -> bool {
let ea_blocks = if inode.file_acl != 0 {
(block_size / 512) as u64
} else {
0
};
inode.blocks == ea_blocks
}
fn maps_data(inode: &Inode, block_size: usize) -> bool {
match inode.mode & 0o170000 {
0o100000 | 0o040000 => true, 0o120000 => !is_fast_symlink(inode, block_size), _ => false,
}
}
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub enum Severity {
Cosmetic,
Conformance,
Integrity,
Structural,
}
impl Severity {
#[must_use]
pub fn as_str(self) -> &'static str {
match self {
Severity::Cosmetic => "cosmetic",
Severity::Conformance => "conformance",
Severity::Integrity => "integrity",
Severity::Structural => "structural",
}
}
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub enum Category {
Superblock,
GroupDescriptor,
Bitmap,
Inode,
ExtentTree,
Directory,
Xattr,
Journal,
Orphan,
}
impl Category {
#[must_use]
pub fn as_str(self) -> &'static str {
match self {
Category::Superblock => "superblock",
Category::GroupDescriptor => "group descriptor",
Category::Bitmap => "bitmap",
Category::Inode => "inode",
Category::ExtentTree => "extent tree",
Category::Directory => "directory",
Category::Xattr => "xattr",
Category::Journal => "journal",
Category::Orphan => "orphan",
}
}
}
pub const SCAN_SCHEMA_VERSION: u32 = 1;
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct Location {
pub block: Option<u64>,
pub group: Option<u32>,
pub inode: Option<u32>,
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct Anomaly {
pub severity: Severity,
pub category: Category,
pub location: Location,
pub detail: String,
}
impl Anomaly {
#[must_use]
pub fn to_json(&self) -> String {
let Self {
severity,
category,
location,
detail,
} = self;
let mut out = String::from("{\"severity\":\"");
out.push_str(severity.as_str());
out.push_str("\",\"category\":\"");
out.push_str(category.as_str());
out.push_str("\",\"location\":");
push_location_json(&mut out, location);
out.push_str(",\"detail\":");
push_json_string(&mut out, detail);
out.push('}');
out
}
}
fn push_location_json(out: &mut String, loc: &Location) {
let Location {
block,
group,
inode,
} = *loc;
out.push('{');
let mut first = true;
if let Some(b) = block {
push_json_field(out, &mut first, "block", b);
}
if let Some(g) = group {
push_json_field(out, &mut first, "group", u64::from(g));
}
if let Some(i) = inode {
push_json_field(out, &mut first, "inode", u64::from(i));
}
out.push('}');
}
fn push_json_field(out: &mut String, first: &mut bool, key: &str, value: u64) {
if !*first {
out.push(',');
}
*first = false;
out.push('"');
out.push_str(key);
out.push_str("\":");
out.push_str(&value.to_string());
}
fn push_json_string(out: &mut String, s: &str) {
out.push('"');
for c in s.chars() {
match c {
'"' => out.push_str("\\\""),
'\\' => out.push_str("\\\\"),
'\n' => out.push_str("\\n"),
'\r' => out.push_str("\\r"),
'\t' => out.push_str("\\t"),
c if (c as u32) < 0x20 => {
let byte = c as u32;
out.push_str("\\u00");
out.push(char::from_digit(byte >> 4, 16).expect("high nibble is 0..16"));
out.push(char::from_digit(byte & 0xf, 16).expect("low nibble is 0..16"));
}
c => out.push(c),
}
}
out.push('"');
}
fn location_compact(loc: &Location) -> String {
let mut parts = Vec::new();
if let Some(g) = loc.group {
parts.push(format!("group {g}"));
}
if let Some(i) = loc.inode {
parts.push(format!("inode {i}"));
}
if let Some(b) = loc.block {
parts.push(format!("block {b}"));
}
if parts.is_empty() {
"-".to_string()
} else {
parts.join(" ")
}
}
fn sarif_level(severity: Severity) -> &'static str {
match severity {
Severity::Structural | Severity::Integrity => "error",
Severity::Conformance => "warning",
Severity::Cosmetic => "note",
}
}
fn push_sarif_rules(out: &mut String, anomalies: &[Anomaly]) {
let mut seen: Vec<&'static str> = Vec::new();
for a in anomalies {
let id = a.category.as_str();
if !seen.contains(&id) {
if !seen.is_empty() {
out.push(',');
}
seen.push(id);
out.push_str("{\"id\":");
push_json_string(out, id);
out.push_str(",\"name\":");
push_json_string(out, id);
out.push_str(",\"shortDescription\":{\"text\":");
push_json_string(out, &format!("{id} anomaly"));
out.push_str("}}");
}
}
}
fn push_sarif_result(out: &mut String, a: &Anomaly, artifact_uri: Option<&str>) {
out.push_str("{\"ruleId\":");
push_json_string(out, a.category.as_str());
out.push_str(",\"level\":\"");
out.push_str(sarif_level(a.severity));
out.push_str("\",\"message\":{\"text\":");
push_json_string(out, &a.detail);
out.push('}');
let address = location_compact(&a.location);
let has_address = address != "-";
if artifact_uri.is_some() || has_address {
out.push_str(",\"locations\":[{");
let mut first = true;
if let Some(uri) = artifact_uri {
out.push_str("\"physicalLocation\":{\"artifactLocation\":{\"uri\":");
push_json_string(out, uri);
out.push_str("}}");
first = false;
}
if has_address {
if !first {
out.push(',');
}
out.push_str("\"logicalLocations\":[{\"fullyQualifiedName\":");
push_json_string(out, &address);
out.push_str("}]");
}
out.push_str("}]");
}
out.push_str(",\"properties\":");
push_sarif_properties(out, a);
out.push('}');
}
fn push_sarif_properties(out: &mut String, a: &Anomaly) {
out.push_str("{\"severity\":");
push_json_string(out, a.severity.as_str());
out.push_str(",\"category\":");
push_json_string(out, a.category.as_str());
let mut first = false;
if let Some(b) = a.location.block {
push_json_field(out, &mut first, "block", b);
}
if let Some(g) = a.location.group {
push_json_field(out, &mut first, "group", u64::from(g));
}
if let Some(i) = a.location.inode {
push_json_field(out, &mut first, "inode", u64::from(i));
}
out.push('}');
}
fn anomaly_at_inode(err: &ReadError, ino: u32) -> Anomaly {
let mut a = err.anomaly();
a.location.inode.get_or_insert(ino);
a
}
fn redirect_block_ref(a: &mut Anomaly, err: &ReadError, category: Category) {
if matches!(err, ReadError::OutOfRange { what: "block", .. }) {
a.category = category;
}
}
fn anomaly_in_mapping(err: &ReadError, ino: u32, category: Category) -> Anomaly {
let mut a = err.anomaly();
redirect_block_ref(&mut a, err, category);
if ino != 0 {
a.location.inode.get_or_insert(ino);
}
a
}
fn hostile_name_anomaly(ino: u32) -> Anomaly {
Anomaly {
severity: Severity::Structural,
category: Category::Directory,
location: Location {
inode: Some(ino),
..Location::default()
},
detail: "a directory entry name contains a path separator or NUL".to_string(),
}
}
fn anomaly_in_bitmap(err: &ReadError, group: u32, category: Category) -> Anomaly {
let mut a = err.anomaly();
redirect_block_ref(&mut a, err, category);
a.location.group.get_or_insert(group);
a
}
fn parse_structure(err: &ParseError) -> &'static str {
match err {
ParseError::TooShort { structure, .. }
| ParseError::BadMagic { structure, .. }
| ParseError::InvalidField { structure, .. } => structure,
}
}
fn parse_category(structure: &str) -> Category {
match structure {
"Inode" => Category::Inode,
"GroupDescriptor" => Category::GroupDescriptor,
"ExtentHeader" | "ExtentNode" => Category::ExtentTree,
"DirEntry" | "DirEntryTail" => Category::Directory,
s if s.starts_with("Dx") => Category::Directory,
s if s.starts_with("Xattr") => Category::Xattr,
s if s.starts_with("JournalSuperblock") => Category::Journal,
"OrphanBlockTail" => Category::Orphan,
_ => Category::Superblock,
}
}
struct ExtentScanCtx<'a> {
ino: u32,
seed: u32,
has_csum: bool,
csum: &'a Crc32c,
}
fn extent_tail_offset(node: &[u8], node_bytes: usize) -> usize {
if node.len() >= EXTENT_ENTRY_SIZE {
let eh_max = usize::from(get_u16(node, 4));
let tail = EXTENT_ENTRY_SIZE * (eh_max + 1);
if tail + EXTENT_TAIL_LEN <= node.len() {
return tail;
}
}
tail_offset(node_bytes)
}
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
pub enum ReadPolicy {
#[default]
Strict,
Lenient,
}
impl ReadPolicy {
#[must_use]
pub fn is_fatal(self, severity: Severity) -> bool {
match self {
ReadPolicy::Strict => severity >= Severity::Conformance,
ReadPolicy::Lenient => false,
}
}
}
#[derive(Clone, PartialEq, Eq, Debug, thiserror::Error)]
#[non_exhaustive]
pub enum ReadError {
#[error("i/o error: {message}")]
#[non_exhaustive]
Io {
kind: std::io::ErrorKind,
message: String,
},
#[error(transparent)]
Parse(#[from] ParseError),
#[error("reference to {what} {index} is out of range")]
#[non_exhaustive]
OutOfRange {
what: &'static str,
index: u64,
},
#[error("inode {inode} does not exist")]
#[non_exhaustive]
NoSuchInode {
inode: u32,
},
#[error("extent tree is too deep or malformed")]
BadExtentTree,
#[error("directory structure is malformed")]
BadDirectory,
#[error("journal structure is malformed")]
BadJournal,
#[error("orphan file structure is malformed")]
BadOrphanFile,
#[error(
"unsupported incompatible feature bits {bits:#010x}: the reader cannot be certain \
it interprets the on-disk format correctly"
)]
#[non_exhaustive]
UnsupportedIncompat {
bits: u32,
},
#[error(
"inode {inode} is in extent format, but the superblock does not enable the \
extent feature"
)]
#[non_exhaustive]
ExtentFlagWithoutFeature {
inode: u32,
},
#[error(
"inode {inode} names attribute block {block}, but the superblock does not enable \
the ext_attr feature"
)]
#[non_exhaustive]
XattrBlockWithoutFeature {
inode: u32,
block: u64,
},
#[error(
"inode {inode} is a {size}-byte regular file, but the superblock does not enable \
the large_file feature"
)]
#[non_exhaustive]
LargeFileWithoutFeature {
inode: u32,
size: u64,
},
#[error(
"inode {inode} is marked hash-indexed, but the superblock does not enable the \
dir_index feature"
)]
#[non_exhaustive]
IndexFlagWithoutFeature {
inode: u32,
},
#[error("inode {inode} is marked hash-indexed, but it is not a directory")]
#[non_exhaustive]
IndexFlagOnNonDirectory {
inode: u32,
},
#[error("{what} for group {group} lies at block {block}, outside the group")]
#[non_exhaustive]
MetadataOutsideGroup {
what: &'static str,
group: u32,
block: u64,
},
#[error("no such path: {}", String::from_utf8_lossy(path))]
#[non_exhaustive]
NotFound {
path: Vec<u8>,
},
#[error("not a directory: {}", String::from_utf8_lossy(path))]
#[non_exhaustive]
NotADirectory {
path: Vec<u8>,
},
#[error("too many symbolic links resolving: {}", String::from_utf8_lossy(path))]
#[non_exhaustive]
SymlinkLoop {
path: Vec<u8>,
},
#[error("the tree holds more than {limit} names, the bound this walk is held to")]
#[non_exhaustive]
WalkTooLarge {
limit: usize,
},
#[error("the file is {size} bytes, more than the {limit}-byte cap this read is held to")]
#[non_exhaustive]
FileTooLarge {
size: u64,
limit: u64,
},
#[error("{object} {index} checksum mismatch: stored {stored:#010x}, computed {computed:#010x}")]
#[non_exhaustive]
ChecksumMismatch {
object: &'static str,
index: u64,
stored: u32,
computed: u32,
},
}
impl From<std::io::Error> for ReadError {
fn from(e: std::io::Error) -> Self {
ReadError::Io {
kind: e.kind(),
message: e.to_string(),
}
}
}
impl ReadError {
#[must_use]
pub fn anomaly(&self) -> Anomaly {
let (severity, category, location) = match self {
ReadError::Io { .. } => (
Severity::Structural,
Category::Superblock,
Location::default(),
),
ReadError::Parse(e) => (
Severity::Structural,
parse_category(parse_structure(e)),
Location::default(),
),
ReadError::OutOfRange { what, index } => {
let category = if *what == "inode" {
Category::Inode
} else if *what == "group" {
Category::GroupDescriptor
} else {
Category::Superblock
};
let location = match *what {
"block" => Location {
block: Some(*index),
..Location::default()
},
"inode" => Location {
inode: Some(*index as u32),
..Location::default()
},
"group" => Location {
group: Some(*index as u32),
..Location::default()
},
_ => Location::default(),
};
(Severity::Structural, category, location)
}
ReadError::NoSuchInode { inode: n } => (
Severity::Structural,
Category::Inode,
Location {
inode: Some(*n),
..Location::default()
},
),
ReadError::BadExtentTree => (
Severity::Structural,
Category::ExtentTree,
Location::default(),
),
ReadError::BadDirectory => (
Severity::Structural,
Category::Directory,
Location::default(),
),
ReadError::BadJournal => (Severity::Structural, Category::Journal, Location::default()),
ReadError::BadOrphanFile => {
(Severity::Structural, Category::Orphan, Location::default())
}
ReadError::WalkTooLarge { .. } => (
Severity::Structural,
Category::Directory,
Location::default(),
),
ReadError::FileTooLarge { .. } => {
(Severity::Structural, Category::Inode, Location::default())
}
ReadError::NotFound { .. }
| ReadError::NotADirectory { .. }
| ReadError::SymlinkLoop { .. } => (
Severity::Structural,
Category::Directory,
Location::default(),
),
ReadError::ChecksumMismatch { object, index, .. } => {
let (category, location) = match *object {
"superblock" => (Category::Superblock, Location::default()),
"group descriptor" => (
Category::GroupDescriptor,
Location {
group: Some(*index as u32),
..Location::default()
},
),
"inode" => (
Category::Inode,
Location {
inode: Some(*index as u32),
..Location::default()
},
),
"extent node" => (
Category::ExtentTree,
Location {
block: Some(*index),
..Location::default()
},
),
"block bitmap" | "inode bitmap" => (
Category::Bitmap,
Location {
group: Some(*index as u32),
..Location::default()
},
),
"directory block" => (
Category::Directory,
Location {
block: Some(*index),
..Location::default()
},
),
"xattr block" => (
Category::Xattr,
Location {
block: Some(*index),
..Location::default()
},
),
"orphan block" => (
Category::Orphan,
Location {
block: Some(*index),
..Location::default()
},
),
_ => (Category::Superblock, Location::default()),
};
(Severity::Integrity, category, location)
}
ReadError::UnsupportedIncompat { .. } => (
Severity::Structural,
Category::Superblock,
Location::default(),
),
ReadError::ExtentFlagWithoutFeature { inode } => (
Severity::Structural,
Category::Inode,
Location {
inode: Some(*inode),
..Location::default()
},
),
ReadError::XattrBlockWithoutFeature { inode, block } => (
Severity::Structural,
Category::Xattr,
Location {
inode: Some(*inode),
block: Some(*block),
..Location::default()
},
),
ReadError::LargeFileWithoutFeature { inode, .. } => (
Severity::Conformance,
Category::Inode,
Location {
inode: Some(*inode),
..Location::default()
},
),
ReadError::IndexFlagWithoutFeature { inode } => (
Severity::Conformance,
Category::Directory,
Location {
inode: Some(*inode),
..Location::default()
},
),
ReadError::IndexFlagOnNonDirectory { inode } => (
Severity::Conformance,
Category::Inode,
Location {
inode: Some(*inode),
..Location::default()
},
),
ReadError::MetadataOutsideGroup {
what, group, block, ..
} => {
let category = if what.ends_with("bitmap") {
Category::Bitmap
} else {
Category::GroupDescriptor
};
(
Severity::Structural,
category,
Location {
group: Some(*group),
block: Some(*block),
..Location::default()
},
)
}
};
let detail = match self {
ReadError::UnsupportedIncompat { bits } => describe_unsupported_incompat(*bits),
_ => self.to_string(),
};
Anomaly {
severity,
category,
location,
detail,
}
}
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct ScanReport {
anomalies: Vec<Anomaly>,
truncated: bool,
#[cfg_attr(feature = "serde", serde(skip))]
cap: usize,
}
impl Default for ScanReport {
fn default() -> Self {
Self {
anomalies: Vec::new(),
truncated: false,
cap: Self::MAX_ANOMALIES,
}
}
}
impl ScanReport {
pub const MAX_ANOMALIES: usize = 10_000;
#[must_use]
pub fn anomalies(&self) -> &[Anomaly] {
&self.anomalies
}
#[must_use]
pub fn is_truncated(&self) -> bool {
self.truncated
}
#[must_use]
pub fn is_clean(&self) -> bool {
!self.truncated && self.anomalies.is_empty()
}
#[must_use]
pub fn worst_severity(&self) -> Option<Severity> {
self.anomalies.iter().map(|a| a.severity).max()
}
#[must_use]
pub fn has_fatal(&self, policy: ReadPolicy) -> bool {
self.anomalies.iter().any(|a| policy.is_fatal(a.severity))
}
#[must_use]
pub fn to_json(&self) -> String {
let mut out = String::from("{\"schema\":");
out.push_str(&SCAN_SCHEMA_VERSION.to_string());
out.push_str(",\"clean\":");
out.push_str(if self.is_clean() { "true" } else { "false" });
out.push_str(",\"count\":");
out.push_str(&self.anomalies.len().to_string());
out.push_str(",\"truncated\":");
out.push_str(if self.truncated { "true" } else { "false" });
out.push_str(",\"anomalies\":[");
for (i, a) in self.anomalies.iter().enumerate() {
if i > 0 {
out.push(',');
}
out.push_str(&a.to_json());
}
out.push_str("]}");
out
}
#[must_use]
pub fn to_sarif(&self, artifact_uri: Option<&str>) -> String {
let mut out = String::from(
"{\"$schema\":\"https://json.schemastore.org/sarif-2.1.0.json\",\
\"version\":\"2.1.0\",\"runs\":[{\"tool\":{\"driver\":{\"name\":\"ferrosys\",\"rules\":[",
);
push_sarif_rules(&mut out, &self.anomalies);
out.push_str("]}},\"results\":[");
for (i, a) in self.anomalies.iter().enumerate() {
if i > 0 {
out.push(',');
}
push_sarif_result(&mut out, a, artifact_uri);
}
out.push(']');
if self.truncated {
out.push_str(
",\"invocations\":[{\"executionSuccessful\":true,\
\"toolExecutionNotifications\":[{\"level\":\"warning\",\"message\":{\"text\":",
);
push_json_string(&mut out, &self.truncation_notice());
out.push_str("}}]}]");
}
out.push_str("}]}");
out
}
#[must_use]
pub fn to_table(&self) -> String {
if self.anomalies.is_empty() {
let mut out = String::from("no anomalies\n");
if self.truncated {
out.push('\n');
out.push_str(&self.truncation_notice());
out.push('\n');
}
return out;
}
let rows: Vec<(&str, &str, String, &str)> = self
.anomalies
.iter()
.map(|a| {
(
a.severity.as_str(),
a.category.as_str(),
location_compact(&a.location),
a.detail.as_str(),
)
})
.collect();
let mut sev_w = "SEVERITY".len();
let mut cat_w = "CATEGORY".len();
let mut loc_w = "LOCATION".len();
for (s, c, l, _) in &rows {
sev_w = sev_w.max(s.len());
cat_w = cat_w.max(c.len());
loc_w = loc_w.max(l.len());
}
let mut out = format!(
"{:<sev_w$} {:<cat_w$} {:<loc_w$} {}\n",
"SEVERITY", "CATEGORY", "LOCATION", "DETAIL"
);
for (s, c, l, d) in &rows {
out.push_str(&format!("{s:<sev_w$} {c:<cat_w$} {l:<loc_w$} {d}\n"));
}
if self.truncated {
out.push('\n');
out.push_str(&self.truncation_notice());
out.push('\n');
}
out
}
fn truncation_notice(&self) -> String {
format!(
"report truncated at {} anomalies; the rest of the image was not scanned",
self.cap
)
}
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct Entry {
pub name: Vec<u8>,
pub inode: u32,
pub file_type: FileType,
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct WalkEntry {
pub path: Vec<u8>,
pub number: u32,
pub inode: Inode,
}
pub struct Reader<R> {
src: R,
base: u64,
sb: SuperBlock,
sb_raw: Vec<u8>,
feature: FeatureSet,
block_size: usize,
policy: ReadPolicy,
limits: Limits,
csum_seed: Option<u32>,
}
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
#[non_exhaustive]
pub struct OpenOptions {
pub base: u64,
pub policy: ReadPolicy,
pub limits: Limits,
pub csum_seed: Option<u32>,
}
impl OpenOptions {
#[must_use]
pub const fn new() -> Self {
Self {
base: 0,
policy: ReadPolicy::Strict,
limits: Limits::new(),
csum_seed: None,
}
}
#[must_use]
pub const fn base(mut self, base: u64) -> Self {
self.base = base;
self
}
#[must_use]
pub const fn policy(mut self, policy: ReadPolicy) -> Self {
self.policy = policy;
self
}
#[must_use]
pub const fn limits(mut self, limits: Limits) -> Self {
self.limits = limits;
self
}
#[must_use]
pub const fn csum_seed(mut self, seed: u32) -> Self {
self.csum_seed = Some(seed);
self
}
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct Limits {
pub max_anomalies: usize,
pub max_walk_entries: usize,
pub max_file_bytes: u64,
}
impl Limits {
#[must_use]
pub const fn new() -> Self {
Self {
max_anomalies: ScanReport::MAX_ANOMALIES,
max_walk_entries: usize::MAX,
max_file_bytes: u64::MAX,
}
}
#[must_use]
pub const fn max_anomalies(mut self, max: usize) -> Self {
self.max_anomalies = max;
self
}
#[must_use]
pub const fn max_walk_entries(mut self, max: usize) -> Self {
self.max_walk_entries = max;
self
}
#[must_use]
pub const fn max_file_bytes(mut self, max: u64) -> Self {
self.max_file_bytes = max;
self
}
}
impl Default for Limits {
fn default() -> Self {
Self::new()
}
}
impl<R: Read + Seek> Reader<R> {
pub fn open(src: R) -> Result<Self, ReadError> {
Self::open_with(src, &OpenOptions::new())
}
pub fn open_with(mut src: R, options: &OpenOptions) -> Result<Self, ReadError> {
let &OpenOptions {
base,
policy,
limits,
csum_seed,
} = options;
let sb_offset = base.checked_add(1024).ok_or(ReadError::OutOfRange {
what: "bytes",
index: base,
})?;
src.seek(SeekFrom::Start(sb_offset))?;
let mut sb_bytes = vec![0u8; SuperBlock::SIZE];
src.read_exact(&mut sb_bytes)?;
let mut sb = SuperBlock::read_from(&sb_bytes)?;
if sb.rev_level == 0 {
sb.inode_size = GOOD_OLD_INODE_SIZE as u16;
sb.first_ino = GOOD_OLD_FIRST_INODE;
}
if sb.log_block_size > 6 {
return Err(ReadError::Parse(ParseError::InvalidField {
structure: "superblock",
field: "s_log_block_size",
value: u64::from(sb.log_block_size),
}));
}
let block_size = 1024usize << sb.log_block_size;
if !sb.inode_size.is_power_of_two()
|| sb.inode_size < 128
|| usize::from(sb.inode_size) > block_size
{
return Err(ReadError::Parse(ParseError::InvalidField {
structure: "superblock",
field: "s_inode_size",
value: u64::from(sb.inode_size),
}));
}
let feature = FeatureSet {
compat: crate::feature::Compat::from_bits(sb.feature_compat),
incompat: Incompat::from_bits(sb.feature_incompat),
ro_compat: crate::feature::RoCompat::from_bits(sb.feature_ro_compat),
block_size: block_size as u32,
inode_size: sb.inode_size,
};
if feature.is_64bit()
&& (!sb.desc_size.is_power_of_two()
|| usize::from(sb.desc_size) < GroupDescriptor::SIZE_64
|| usize::from(sb.desc_size) > block_size)
{
return Err(ReadError::Parse(ParseError::InvalidField {
structure: "superblock",
field: "s_desc_size",
value: u64::from(sb.desc_size),
}));
}
let unsupported = unsupported_incompat(feature.incompat);
if unsupported != 0 && policy.is_fatal(Severity::Structural) {
return Err(ReadError::UnsupportedIncompat { bits: unsupported });
}
Ok(Self {
src,
base,
sb,
sb_raw: sb_bytes,
feature,
block_size,
policy,
limits,
csum_seed,
})
}
#[must_use]
pub fn superblock(&self) -> &SuperBlock {
&self.sb
}
#[must_use]
pub fn feature(&self) -> FeatureSet {
self.feature
}
#[must_use]
pub fn profile(&self) -> Profile {
Profile::of(self.feature)
}
#[must_use]
pub fn policy(&self) -> ReadPolicy {
self.policy
}
fn read_at(&mut self, offset: u64, len: usize) -> Result<Vec<u8>, ReadError> {
let pos = self.base.checked_add(offset).ok_or(ReadError::OutOfRange {
what: "bytes",
index: offset,
})?;
self.src.seek(SeekFrom::Start(pos))?;
let mut buf = vec![0u8; len];
match self.src.read_exact(&mut buf) {
Ok(()) => Ok(buf),
Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => Err(ReadError::OutOfRange {
what: "bytes",
index: offset,
}),
Err(e) => Err(ReadError::Io {
kind: e.kind(),
message: e.to_string(),
}),
}
}
fn block(&mut self, block: u64) -> Result<Vec<u8>, ReadError> {
let start = block
.checked_mul(self.block_size as u64)
.ok_or(ReadError::OutOfRange {
what: "block",
index: block,
})?;
match self.read_at(start, self.block_size) {
Err(ReadError::OutOfRange { .. }) => Err(ReadError::OutOfRange {
what: "block",
index: block,
}),
other => other,
}
}
pub fn group_descriptor(&mut self, group: u32) -> Result<GroupDescriptor, ReadError> {
let raw = self.group_descriptor_raw(group)?;
Ok(GroupDescriptor::read_from(&raw, self.desc_size())?)
}
fn desc_size(&self) -> usize {
if self.feature.is_64bit() {
debug_assert!(
usize::from(self.sb.desc_size) >= GroupDescriptor::SIZE_64,
"open_with admitted a 64bit image with s_desc_size {}",
self.sb.desc_size
);
self.sb.desc_size.max(GroupDescriptor::SIZE_32 as u16) as usize
} else {
GroupDescriptor::SIZE_32
}
}
fn group_descriptor_raw(&mut self, group: u32) -> Result<Vec<u8>, ReadError> {
let desc_size = self.desc_size();
let table = u64::from(self.sb.first_data_block) + 1;
let off = table * self.block_size as u64 + u64::from(group) * desc_size as u64;
match self.read_at(off, desc_size) {
Err(ReadError::OutOfRange { .. }) => Err(ReadError::OutOfRange {
what: "group",
index: u64::from(group),
}),
other => other,
}
}
#[must_use]
pub fn group_count(&self) -> u32 {
let bpg = u64::from(self.sb.blocks_per_group);
if bpg == 0 {
return 0;
}
let addressable = self
.sb
.blocks_count
.saturating_sub(u64::from(self.sb.first_data_block));
addressable.div_ceil(bpg).min(u64::from(u32::MAX)) as u32
}
fn source_len(&mut self) -> u64 {
self.src.seek(SeekFrom::End(0)).unwrap_or(0)
}
fn group_in_use_inodes(&mut self, g: u32) -> Result<Vec<u32>, ReadError> {
let desc = self.group_descriptor(g)?;
if desc.flags & BG_INODE_UNINIT != 0 {
return Ok(Vec::new());
}
let ipg = self.sb.inodes_per_group;
let base = u64::from(g) * u64::from(ipg);
let bmp = self.block(desc.inode_bitmap)?;
let mut out = Vec::new();
for i in 0..ipg {
let byte = (i / 8) as usize;
if byte >= bmp.len() {
break;
}
if bmp[byte] & (1u8 << (i % 8)) == 0 {
continue;
}
let number = base + u64::from(i) + 1;
if number > u64::from(self.sb.inodes_count) {
break;
}
out.push(number as u32);
}
Ok(out)
}
fn superblock_checksum(&self, csum: &Crc32c) -> u32 {
csum.crc32c(!0, &self.sb_raw[..SuperBlock::SIZE - 4])
}
fn descriptor_checksum(&self, group: u32, raw: &[u8], csum: &Crc32c) -> u16 {
let mut buf = raw.to_vec();
put_u16(&mut buf, GroupDescriptor::CHECKSUM_OFFSET, 0);
let seed = csum.base_seed();
let mut c = csum.crc32c(seed, &group.to_le_bytes());
c = csum.crc32c(c, &buf);
(c & 0xffff) as u16
}
fn inode_checksum(&self, number: u32, raw: &[u8], csum: &Crc32c, seed: u32) -> (u32, u32) {
let inode_size = self.sb.inode_size;
let extra_isize = if usize::from(inode_size) > GOOD_OLD_INODE_SIZE {
get_u16(raw, 0x80)
} else {
0
};
let has_hi = Inode::has_checksum_hi(inode_size, extra_isize);
let mut buf = raw.to_vec();
put_u16(&mut buf, Inode::CHECKSUM_LO_OFFSET, 0);
let stored = {
let lo = u32::from(get_u16(raw, Inode::CHECKSUM_LO_OFFSET));
if has_hi {
put_u16(&mut buf, Inode::CHECKSUM_HI_OFFSET, 0);
lo | (u32::from(get_u16(raw, Inode::CHECKSUM_HI_OFFSET)) << 16)
} else {
lo
}
};
let mut c = csum.crc32c(seed, &number.to_le_bytes());
c = csum.crc32c(c, &get_u32(raw, 0x64).to_le_bytes()); c = csum.crc32c(c, &buf);
let computed = if has_hi { c } else { c & 0xffff };
(stored, computed)
}
pub fn verify_checksums(&mut self) -> Result<(), ReadError> {
if !self.feature.has_metadata_csum() {
return Ok(());
}
let csum = self.checksummer();
let seed = csum.base_seed();
let computed = self.superblock_checksum(&csum);
if computed != self.sb.checksum {
return Err(ReadError::ChecksumMismatch {
object: "superblock",
index: 0,
stored: self.sb.checksum,
computed,
});
}
for g in 0..self.group_count() {
let raw = self.group_descriptor_raw(g)?;
let desc = GroupDescriptor::read_from(&raw, self.desc_size())?;
let computed = self.descriptor_checksum(g, &raw, &csum);
if computed != desc.checksum {
return Err(ReadError::ChecksumMismatch {
object: "group descriptor",
index: u64::from(g),
stored: u32::from(desc.checksum),
computed: u32::from(computed),
});
}
self.verify_bitmap_checksums(g, &csum, seed)?;
}
let max_inodes = self.source_len() / u64::from(self.sb.inode_size.max(128));
let mut examined = 0u64;
'inodes: for g in 0..self.group_count() {
for n in self.group_in_use_inodes(g)? {
if examined >= max_inodes {
break 'inodes;
}
examined += 1;
let raw = self.inode_raw(n)?;
let inode = Inode::read_from(&raw, self.sb.inode_size)?;
let (stored, computed) = self.inode_checksum(n, &raw, &csum, seed);
if computed != stored {
return Err(ReadError::ChecksumMismatch {
object: "inode",
index: u64::from(n),
stored,
computed,
});
}
self.verify_extent_nodes(n, &inode, &csum)?;
self.verify_directory_checksums(n, &inode, &csum, seed)?;
self.verify_xattr_block_checksum(&inode, &csum, seed)?;
}
}
self.journal_superblock()?;
self.verify_orphan_blocks(&csum, seed)?;
Ok(())
}
fn checksummer(&self) -> Crc32c {
match self.csum_seed {
Some(seed) => Crc32c::with_seed(seed),
None if self.feature.has_csum_seed() => Crc32c::with_seed(self.sb.checksum_seed),
None => Crc32c::new(&self.sb.uuid),
}
}
fn verify_orphan_blocks(&mut self, csum: &Crc32c, seed: u32) -> Result<(), ReadError> {
let mut faults = Vec::new();
self.collect_orphan_faults(csum, seed, &mut faults);
faults.into_iter().next().map_or(Ok(()), Err)
}
fn collect_orphan_faults(&mut self, csum: &Crc32c, seed: u32, faults: &mut Vec<ReadError>) {
if !self.feature.has_orphan_file() {
return;
}
let has_csum = self.feature.has_metadata_csum();
let ino = self.sb.orphan_file_inum;
if ino == 0 {
faults.push(ReadError::BadOrphanFile);
return;
}
let inode = match self.inode(ino) {
Ok(inode) => inode,
Err(e) => {
faults.push(e);
return;
}
};
let generation = inode.generation;
let bound = self.materialized_block_bound();
if inode.size.div_ceil(self.block_size as u64) > bound {
faults.push(ReadError::BadOrphanFile);
return;
}
let blocks = match self.data_blocks(&inode) {
Ok(blocks) => blocks,
Err(e) => {
faults.push(e);
return;
}
};
for phys in blocks {
if phys == 0 {
faults.push(ReadError::BadOrphanFile);
continue;
}
let block = match self.block(phys) {
Ok(block) => block,
Err(e) => {
faults.push(e);
continue;
}
};
let stored = match read_orphan_tail(&block) {
Ok(stored) => stored,
Err(_) => {
faults.push(ReadError::BadOrphanFile);
continue;
}
};
if !has_csum {
continue; }
let entries = &block[..orphan_entries_len(block.len())];
let mut c = csum.crc32c(seed, &ino.to_le_bytes());
c = csum.crc32c(c, &generation.to_le_bytes());
c = csum.crc32c(c, &phys.to_le_bytes());
c = csum.crc32c(c, entries);
if c != stored {
faults.push(ReadError::ChecksumMismatch {
object: "orphan block",
index: phys,
stored,
computed: c,
});
}
}
}
fn verify_extent_nodes(
&mut self,
ino: u32,
inode: &Inode,
csum: &Crc32c,
) -> Result<(), ReadError> {
if !inode.flags.contains(InodeFlags::EXTENTS) {
return Ok(());
}
let mut seed = csum.crc32c(csum.base_seed(), &ino.to_le_bytes());
seed = csum.crc32c(seed, &inode.generation.to_le_bytes());
let mut visited = HashSet::new();
self.verify_extent_subtree(&inode.block, 0, seed, csum, &mut visited)
}
fn verify_extent_subtree(
&mut self,
node: &[u8],
depth: u16,
seed: u32,
csum: &Crc32c,
visited: &mut HashSet<u64>,
) -> Result<(), ReadError> {
if depth > MAX_EXTENT_DEPTH {
return Err(ReadError::BadExtentTree);
}
let ExtentNode::Index { entries, .. } = parse_node(node)? else {
return Ok(());
};
for idx in entries {
if !visited.insert(idx.leaf) {
return Err(ReadError::BadExtentTree);
}
let child = self.block(idx.leaf)?;
let tail = extent_tail_offset(&child, self.block_size);
let stored = u32::from_le_bytes(
child[tail..tail + EXTENT_TAIL_LEN]
.try_into()
.expect("tail slice is exactly EXTENT_TAIL_LEN bytes"),
);
let computed = csum.crc32c(seed, &child[..tail]);
if stored != computed {
return Err(ReadError::ChecksumMismatch {
object: "extent node",
index: idx.leaf,
stored,
computed,
});
}
self.verify_extent_subtree(&child, depth + 1, seed, csum, visited)?;
}
Ok(())
}
fn collect_metadata_placement_faults(
&self,
g: u32,
desc: &GroupDescriptor,
faults: &mut Vec<ReadError>,
) {
if self.feature.has_flex_bg() {
return;
}
let bpg = u64::from(self.sb.blocks_per_group);
if bpg == 0 {
return;
}
let start = u64::from(self.sb.first_data_block) + u64::from(g) * bpg;
let end = start.saturating_add(bpg).min(self.sb.blocks_count);
let in_group = |block: u64| block >= start && block < end;
for (what, block) in [
("block bitmap", desc.block_bitmap),
("inode bitmap", desc.inode_bitmap),
("inode table", desc.inode_table),
] {
if !in_group(block) {
faults.push(ReadError::MetadataOutsideGroup {
what,
group: g,
block,
});
}
}
}
fn verify_bitmap_checksums(
&mut self,
g: u32,
csum: &Crc32c,
seed: u32,
) -> Result<(), ReadError> {
let mut faults = Vec::new();
self.collect_bitmap_faults(g, csum, seed, &mut faults);
faults.into_iter().next().map_or(Ok(()), Err)
}
fn collect_bitmap_faults(
&mut self,
g: u32,
csum: &Crc32c,
seed: u32,
faults: &mut Vec<ReadError>,
) {
let desc = match self.group_descriptor(g) {
Ok(desc) => desc,
Err(e) => {
faults.push(e);
return;
}
};
let wide = self.desc_size() >= GroupDescriptor::SIZE_64;
let fold = |c: u32| if wide { c } else { c & 0xffff };
if desc.flags & BG_BLOCK_UNINIT == 0 {
let len = (self.sb.blocks_per_group / 8) as usize;
match self.block(desc.block_bitmap) {
Ok(bmp) => {
let computed = fold(csum.crc32c(seed, &bmp[..len.min(bmp.len())]));
if computed != desc.block_bitmap_csum {
faults.push(ReadError::ChecksumMismatch {
object: "block bitmap",
index: u64::from(g),
stored: desc.block_bitmap_csum,
computed,
});
}
}
Err(e) => faults.push(e),
}
}
if desc.flags & BG_INODE_UNINIT == 0 {
let len = self.sb.inodes_per_group.div_ceil(8) as usize;
match self.block(desc.inode_bitmap) {
Ok(bmp) => {
let computed = fold(csum.crc32c(seed, &bmp[..len.min(bmp.len())]));
if computed != desc.inode_bitmap_csum {
faults.push(ReadError::ChecksumMismatch {
object: "inode bitmap",
index: u64::from(g),
stored: desc.inode_bitmap_csum,
computed,
});
}
}
Err(e) => faults.push(e),
}
}
}
fn verify_directory_checksums(
&mut self,
ino: u32,
inode: &Inode,
csum: &Crc32c,
seed: u32,
) -> Result<(), ReadError> {
let mut faults = Vec::new();
self.collect_directory_faults(ino, inode, csum, seed, &mut faults);
faults.into_iter().next().map_or(Ok(()), Err)
}
fn collect_directory_faults(
&mut self,
ino: u32,
inode: &Inode,
csum: &Crc32c,
seed: u32,
faults: &mut Vec<ReadError>,
) {
if inode.mode & 0o170000 != 0o040000 {
return;
}
let indexed = inode.flags.contains(InodeFlags::INDEX);
let base = {
let c = csum.crc32c(seed, &ino.to_le_bytes());
csum.crc32c(c, &inode.generation.to_le_bytes())
};
let blocks = match self.data_blocks(inode) {
Ok(blocks) => blocks,
Err(e) => {
faults.push(e);
return;
}
};
let (root_indexed, interior) = match self.directory_index_layout(&blocks, indexed) {
Ok(layout) => layout,
Err(e) => {
faults.push(e);
return;
}
};
let mut checked = HashSet::new();
for (logical, &phys) in blocks.iter().enumerate() {
if phys == 0 {
continue;
}
if !checked.insert(phys) {
continue;
}
let logical = logical as u64;
let block = match self.block(phys) {
Ok(block) => block,
Err(e) => {
faults.push(e);
continue;
}
};
let count_offset = if logical == 0 && root_indexed {
Some(DX_ROOT_COUNT_OFFSET)
} else if interior.contains(&logical) {
Some(DX_NODE_COUNT_OFFSET)
} else {
None
};
if let Err(e) = self.verify_one_dir_block(phys, &block, base, count_offset, csum) {
faults.push(e);
}
}
}
fn directory_index_layout(
&mut self,
blocks: &[u64],
indexed: bool,
) -> Result<(bool, HashSet<u64>), ReadError> {
let mut interior = HashSet::new();
if !indexed {
return Ok((false, interior));
}
let Some(root_phys) = blocks.first().copied().filter(|&b| b != 0) else {
return Ok((false, interior));
};
let root = self.block(root_phys)?;
let levels = match read_dx_root_info(&root) {
Ok((_, levels)) => levels,
Err(_) => return Ok((true, interior)),
};
let mut frontier = vec![0u64];
for _ in 0..levels {
let mut next = Vec::new();
for &logical in &frontier {
let Some(phys) = blocks.get(logical as usize).copied().filter(|&b| b != 0) else {
continue;
};
let block = self.block(phys)?;
let count_offset = if logical == 0 {
DX_ROOT_COUNT_OFFSET
} else {
DX_NODE_COUNT_OFFSET
};
let Ok(entries) = read_dx_entries(&block, count_offset) else {
continue;
};
for entry in entries {
let child = u64::from(entry.block);
if child != 0 && (child as usize) < blocks.len() && interior.insert(child) {
next.push(child);
}
}
}
frontier = next;
}
Ok((true, interior))
}
fn verify_one_dir_block(
&self,
phys: u64,
block: &[u8],
base: u32,
count_offset: Option<usize>,
csum: &Crc32c,
) -> Result<(), ReadError> {
match count_offset {
None => {
if block.len() < DIR_TAIL_LEN + 4 {
return Ok(());
}
let covered = block.len() - DIR_TAIL_LEN;
let computed = csum.crc32c(base, &block[..covered]);
let stored = get_u32(block, block.len() - 4);
if computed != stored {
return Err(ReadError::ChecksumMismatch {
object: "directory block",
index: phys,
stored,
computed,
});
}
}
Some(count_offset) => {
let limit = usize::from(get_u16(block, count_offset));
let count = usize::from(get_u16(block, count_offset + 2));
let covered = count_offset + DX_ENTRY_LEN * count;
let tail = dx_tail_offset(count_offset, limit);
if covered > block.len() || tail + DX_TAIL_LEN > block.len() {
return Ok(());
}
let mut c = csum.crc32c(base, &block[..covered]);
c = csum.crc32c(c, &block[tail..tail + DX_CHECKSUM_OFFSET]);
c = csum.crc32c(c, &[0u8; DX_TAIL_LEN - DX_CHECKSUM_OFFSET]);
let stored = get_u32(block, tail + 4);
if c != stored {
return Err(ReadError::ChecksumMismatch {
object: "directory block",
index: phys,
stored,
computed: c,
});
}
}
}
Ok(())
}
fn verify_xattr_block_checksum(
&mut self,
inode: &Inode,
csum: &Crc32c,
seed: u32,
) -> Result<(), ReadError> {
let phys = inode.file_acl;
if phys == 0 {
return Ok(());
}
self.check_data_block(phys)?;
let mut block = self.block(phys)?;
if block.len() < 20 {
return Ok(());
}
let stored = get_u32(&block, 16);
crate::ondisk::put_u32(&mut block, 16, 0);
let mut c = csum.crc32c(seed, &phys.to_le_bytes());
c = csum.crc32c(c, &block);
if c != stored {
return Err(ReadError::ChecksumMismatch {
object: "xattr block",
index: phys,
stored,
computed: c,
});
}
Ok(())
}
#[must_use]
pub fn scan(&mut self) -> ScanReport {
let mut anomalies = Vec::new();
let mut truncated = false;
let has_csum = self.feature.has_metadata_csum();
let csum = self.checksummer();
let seed = csum.base_seed();
let source_len = self.source_len();
let block_size = self.block_size as u64;
let max_blocks = source_len / block_size;
let unsupported = unsupported_incompat(self.feature.incompat);
if unsupported != 0 {
anomalies.push(ReadError::UnsupportedIncompat { bits: unsupported }.anomaly());
}
if has_csum {
let computed = self.superblock_checksum(&csum);
if computed != self.sb.checksum {
anomalies.push(
ReadError::ChecksumMismatch {
object: "superblock",
index: 0,
stored: self.sb.checksum,
computed,
}
.anomaly(),
);
}
}
let bpg = u64::from(self.sb.blocks_per_group.max(1));
let group_bound = (max_blocks / bpg)
.saturating_add(2)
.min(u64::from(u32::MAX)) as u32;
let desc_size = self.desc_size();
for g in 0..self.group_count().min(group_bound) {
if anomalies.len() >= self.limits.max_anomalies {
truncated = true;
break;
}
let raw = match self.group_descriptor_raw(g) {
Err(e) => {
anomalies.push(e.anomaly());
continue;
}
Ok(raw) => raw,
};
match GroupDescriptor::read_from(&raw, desc_size) {
Err(e) => anomalies.push(ReadError::Parse(e).anomaly()),
Ok(desc) => {
let mut placement = Vec::new();
self.collect_metadata_placement_faults(g, &desc, &mut placement);
for e in &placement {
anomalies.push(e.anomaly());
}
if has_csum {
let computed = self.descriptor_checksum(g, &raw, &csum);
if computed != desc.checksum {
anomalies.push(
ReadError::ChecksumMismatch {
object: "group descriptor",
index: u64::from(g),
stored: u32::from(desc.checksum),
computed: u32::from(computed),
}
.anomaly(),
);
}
let mut faults = Vec::new();
self.collect_bitmap_faults(g, &csum, seed, &mut faults);
for e in &faults {
anomalies.push(anomaly_in_bitmap(e, g, Category::Bitmap));
}
}
}
}
}
let max_inodes = source_len / u64::from(self.sb.inode_size.max(128));
let mut visited = HashSet::new();
let inode_size = self.sb.inode_size;
let mut examined = 0u64;
'inodes: for g in 0..self.group_count().min(group_bound) {
if examined >= max_inodes {
break;
}
if anomalies.len() >= self.limits.max_anomalies {
truncated = true;
break;
}
let in_use = match self.group_in_use_inodes(g) {
Ok(v) => v,
Err(e) => {
anomalies.push(anomaly_in_bitmap(&e, g, Category::Bitmap));
continue;
}
};
for n in in_use {
if examined >= max_inodes {
break 'inodes;
}
if anomalies.len() >= self.limits.max_anomalies {
truncated = true;
break 'inodes;
}
examined += 1;
let raw = match self.inode_raw(n) {
Err(e) => {
anomalies.push(anomaly_at_inode(&e, n));
continue;
}
Ok(raw) => raw,
};
match Inode::read_from(&raw, inode_size) {
Err(e) => anomalies.push(anomaly_at_inode(&ReadError::Parse(e), n)),
Ok(inode) => {
if has_csum {
let (stored, computed) = self.inode_checksum(n, &raw, &csum, seed);
if computed != stored {
anomalies.push(
ReadError::ChecksumMismatch {
object: "inode",
index: u64::from(n),
stored,
computed,
}
.anomaly(),
);
}
}
self.scan_feature_coherence(n, &inode, &mut anomalies);
self.scan_inode_map(
n,
&inode,
has_csum,
&csum,
&mut visited,
&mut anomalies,
);
self.scan_dirent_names(n, &inode, &mut anomalies);
if has_csum {
let mut faults = Vec::new();
self.collect_directory_faults(n, &inode, &csum, seed, &mut faults);
for e in &faults {
anomalies.push(anomaly_in_mapping(e, n, Category::Directory));
}
if let Err(e) = self.verify_xattr_block_checksum(&inode, &csum, seed) {
anomalies.push(anomaly_in_mapping(&e, n, Category::Xattr));
}
}
}
}
}
}
if let Err(e) = self.journal_superblock() {
anomalies.push(e.anomaly());
}
let mut orphan_faults = Vec::new();
self.collect_orphan_faults(&csum, seed, &mut orphan_faults);
let orphan_ino = self.sb.orphan_file_inum;
for e in &orphan_faults {
anomalies.push(anomaly_in_mapping(e, orphan_ino, Category::Orphan));
}
if anomalies.len() > self.limits.max_anomalies {
anomalies.truncate(self.limits.max_anomalies);
truncated = true;
}
ScanReport {
anomalies,
truncated,
cap: self.limits.max_anomalies,
}
}
fn scan_inode_map(
&mut self,
ino: u32,
inode: &Inode,
has_csum: bool,
csum: &Crc32c,
visited: &mut HashSet<u64>,
out: &mut Vec<Anomaly>,
) {
if !inode.flags.contains(InodeFlags::EXTENTS) {
if !maps_data(inode, self.block_size) {
return;
}
if let Err(e) = self.scan_block_map(inode, visited) {
let owner = if is_dir(inode) {
Category::Directory
} else {
Category::Inode
};
out.push(anomaly_in_mapping(&e, ino, owner));
}
return;
}
let mut seed = csum.crc32c(csum.base_seed(), &ino.to_le_bytes());
seed = csum.crc32c(seed, &inode.generation.to_le_bytes());
let ctx = ExtentScanCtx {
ino,
seed,
has_csum,
csum,
};
self.scan_extent_node(&ctx, &inode.block, 0, visited, out);
}
fn scan_feature_coherence(&self, ino: u32, inode: &Inode, out: &mut Vec<Anomaly>) {
if inode.flags.contains(InodeFlags::EXTENTS) && !self.feature.has_extents() {
out.push(ReadError::ExtentFlagWithoutFeature { inode: ino }.anomaly());
}
if inode.file_acl != 0 && !self.feature.has_ext_attr() {
out.push(
ReadError::XattrBlockWithoutFeature {
inode: ino,
block: inode.file_acl,
}
.anomaly(),
);
}
if is_regular(inode) && inode.size >= LARGE_FILE_MIN_SIZE && !self.feature.has_large_file()
{
out.push(
ReadError::LargeFileWithoutFeature {
inode: ino,
size: inode.size,
}
.anomaly(),
);
}
if inode.flags.contains(InodeFlags::INDEX) {
if is_dir(inode) {
if !self.feature.has_dir_index() {
out.push(ReadError::IndexFlagWithoutFeature { inode: ino }.anomaly());
}
} else {
out.push(ReadError::IndexFlagOnNonDirectory { inode: ino }.anomaly());
}
}
}
fn scan_dirent_names(&mut self, ino: u32, inode: &Inode, out: &mut Vec<Anomaly>) {
if !is_dir(inode) {
return;
}
let Ok(blocks) = self.data_blocks(inode) else {
return;
};
let mut read = HashSet::new();
for phys in blocks {
if phys == 0 || !read.insert(phys) {
continue;
}
let Ok(block) = self.block(phys) else {
continue;
};
let mut off = 0;
while off < block.len() {
let Ok((entry, rec_len)) = DirEntry::read_from(&block[off..], self.block_size)
else {
break; };
if rec_len == 0 {
break;
}
if entry.inode != 0 && name_is_hostile(&entry.name) {
out.push(hostile_name_anomaly(ino));
return;
}
off += rec_len;
}
}
}
fn scan_extent_node(
&mut self,
ctx: &ExtentScanCtx,
node: &[u8],
depth: u16,
visited: &mut HashSet<u64>,
out: &mut Vec<Anomaly>,
) {
if depth > MAX_EXTENT_DEPTH {
out.push(anomaly_at_inode(&ReadError::BadExtentTree, ctx.ino));
return;
}
let parsed = match parse_node(node) {
Ok(n) => n,
Err(e) => {
out.push(anomaly_at_inode(&ReadError::Parse(e), ctx.ino));
return;
}
};
match parsed {
ExtentNode::Leaves(leaves) => {
for leaf in leaves {
let end = leaf.start.saturating_add(u64::from(leaf.len));
if leaf.start >= self.sb.blocks_count || end > self.sb.blocks_count {
out.push(anomaly_in_mapping(
&ReadError::OutOfRange {
what: "block",
index: leaf.start,
},
ctx.ino,
Category::ExtentTree,
));
}
}
}
ExtentNode::Index { entries, .. } => {
for idx in entries {
if !visited.insert(idx.leaf) {
continue;
}
let child = match self.block(idx.leaf) {
Ok(c) => c,
Err(e) => {
out.push(anomaly_in_mapping(&e, ctx.ino, Category::ExtentTree));
continue;
}
};
if ctx.has_csum {
let tail = extent_tail_offset(&child, self.block_size);
let stored = u32::from_le_bytes(
child[tail..tail + EXTENT_TAIL_LEN]
.try_into()
.expect("tail slice is exactly EXTENT_TAIL_LEN bytes"),
);
let computed = ctx.csum.crc32c(ctx.seed, &child[..tail]);
if stored != computed {
out.push(anomaly_at_inode(
&ReadError::ChecksumMismatch {
object: "extent node",
index: idx.leaf,
stored,
computed,
},
ctx.ino,
));
}
}
self.scan_extent_node(ctx, &child, depth + 1, visited, out);
}
}
}
}
pub fn inode(&mut self, number: u32) -> Result<Inode, ReadError> {
let raw = self.inode_raw(number)?;
Ok(Inode::read_from(&raw, self.sb.inode_size)?)
}
fn inode_raw(&mut self, number: u32) -> Result<Vec<u8>, ReadError> {
if number == 0 || number > self.sb.inodes_count {
return Err(ReadError::NoSuchInode { inode: number });
}
let ipg = self.sb.inodes_per_group;
if ipg == 0 {
return Err(ReadError::NoSuchInode { inode: number });
}
let group = (number - 1) / ipg;
let index = u64::from((number - 1) % ipg);
let desc = self.group_descriptor(group)?;
let isize = self.sb.inode_size as usize;
let off = desc
.inode_table
.checked_mul(self.block_size as u64)
.and_then(|base| base.checked_add(index * isize as u64))
.ok_or(ReadError::OutOfRange {
what: "inode",
index: u64::from(number),
})?;
match self.read_at(off, isize) {
Err(ReadError::OutOfRange { .. }) => Err(ReadError::OutOfRange {
what: "inode",
index: u64::from(number),
}),
other => other,
}
}
fn extent_leaves(
&mut self,
inode: &Inode,
) -> Result<Vec<crate::ondisk::ExtentLeaf>, ReadError> {
let mut leaves = Vec::new();
let mut visited = HashSet::new();
self.walk_extent_node(&inode.block, 0, &mut visited, &mut leaves)?;
Ok(leaves)
}
fn walk_extent_node(
&mut self,
node: &[u8],
depth: u16,
visited: &mut HashSet<u64>,
out: &mut Vec<crate::ondisk::ExtentLeaf>,
) -> Result<(), ReadError> {
if depth > MAX_EXTENT_DEPTH {
return Err(ReadError::BadExtentTree);
}
match parse_node(node)? {
ExtentNode::Leaves(leaves) => {
for leaf in &leaves {
let end = leaf.start.saturating_add(u64::from(leaf.len));
if leaf.start >= self.sb.blocks_count || end > self.sb.blocks_count {
return Err(ReadError::OutOfRange {
what: "block",
index: leaf.start,
});
}
}
out.extend(leaves);
}
ExtentNode::Index { entries, .. } => {
for idx in entries {
if !visited.insert(idx.leaf) {
return Err(ReadError::BadExtentTree);
}
let child = self.block(idx.leaf)?;
self.walk_extent_node(&child, depth + 1, visited, out)?;
}
}
}
Ok(())
}
fn check_data_block(&self, block: u64) -> Result<(), ReadError> {
if block >= self.sb.blocks_count {
return Err(ReadError::OutOfRange {
what: "block",
index: block,
});
}
Ok(())
}
fn data_blocks(&mut self, inode: &Inode) -> Result<Vec<u64>, ReadError> {
let want = self.logical_block_count(inode);
self.map_window(inode, 0, want)
}
fn materialized_block_bound(&mut self) -> u64 {
self.sb
.blocks_count
.min(self.source_len() / self.block_size as u64)
}
fn logical_block_count(&mut self, inode: &Inode) -> usize {
let want = usize::try_from(
inode
.size
.div_ceil(self.block_size as u64)
.min(MAX_LOGICAL_BLOCKS),
)
.unwrap_or(usize::MAX);
if is_dir(inode) {
let bound = self.materialized_block_bound();
return want.min(usize::try_from(bound).unwrap_or(usize::MAX));
}
want
}
fn map_window(
&mut self,
inode: &Inode,
first: usize,
count: usize,
) -> Result<Vec<u64>, ReadError> {
if count == 0 || !maps_data(inode, self.block_size) {
return Ok(Vec::new());
}
let mut map = vec![0u64; count];
if inode.flags.contains(InodeFlags::EXTENTS) {
self.extent_window(inode, first, &mut map)?;
} else {
self.block_map_window(inode, first, &mut map)?;
}
Ok(map)
}
fn extent_window(
&mut self,
inode: &Inode,
first: usize,
map: &mut [u64],
) -> Result<(), ReadError> {
let end = first.saturating_add(map.len());
for leaf in self.extent_leaves(inode)? {
let lo = leaf.block as usize;
let hi = lo.saturating_add(leaf.len as usize);
if hi <= first || lo >= end || !leaf.initialized {
continue;
}
for logical in lo.max(first)..hi.min(end) {
map[logical - first] = leaf.start + (logical - lo) as u64;
}
}
Ok(())
}
fn block_map_window(
&mut self,
inode: &Inode,
first: usize,
map: &mut [u64],
) -> Result<(), ReadError> {
let end = first.saturating_add(map.len());
for i in first..DIRECT_BLOCKS.min(end) {
let ptr = u64::from(get_u32(&inode.block, i * 4));
if ptr != 0 {
self.check_data_block(ptr)?;
}
map[i - first] = ptr;
}
let per_block = self.block_size / 4;
let mut base = DIRECT_BLOCKS;
for level in 1..=INDIRECT_LEVELS {
if base >= end {
break;
}
let next = base.saturating_add(per_block.saturating_pow(level));
if next > first {
let slot = DIRECT_BLOCKS + level as usize - 1;
let root = u64::from(get_u32(&inode.block, slot * 4));
self.walk_indirect_window(root, level, base, first, map)?;
}
base = next;
}
Ok(())
}
fn walk_indirect_window(
&mut self,
block: u64,
level: u32,
base: usize,
first: usize,
map: &mut [u64],
) -> Result<(), ReadError> {
if block == 0 {
return Ok(());
}
self.check_data_block(block)?;
let buf = self.block(block)?;
let per_block = self.block_size / 4;
let span = per_block.saturating_pow(level - 1);
let end = first.saturating_add(map.len());
for i in 0..per_block {
let lo = base.saturating_add(i.saturating_mul(span));
if lo >= end {
break;
}
if lo.saturating_add(span) <= first {
continue;
}
let ptr = u64::from(get_u32(&buf, i * 4));
if level == 1 {
if ptr != 0 {
self.check_data_block(ptr)?;
}
map[lo - first] = ptr;
} else {
self.walk_indirect_window(ptr, level - 1, lo, first, map)?;
}
}
Ok(())
}
fn scan_block_map(
&mut self,
inode: &Inode,
visited: &mut HashSet<u64>,
) -> Result<(), ReadError> {
for i in 0..DIRECT_BLOCKS {
let ptr = u64::from(get_u32(&inode.block, i * 4));
if ptr != 0 {
self.check_data_block(ptr)?;
}
}
for level in 1..=INDIRECT_LEVELS {
let slot = DIRECT_BLOCKS + level as usize - 1;
let root = u64::from(get_u32(&inode.block, slot * 4));
self.scan_indirect(root, level, visited)?;
}
Ok(())
}
fn scan_indirect(
&mut self,
block: u64,
level: u32,
visited: &mut HashSet<u64>,
) -> Result<(), ReadError> {
if block == 0 {
return Ok(());
}
self.check_data_block(block)?;
if !visited.insert(block) {
return Ok(());
}
let buf = self.block(block)?;
let per_block = self.block_size / 4;
for i in 0..per_block {
let ptr = u64::from(get_u32(&buf, i * 4));
if level == 1 {
if ptr != 0 {
self.check_data_block(ptr)?;
}
} else {
self.scan_indirect(ptr, level - 1, visited)?;
}
}
Ok(())
}
pub fn read_data(&mut self, inode: &Inode) -> Result<Vec<u8>, ReadError> {
let want = self.whole_file_len(inode)?;
let len = usize::try_from(want).map_err(|_| ReadError::FileTooLarge {
size: want,
limit: usize::MAX as u64,
})?;
let mut data = vec![0u8; len];
let filled = self.read_into(inode, 0, &mut data)?;
data.truncate(filled);
Ok(data)
}
pub fn read_data_to(&mut self, inode: &Inode, mut out: impl Write) -> Result<u64, ReadError> {
let want = self.whole_file_len(inode)?;
let bs = self.block_size as u64;
let zeros = vec![0u8; self.block_size];
let mut written = 0u64;
while written < want {
let first = usize::try_from(written / bs).unwrap_or(usize::MAX);
let remaining_blocks = (want - written).div_ceil(bs);
let count = usize::try_from(remaining_blocks.min(MAP_WINDOW_BLOCKS as u64))
.unwrap_or(MAP_WINDOW_BLOCKS);
for phys in self.map_window(inode, first, count)? {
let left = want - written;
let take = usize::try_from(left.min(bs)).unwrap_or(self.block_size);
if phys == 0 {
out.write_all(&zeros[..take])?;
} else {
let block = self.block(phys)?;
out.write_all(&block[..take])?;
}
written += take as u64;
if written >= want {
break;
}
}
}
Ok(written)
}
pub fn read_into(
&mut self,
inode: &Inode,
offset: u64,
buf: &mut [u8],
) -> Result<usize, ReadError> {
let size = self.file_len(inode);
if offset >= size || buf.is_empty() {
return Ok(0);
}
let bs = self.block_size as u64;
let want = (size - offset).min(buf.len() as u64);
let first = usize::try_from(offset / bs).unwrap_or(usize::MAX);
let last = usize::try_from((offset + want - 1) / bs).unwrap_or(usize::MAX);
let count = last - first + 1;
let mut skip = usize::try_from(offset % bs).unwrap_or(0);
let mut filled = 0usize;
for phys in self.map_window(inode, first, count)? {
let take =
(self.block_size - skip).min(usize::try_from(want).unwrap_or(usize::MAX) - filled);
if phys == 0 {
buf[filled..filled + take].fill(0);
} else {
let block = self.block(phys)?;
buf[filled..filled + take].copy_from_slice(&block[skip..skip + take]);
}
filled += take;
skip = 0;
if filled as u64 >= want {
break;
}
}
Ok(filled)
}
fn whole_file_len(&mut self, inode: &Inode) -> Result<u64, ReadError> {
let size = self.file_len(inode);
if size > self.limits.max_file_bytes {
return Err(ReadError::FileTooLarge {
size,
limit: self.limits.max_file_bytes,
});
}
Ok(size)
}
pub(crate) fn file_len(&mut self, inode: &Inode) -> u64 {
if !maps_data(inode, self.block_size) {
return 0;
}
let mapped =
(self.logical_block_count(inode) as u64).saturating_mul(self.block_size as u64);
inode.size.min(mapped)
}
fn max_names(&mut self) -> usize {
usize::try_from(self.source_len() / MIN_DIRENT_LEN).unwrap_or(usize::MAX)
}
pub fn journal_superblock(
&mut self,
) -> Result<Option<crate::journal::JournalSuperblock>, ReadError> {
if !self.feature.has_journal() || self.sb.journal_inum == 0 {
return Ok(None);
}
let inode = self.inode(self.sb.journal_inum)?;
let want = self.logical_block_count(&inode).min(1);
let first = self
.map_window(&inode, 0, want)?
.first()
.copied()
.filter(|&b| b != 0)
.ok_or(ReadError::BadJournal)?;
let block = self.block(first)?;
Ok(Some(crate::journal::JournalSuperblock::read_from(&block)?))
}
pub fn read_symlink(&mut self, inode: &Inode) -> Result<Vec<u8>, ReadError> {
if is_fast_symlink(inode, self.block_size) {
let len = usize::try_from(inode.size)
.unwrap_or(usize::MAX)
.min(inode.block.len());
return Ok(inode.block[..len].to_vec());
}
self.read_data(inode)
}
pub fn xattrs(&mut self, inode: &Inode) -> Result<Vec<Xattr>, ReadError> {
let mut out = parse_inline(&inode.inline_xattr)?;
if inode.file_acl != 0 {
self.check_data_block(inode.file_acl)?;
let block = self.block(inode.file_acl)?;
out.extend(parse_block(&block)?);
}
Ok(out)
}
#[must_use]
pub fn device(&self, inode: &Inode) -> (u32, u32) {
let b0 = u32::from_le_bytes([
inode.block[0],
inode.block[1],
inode.block[2],
inode.block[3],
]);
let b1 = u32::from_le_bytes([
inode.block[4],
inode.block[5],
inode.block[6],
inode.block[7],
]);
decode_device(b0, b1)
}
pub fn read_dir(&mut self, inode: &Inode) -> Result<Vec<Entry>, ReadError> {
let mut entries = Vec::new();
for phys in self.data_blocks(inode)? {
if phys == 0 {
continue;
}
let block = self.block(phys)?;
let mut off = 0;
while off < self.block_size {
let (entry, rec_len) = DirEntry::read_from(&block[off..], self.block_size)?;
if rec_len == 0 {
return Err(ReadError::BadDirectory);
}
if entry.inode != 0 {
entries.push(Entry {
name: entry.name,
inode: entry.inode,
file_type: entry.file_type,
});
}
off += rec_len;
}
}
Ok(entries)
}
pub fn lookup(&mut self, path: &[u8]) -> Result<(u32, Inode), ReadError> {
self.resolve(path, true)
}
pub fn lookup_no_follow(&mut self, path: &[u8]) -> Result<(u32, Inode), ReadError> {
self.resolve(path, false)
}
fn resolve(&mut self, path: &[u8], follow_final: bool) -> Result<(u32, Inode), ReadError> {
let mut pending: VecDeque<Vec<u8>> = components(path);
let mut number = ROOT_INO;
let mut inode = self.inode(number)?;
let mut hops = 0u32;
while let Some(name) = pending.pop_front() {
if !is_dir(&inode) {
return Err(ReadError::NotADirectory {
path: path.to_vec(),
});
}
let entry = self
.read_dir(&inode)?
.into_iter()
.find(|e| e.name == name)
.ok_or_else(|| ReadError::NotFound {
path: path.to_vec(),
})?;
let next = self.inode(entry.inode)?;
let final_component = pending.is_empty();
if is_symlink(&next) && (follow_final || !final_component) {
hops += 1;
if hops > MAX_SYMLINK_HOPS {
return Err(ReadError::SymlinkLoop {
path: path.to_vec(),
});
}
if next.size > MAX_PATH as u64 {
return Err(ReadError::NotFound {
path: path.to_vec(),
});
}
let target = self.read_symlink(&next)?;
if target.is_empty() {
return Err(ReadError::NotFound {
path: path.to_vec(),
});
}
if target.starts_with(b"/") {
number = ROOT_INO;
inode = self.inode(number)?;
}
for c in components(&target).into_iter().rev() {
pending.push_front(c);
}
continue;
}
number = entry.inode;
inode = next;
}
Ok((number, inode))
}
pub fn walk(&mut self) -> Result<Vec<WalkEntry>, ReadError> {
let mut out = Vec::new();
self.walk_with::<ReadError>(|_, entry| {
out.push(entry);
Ok(())
})?;
Ok(out)
}
pub fn walk_with<E: From<ReadError>>(
&mut self,
mut visit: impl FnMut(&mut Self, WalkEntry) -> Result<(), E>,
) -> Result<(), E> {
let cap = self.limits.max_walk_entries.min(self.max_names());
let mut seen = 0usize;
let root = self.inode(ROOT_INO).map_err(E::from)?;
let mut visited = HashSet::new();
visited.insert(ROOT_INO);
let mut stack = self.walk_children(&root, &[]).map_err(E::from)?;
while let Some(entry) = stack.pop() {
if seen >= cap {
return Err(E::from(ReadError::WalkTooLarge { limit: cap }));
}
seen += 1;
if is_dir(&entry.inode) && visited.insert(entry.number) {
let children = self
.walk_children(&entry.inode, &entry.path)
.map_err(E::from)?;
stack.extend(children);
}
visit(self, entry)?;
}
Ok(())
}
fn walk_children(&mut self, inode: &Inode, prefix: &[u8]) -> Result<Vec<WalkEntry>, ReadError> {
let mut entries = self.read_dir(inode)?;
entries.sort_by(|a, b| a.name.cmp(&b.name));
let mut children = Vec::new();
for e in entries.iter().rev() {
if e.name == b"." || e.name == b".." {
continue;
}
if name_is_hostile(&e.name) {
continue;
}
let mut path = prefix.to_vec();
path.push(b'/');
path.extend_from_slice(&e.name);
let child = self.inode(e.inode)?;
children.push(WalkEntry {
path,
number: e.inode,
inode: child,
});
}
Ok(children)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::geometry::GrowReservation;
use crate::materialize::{FormatOptions, format};
use crate::ondisk::Timestamp;
use crate::source::{Metadata, TreeBuilder};
const MIB: u64 = 1024 * 1024;
fn opts() -> FormatOptions {
let mut o = FormatOptions::new([1u8; 16], Timestamp::from_secs(1_700_000_000), [0u8; 16]);
o.grow = GrowReservation::UpTo(32 * 1024 * MIB);
o
}
#[test]
fn an_io_failure_keeps_the_kind_it_was_classified_as() {
let truncated = ReadError::from(std::io::Error::new(
std::io::ErrorKind::UnexpectedEof,
"image ends mid-superblock",
));
let ReadError::Io { kind, message } = &truncated else {
panic!("expected an i/o error, got {truncated:?}");
};
assert_eq!(*kind, std::io::ErrorKind::UnexpectedEof);
assert!(message.contains("image ends mid-superblock"), "{message}");
assert!(
truncated.to_string().contains("image ends mid-superblock"),
"{truncated}"
);
let denied = ReadError::from(std::io::Error::from(std::io::ErrorKind::PermissionDenied));
assert!(matches!(
denied,
ReadError::Io {
kind: std::io::ErrorKind::PermissionDenied,
..
}
));
}
#[test]
fn a_size_past_the_logical_ceiling_is_not_a_length_a_read_yields() {
let time = Timestamp::from_secs(1_700_000_000);
let source = TreeBuilder::new().file(
b"/hello".to_vec(),
b"hi\n".to_vec(),
Metadata::new(0o644, time),
);
let image = format(source, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let (_, mut inode) = r.lookup(b"/hello").unwrap();
assert_eq!(r.file_len(&inode), 3);
let ceiling = MAX_LOGICAL_BLOCKS * r.block_size as u64;
for claimed in [ceiling + 1, ceiling * 2, u64::MAX] {
inode.size = claimed;
assert_eq!(r.file_len(&inode), ceiling, "claimed {claimed}");
}
inode.size = ceiling;
assert_eq!(r.file_len(&inode), ceiling);
}
fn walk_tree<R: Read + Seek>(r: &mut Reader<R>) -> std::collections::BTreeMap<Vec<u8>, Inode> {
r.walk()
.unwrap()
.into_iter()
.map(|e| (e.path, e.inode))
.collect()
}
#[test]
fn reads_back_an_empty_filesystem() {
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
assert_eq!(r.superblock().inodes_count, 16384);
let root = r.inode(2).unwrap();
let entries = r.read_dir(&root).unwrap();
let names: Vec<_> = entries.iter().map(|e| e.name.clone()).collect();
assert!(names.contains(&b".".to_vec()));
assert!(names.contains(&b"..".to_vec()));
assert!(names.contains(&b"lost+found".to_vec()));
}
#[test]
fn default_image_carries_a_readable_empty_journal() {
let image = format(TreeBuilder::new(), 512 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
assert!(r.feature().has_journal());
assert_eq!(r.superblock().journal_inum, 8);
assert_eq!(r.superblock().jnl_backup_type, 1);
let jsb = r.journal_superblock().unwrap().expect("has a journal");
assert_eq!(jsb.block_size, 4096);
assert_eq!(jsb.max_len, 4096);
assert_eq!(jsb.first, 1);
assert_eq!(jsb.sequence, 1);
assert_eq!(jsb.start, 0);
assert_eq!(jsb.nr_users, 1);
assert_eq!(jsb.uuid, [1u8; 16]);
let inode = r.inode(8).unwrap();
assert_eq!(inode.mode, 0o100600);
assert_eq!(inode.links_count, 1);
assert!(inode.flags.contains(InodeFlags::EXTENTS));
assert_eq!(inode.size, 4096 * 4096);
for (i, word) in inode.block.chunks_exact(4).enumerate() {
let w = u32::from_le_bytes([word[0], word[1], word[2], word[3]]);
assert_eq!(r.superblock().jnl_blocks[i], w, "jnl_blocks[{i}]");
}
assert_eq!(r.superblock().jnl_blocks[16], inode.size as u32);
}
#[test]
fn no_journal_feature_leaves_inode_eight_empty() {
let mut o = opts();
o.feature.compat = crate::feature::Compat::from_bits(
o.feature.compat.bits()
& !(crate::feature::Compat::HAS_JOURNAL.bits()
| crate::feature::Compat::ORPHAN_FILE.bits()),
);
let image = format(TreeBuilder::new(), 64 * MIB, o).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
assert!(!r.feature().has_journal());
assert_eq!(r.superblock().journal_inum, 0);
assert_eq!(r.superblock().jnl_backup_type, 0);
assert!(r.journal_superblock().unwrap().is_none());
let inode = r.inode(8).unwrap();
assert_eq!(inode.mode, 0);
assert_eq!(inode.links_count, 0);
assert_eq!(inode.size, 0);
assert_eq!(inode.blocks, 0);
}
#[test]
fn round_trips_a_populated_tree() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.directory(b"/etc".to_vec(), m(0o755))
.file(b"/etc/hostname".to_vec(), b"ferrosys\n".to_vec(), m(0o644))
.symlink(
b"/etc/mtab".to_vec(),
b"/proc/self/mounts".to_vec(),
m(0o777),
)
.file(
b"/big".to_vec(),
vec![0x42; 20_000],
m(0o600).owned_by(7, 9),
);
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let tree = walk_tree(&mut r);
let hostname = &tree[&b"/etc/hostname".to_vec()];
assert_eq!(r.read_data(hostname).unwrap(), b"ferrosys\n");
assert_eq!(hostname.mode, 0o100644);
let big = &tree[&b"/big".to_vec()];
assert_eq!(r.read_data(big).unwrap(), vec![0x42; 20_000]);
assert_eq!(big.uid, 7);
assert_eq!(big.gid, 9);
let mtab = &tree[&b"/etc/mtab".to_vec()];
assert_eq!(r.read_symlink(mtab).unwrap(), b"/proc/self/mounts");
assert_eq!(mtab.mode & 0o170000, 0o120000);
}
#[test]
fn round_trips_hardlinks_as_a_shared_inode() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.file(b"/a".to_vec(), b"shared".to_vec(), m(0o644))
.hardlink(b"/b".to_vec(), b"/a".to_vec(), m(0o644));
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let root = r.inode(2).unwrap();
let entries = r.read_dir(&root).unwrap();
let a = entries.iter().find(|e| e.name == b"a").unwrap().inode;
let b = entries.iter().find(|e| e.name == b"b").unwrap().inode;
assert_eq!(a, b, "hard links share one inode");
assert_eq!(r.inode(a).unwrap().links_count, 2);
}
#[test]
fn round_trips_a_slow_symlink() {
let time = Timestamp::from_secs(1_700_000_000);
let target = vec![b'p'; 200];
let src = TreeBuilder::new().symlink(
b"/link".to_vec(),
target.clone(),
Metadata::new(0o777, time),
);
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let root = r.inode(2).unwrap();
let link_ino = r
.read_dir(&root)
.unwrap()
.iter()
.find(|e| e.name == b"link")
.unwrap()
.inode;
let link = r.inode(link_ino).unwrap();
assert_eq!(r.read_symlink(&link).unwrap(), target);
}
fn inode_offset(bytes: &[u8], number: u32) -> usize {
let mut r = Reader::open(std::io::Cursor::new(bytes)).unwrap();
let inode_size = r.superblock().inode_size as usize;
let table = r.group_descriptor(0).unwrap().inode_table as usize;
table * 4096 + (number as usize - 1) * inode_size
}
#[test]
fn a_symlink_owning_a_data_block_reads_its_target_from_the_block() {
let time = Timestamp::from_secs(1_700_000_000);
let target = vec![b'p'; 200];
let src = TreeBuilder::new().symlink(
b"/link".to_vec(),
target.clone(),
Metadata::new(0o777, time),
);
let mut bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let ino = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
r.lookup_no_follow(b"/link").expect("lookup /link").0
};
let off = inode_offset(&bytes, ino);
crate::ondisk::put_u32(&mut bytes[off..], 0x04, 40);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let link = r.inode(ino).unwrap();
assert!(link.blocks > 0, "the symlink owns a data block");
assert_eq!(
r.read_symlink(&link).unwrap(),
target[..40].to_vec(),
"the target came from the block the inode owns, not from its block area"
);
}
#[test]
fn a_fast_symlink_carrying_an_attribute_block_still_reads_inline() {
let time = Timestamp::from_secs(1_700_000_000);
let target = b"/proc/self/mounts".to_vec();
let src = TreeBuilder::new()
.symlink(
b"/mtab".to_vec(),
target.clone(),
Metadata::new(0o777, time),
)
.xattr(b"user.blob".to_vec(), vec![0xAB; 300]);
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let (_, link) = r.lookup_no_follow(b"/mtab").expect("lookup /mtab");
assert_ne!(link.file_acl, 0, "the attribute set spilled to a block");
assert_ne!(link.blocks, 0, "which is charged to i_blocks");
assert_eq!(r.read_symlink(&link).unwrap(), target);
}
#[test]
fn a_fast_symlink_claiming_more_than_its_block_area_yields_the_area() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new().symlink(
b"/mtab".to_vec(),
b"/proc/self/mounts".to_vec(),
Metadata::new(0o777, time),
);
let mut bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let ino = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
r.lookup_no_follow(b"/mtab").expect("lookup /mtab").0
};
let off = inode_offset(&bytes, ino);
crate::ondisk::put_u32(&mut bytes[off..], 0x04, 100);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let link = r.inode(ino).unwrap();
assert_eq!(
r.read_symlink(&link).unwrap().len(),
Inode::BLOCK_BYTES,
"the read is bounded by the block area the target lives in"
);
}
#[test]
fn an_attribute_block_pointer_past_the_filesystem_is_refused() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new()
.file(b"/f".to_vec(), b"x".to_vec(), Metadata::new(0o644, time))
.xattr(b"user.blob".to_vec(), vec![0xAB; 300]);
let mut bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let (ino, blocks_count) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
(
r.lookup(b"/f").expect("lookup /f").0,
r.superblock().blocks_count,
)
};
let planted = crate::ondisk::Xattr {
name: b"user.neighbour".to_vec(),
value: b"from the next partition".to_vec(),
};
let neighbour = crate::ondisk::encode_block(std::slice::from_ref(&planted), 4096, false);
assert_eq!(
crate::ondisk::parse_block(&neighbour).unwrap(),
vec![planted],
"the planted block is a readable attribute block"
);
let at = usize::try_from(blocks_count).unwrap() * 4096;
bytes.resize(at + 4096, 0);
bytes[at..at + 4096].copy_from_slice(&neighbour);
let off = inode_offset(&bytes, ino);
crate::ondisk::put_u32(
&mut bytes[off..],
0x68,
u32::try_from(blocks_count).unwrap(),
);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let inode = r.inode(ino).unwrap();
assert_eq!(inode.file_acl, blocks_count);
assert!(
matches!(
r.xattrs(&inode),
Err(ReadError::OutOfRange { what: "block", index }) if index == blocks_count
),
"an attribute block outside the filesystem was read: {:?}",
r.xattrs(&inode)
);
}
#[test]
fn the_descriptor_stride_ignores_s_desc_size_without_64bit() {
let mut o = opts();
o.feature.incompat = o.feature.incompat.without(Incompat::SIXTY_FOUR_BIT);
o.grow = GrowReservation::None;
let bytes = format(TreeBuilder::new(), 256 * MIB, o)
.unwrap()
.into_bytes();
let pristine = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert_eq!(r.desc_size(), GroupDescriptor::SIZE_32);
assert!(
r.group_count() > 1,
"the image must span more than one group for the stride to show"
);
(0..r.group_count())
.map(|g| r.group_descriptor(g).unwrap())
.collect::<Vec<_>>()
};
let mut corrupt = bytes.clone();
put_u16(&mut corrupt[1024..], 0xfe, GroupDescriptor::SIZE_64 as u16);
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
assert_eq!(r.desc_size(), GroupDescriptor::SIZE_32);
let after: Vec<_> = (0..r.group_count())
.map(|g| r.group_descriptor(g).unwrap())
.collect();
assert_eq!(
after, pristine,
"a meaningless s_desc_size moved the descriptors"
);
let wide = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let r = Reader::open(std::io::Cursor::new(wide.as_bytes())).unwrap();
assert!(r.feature().is_64bit());
assert_eq!(r.desc_size(), GroupDescriptor::SIZE_64);
}
#[test]
fn a_64bit_superblock_rejects_an_out_of_bounds_desc_size() {
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
for bad in [32u16, 8192] {
let mut corrupt = image.as_bytes().to_vec();
put_u16(&mut corrupt[1024..], 0xfe, bad);
assert!(
matches!(
Reader::open(std::io::Cursor::new(&corrupt)),
Err(ReadError::Parse(ParseError::InvalidField {
field: "s_desc_size",
..
}))
),
"a 64bit image with s_desc_size={bad} must be refused at open"
);
}
assert!(Reader::open(std::io::Cursor::new(image.as_bytes())).is_ok());
}
#[test]
fn a_corrupted_index_tail_reserved_word_is_caught() {
let time = Timestamp::from_secs(1_700_000_000);
let mut o = opts();
o.feature.block_size = 1024;
o.grow = GrowReservation::None;
let mut src = TreeBuilder::new().directory(b"/d".to_vec(), Metadata::new(0o755, time));
for i in 0..64u32 {
let mut name = format!("/d/entry-{i:04}").into_bytes();
name.resize(b"/d/".len() + 200, b'x');
src = src.file(name, Vec::new(), Metadata::new(0o644, time));
}
let mut bytes = format(src, 64 * MIB, o).unwrap().into_bytes();
let (root_block, tail) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (_, dir) = r.lookup(b"/d").expect("the directory is present");
assert!(
dir.flags.contains(InodeFlags::INDEX),
"the directory must be hash-indexed for it to have an index tail"
);
r.verify_checksums()
.expect("it verifies clean to begin with");
let block = r.data_blocks(&dir).unwrap()[0];
let raw = r.block(block).unwrap();
let limit = usize::from(get_u16(&raw, DX_ROOT_COUNT_OFFSET));
(block, dx_tail_offset(DX_ROOT_COUNT_OFFSET, limit))
};
let at = usize::try_from(root_block).unwrap() * 1024 + tail;
assert_eq!(bytes[at..at + 4], [0; 4], "the writer leaves it zero");
bytes[at] = 0xff;
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert!(
matches!(
r.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "directory block",
..
})
),
"a flipped dt_reserved went unnoticed: {:?}",
r.verify_checksums()
);
}
#[test]
fn unsupported_features_are_reported_by_name() {
let d = describe_unsupported_incompat(
Incompat::META_BG.bits() | 0x0000_4000 | 0x0000_8000 | 0x8000_0000,
);
for name in ["meta_bg", "large_dir", "inline_data", "0x80000000"] {
assert!(d.contains(name), "{name} is missing from {d:?}");
}
let order: Vec<usize> = ["meta_bg", "large_dir", "inline_data", "0x80000000"]
.iter()
.map(|n| d.find(n).unwrap())
.collect();
assert!(
order.windows(2).all(|w| w[0] < w[1]),
"features are listed in ascending bit order: {d:?}"
);
}
#[test]
fn every_incompat_bit_is_named_by_exactly_one_table() {
for (name, bit) in UNMODELLED_INCOMPAT {
assert_eq!(bit.count_ones(), 1, "{name} names exactly one bit");
assert!(
Incompat::from_bits(*bit).names().is_empty(),
"{name} ({bit:#x}) is named by the feature word too"
);
assert_eq!(
bit & SUPPORTED_INCOMPAT,
0,
"{name} ({bit:#x}) is a feature the reader claims to follow"
);
}
}
#[test]
fn round_trips_inline_and_block_xattrs() {
let time = Timestamp::from_secs(1_700_000_000);
let cap = vec![
0x01, 0x00, 0x00, 0x02, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
];
let src = TreeBuilder::new()
.directory(b"/bin".to_vec(), Metadata::new(0o755, time))
.file(
b"/bin/ping".to_vec(),
b"elf".to_vec(),
Metadata::new(0o755, time),
)
.xattr(b"security.capability".to_vec(), cap.clone())
.xattr(b"user.note".to_vec(), b"hi".to_vec())
.file(b"/big".to_vec(), b"x".to_vec(), Metadata::new(0o644, time))
.xattr(b"user.blob".to_vec(), vec![0xAB; 300]);
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let tree = walk_tree(&mut r);
let ping = &tree[&b"/bin/ping".to_vec()];
assert_eq!(ping.file_acl, 0, "small set stays inline, no acl block");
let mut got = r.xattrs(ping).unwrap();
got.sort_by(|a, b| a.name.cmp(&b.name));
assert_eq!(got.len(), 2);
assert_eq!(got[0].name, b"security.capability");
assert_eq!(got[0].value, cap);
assert_eq!(got[1].name, b"user.note");
let big = &tree[&b"/big".to_vec()];
assert_ne!(big.file_acl, 0, "large value spilled to a block");
let blob = r.xattrs(big).unwrap();
assert_eq!(blob.len(), 1);
assert_eq!(blob[0].name, b"user.blob");
assert_eq!(blob[0].value, vec![0xAB; 300]);
}
#[test]
fn a_xattr_set_splits_between_the_inode_and_its_block() {
let time = Timestamp::from_secs(1_700_000_000);
let huge = vec![0xAA; 4040];
let tiny = vec![0xBB; 60];
let src = TreeBuilder::new()
.file(b"/f".to_vec(), b"x".to_vec(), Metadata::new(0o644, time))
.xattr(b"user.huge".to_vec(), huge.clone())
.xattr(b"user.tiny".to_vec(), tiny.clone());
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let tree = walk_tree(&mut r);
let f = &tree[&b"/f".to_vec()];
assert_ne!(f.file_acl, 0, "the huge value spilled to a block");
let inline = parse_inline(&f.inline_xattr).unwrap();
assert_eq!(inline.len(), 1, "the tiny value stayed inline");
assert_eq!(inline[0].name, b"user.tiny");
let mut got = r.xattrs(f).unwrap();
got.sort_by(|a, b| a.name.cmp(&b.name));
assert_eq!(got.len(), 2, "both regions read back as one set");
assert_eq!(got[0].name, b"user.huge");
assert_eq!(got[0].value, huge);
assert_eq!(got[1].name, b"user.tiny");
assert_eq!(got[1].value, tiny);
}
#[test]
fn round_trips_device_fifo_and_socket_nodes() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.directory(b"/dev".to_vec(), m(0o755))
.char_device(b"/dev/null".to_vec(), 1, 3, m(0o666))
.block_device(b"/dev/sda".to_vec(), 8, 0, m(0o660))
.fifo(b"/dev/initctl".to_vec(), m(0o600))
.socket(b"/dev/log".to_vec(), m(0o666));
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let tree = walk_tree(&mut r);
let null = &tree[&b"/dev/null".to_vec()];
assert_eq!(null.mode & 0o170000, 0o020000, "char device");
assert_eq!(null.mode & 0o7777, 0o666);
assert_eq!(r.device(null), (1, 3));
assert_eq!(null.blocks, 0, "no data blocks");
let sda = &tree[&b"/dev/sda".to_vec()];
assert_eq!(sda.mode & 0o170000, 0o060000, "block device");
assert_eq!(r.device(sda), (8, 0));
assert_eq!(
tree[&b"/dev/initctl".to_vec()].mode & 0o170000,
0o010000,
"fifo"
);
assert_eq!(
tree[&b"/dev/log".to_vec()].mode & 0o170000,
0o140000,
"socket"
);
}
#[test]
fn round_trips_distinct_and_fixed_timestamps() {
let m = Metadata::new(0o644, Timestamp::from_secs(500)).with_times(
Timestamp::from_secs(100),
Timestamp::from_secs(200),
Timestamp::from_secs(300),
);
let src = TreeBuilder::new().file(b"/f".to_vec(), b"x".to_vec(), m);
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let root = r.inode(2).unwrap();
let f_ino = r
.read_dir(&root)
.unwrap()
.iter()
.find(|e| e.name == b"f")
.unwrap()
.inode;
let f = r.inode(f_ino).unwrap();
assert_eq!(f.atime, Timestamp::from_secs(100));
assert_eq!(f.ctime, Timestamp::from_secs(200));
assert_eq!(f.mtime, Timestamp::from_secs(300));
assert_eq!(
f.crtime,
Timestamp::from_secs(300),
"crtime derives from mtime"
);
let mut fixed = opts();
fixed.fixed_time = Some(Timestamp::from_secs(42));
let src = TreeBuilder::new().file(b"/f".to_vec(), b"x".to_vec(), m);
let image = format(src, 64 * MIB, fixed).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let root = r.inode(2).unwrap();
let f_ino = r
.read_dir(&root)
.unwrap()
.iter()
.find(|e| e.name == b"f")
.unwrap()
.inode;
let f = r.inode(f_ino).unwrap();
assert_eq!(f.atime, Timestamp::from_secs(42));
assert_eq!(f.mtime, Timestamp::from_secs(42));
assert_eq!(f.crtime, Timestamp::from_secs(42));
}
#[test]
fn the_fixed_time_clamp_reaches_the_reserved_structural_inodes() {
let format_time = Timestamp::from_secs(1_700_000_000);
let clamp = Timestamp::from_secs(42);
assert_ne!(
clamp, format_time,
"the clamp must differ from the format time"
);
let mut fixed = opts();
fixed.fixed_time = Some(clamp);
let image = format(TreeBuilder::new(), 64 * MIB, fixed).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
for ino in [7u32, 8, 12] {
let s = r.inode(ino).unwrap();
assert_eq!(
(s.atime, s.ctime, s.mtime, s.crtime),
(clamp, clamp, clamp, clamp),
"inode {ino}'s times honor the clamp, not the format time"
);
}
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
for ino in [7u32, 8, 12] {
assert_eq!(
r.inode(ino).unwrap().mtime,
format_time,
"inode {ino} takes the format time when the clamp is unset"
);
}
}
#[test]
fn verifies_metadata_checksums_and_detects_corruption() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.directory(b"/etc".to_vec(), m(0o755))
.file(b"/etc/hostname".to_vec(), b"ferrosys\n".to_vec(), m(0o644))
.file(b"/big".to_vec(), vec![0x42; 20_000], m(0o600));
let bytes = format(src, 512 * MIB, opts()).unwrap().into_bytes();
Reader::open(std::io::Cursor::new(&bytes))
.unwrap()
.verify_checksums()
.unwrap();
let mut corrupt = bytes.clone();
corrupt[1024 + 0x30] ^= 0xff; assert!(matches!(
Reader::open(std::io::Cursor::new(&corrupt))
.unwrap()
.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "superblock",
..
})
));
let root_off = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
r.group_descriptor(0).unwrap().inode_table as usize * 4096 + 256
};
let mut corrupt = bytes.clone();
corrupt[root_off] ^= 0xff; assert!(matches!(
Reader::open(std::io::Cursor::new(&corrupt))
.unwrap()
.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "inode",
index: 2,
..
})
));
let desc_size = {
let r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
r.superblock().desc_size as usize
};
assert_eq!(desc_size, 64, "the default feature set sets 64bit");
let mut corrupt = bytes.clone();
corrupt[4096 + desc_size + 0x0c] ^= 0xff; assert!(matches!(
Reader::open(std::io::Cursor::new(&corrupt))
.unwrap()
.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "group descriptor",
index: 1,
..
})
));
}
#[test]
fn verifies_bitmap_directory_and_xattr_checksums() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.directory(b"/etc".to_vec(), m(0o755))
.file(b"/etc/hostname".to_vec(), b"ferrosys\n".to_vec(), m(0o644))
.file(b"/etc/big".to_vec(), b"x".to_vec(), m(0o644))
.xattr(b"user.big".to_vec(), vec![0xcd; 400]);
let bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
{
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
r.verify_checksums()
.expect("a well-formed image verifies clean");
let report = r.scan();
assert!(
report.anomalies.is_empty(),
"a clean image scans clean, got {:?}",
report.anomalies
);
}
let (bitmap_block, dir_block, xattr_block) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let bitmap_block = r.group_descriptor(0).unwrap().block_bitmap;
let root = r.inode(2).unwrap();
let dir_block = r.extent_leaves(&root).unwrap()[0].start;
let mut xattr_block = 0u64;
for e in r.walk().unwrap() {
if e.path == b"/etc/big" {
xattr_block = e.inode.file_acl;
}
}
assert_ne!(xattr_block, 0, "the file has an external attribute block");
(bitmap_block, dir_block, xattr_block)
};
let bs = 4096u64;
let corrupt_at = |block: u64, within: u64| {
let mut c = bytes.clone();
c[(block * bs + within) as usize] ^= 0xff;
c
};
let c = corrupt_at(bitmap_block, 0);
let mut r = Reader::open(std::io::Cursor::new(&c)).unwrap();
assert!(matches!(
r.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "block bitmap",
..
})
));
assert!(
r.scan()
.anomalies
.iter()
.any(|a| a.category == Category::Bitmap),
"scan reports a Bitmap anomaly"
);
let c = corrupt_at(dir_block, 40);
let mut r = Reader::open(std::io::Cursor::new(&c)).unwrap();
assert!(matches!(
r.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "directory block",
..
})
));
assert!(
r.scan()
.anomalies
.iter()
.any(|a| a.category == Category::Directory),
"scan reports a Directory anomaly"
);
let c = corrupt_at(xattr_block, 32);
let mut r = Reader::open(std::io::Cursor::new(&c)).unwrap();
assert!(matches!(
r.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "xattr block",
..
})
));
assert!(
r.scan()
.anomalies
.iter()
.any(|a| a.category == Category::Xattr),
"scan reports an Xattr anomaly"
);
}
#[test]
fn verifies_a_two_level_htree_with_interior_index_nodes() {
let time = Timestamp::from_secs(1_700_000_000);
let mut o = opts();
o.feature.block_size = 1024;
o.grow = GrowReservation::None;
let mut src = TreeBuilder::new().directory(b"/bigdir".to_vec(), Metadata::new(0o755, time));
for i in 0..800u32 {
let mut name = format!("/bigdir/entry-{i:04}").into_bytes();
name.resize(b"/bigdir/".len() + 200, b'x');
src = src.file(name, Vec::new(), Metadata::new(0o644, time));
}
let bytes = format(src, 64 * MIB, o).unwrap().into_bytes();
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (_, dir) = r.lookup(b"/bigdir").expect("the directory is present");
assert!(
dir.flags.contains(InodeFlags::INDEX),
"an 800-entry directory must be hash-indexed"
);
let block_count = dir.size / 1024;
assert!(
block_count > 124,
"a two-level tree spans more than a one-level root's 123 leaves and its \
root, but this directory is {block_count} blocks — the interior level \
this test exists to exercise was never grown"
);
r.verify_checksums()
.expect("a well-formed two-level htree verifies clean");
assert!(
r.scan().anomalies.is_empty(),
"a clean two-level htree scans clean, got {:?}",
r.scan().anomalies
);
let names: std::collections::BTreeSet<Vec<u8>> = r
.read_dir(&dir)
.expect("read_dir")
.into_iter()
.filter(|e| e.name != b"." && e.name != b"..")
.map(|e| e.name)
.collect();
assert_eq!(names.len(), 800, "every name survives the two-level index");
}
#[test]
fn the_orphan_files_blocks_carry_their_magic_and_checksum() {
let bytes = format(TreeBuilder::new(), 64 * MIB, opts())
.unwrap()
.into_bytes();
let (first_block, blocks) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let ino = r.superblock().orphan_file_inum;
assert_eq!(ino, 12, "the orphan file takes the inode past /lost+found");
let inode = r.inode(ino).unwrap();
assert_eq!(inode.links_count, 1);
assert_eq!(
inode.size,
32 * 4096,
"the size heuristic's floor at 64 MiB"
);
let leaves = r.extent_leaves(&inode).unwrap();
(leaves[0].start, u64::from(leaves[0].len))
};
assert_eq!(blocks, 32, "the file maps as one contiguous run");
{
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
r.verify_checksums().expect("the orphan tails verify");
assert!(r.scan().anomalies.is_empty());
}
let bs = 4096u64;
let corrupt_at = |offset: u64| {
let mut c = bytes.clone();
c[offset as usize] ^= 0xff;
c
};
let last = first_block + blocks - 1;
let c = corrupt_at((last + 1) * bs - 4);
let mut r = Reader::open(std::io::Cursor::new(&c)).unwrap();
assert!(matches!(
r.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "orphan block",
..
})
));
assert!(
r.scan()
.anomalies
.iter()
.any(|a| a.category == Category::Orphan),
"scan reports an Orphan anomaly"
);
let c = corrupt_at((first_block + 1) * bs - 8);
let mut r = Reader::open(std::io::Cursor::new(&c)).unwrap();
assert!(matches!(
r.verify_checksums(),
Err(ReadError::BadOrphanFile)
));
let mut c = bytes.clone();
c[1024 + 0x280..1024 + 0x284].copy_from_slice(&0u32.to_le_bytes());
let mut r = Reader::open(std::io::Cursor::new(&c)).unwrap();
assert!(
r.scan()
.anomalies
.iter()
.any(|a| a.category == Category::Orphan),
"a feature with no file behind it is an Orphan anomaly"
);
}
#[test]
fn a_scan_is_bounded_by_the_bytes_that_exist_not_the_claimed_block_count() {
let bytes = format(TreeBuilder::new(), 64 * MIB, opts())
.unwrap()
.into_bytes();
let mut corrupt = bytes.clone();
crate::ondisk::put_u32(&mut corrupt[1024 + 0x04..], 0, 0xffff_ffff);
crate::ondisk::put_u32(&mut corrupt[1024 + 0x150..], 0, 0xffff_ffff);
let mut r = Reader::open_with(
std::io::Cursor::new(&corrupt),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let report = r.scan();
assert!(
report.anomalies().len() < 64,
"the scan reported {} anomalies for a 64 MiB image — it is walking the \
claimed group count, not the source",
report.anomalies().len()
);
}
#[test]
fn verify_checksums_ignores_a_hostile_free_inode_count() {
let bytes = format(TreeBuilder::new(), 64 * MIB, opts())
.unwrap()
.into_bytes();
let mut corrupt = bytes.clone();
crate::ondisk::put_u32(&mut corrupt[1024 + 0x10..], 0, 0xffff_ffff);
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
let _ = r.verify_checksums();
let _ = r.scan();
}
#[test]
fn open_rejects_a_bad_superblock() {
let mut bytes = vec![0u8; 4096 * 16];
assert!(matches!(
Reader::open(std::io::Cursor::new(&bytes)),
Err(ReadError::Parse(ParseError::BadMagic { .. }))
));
bytes.truncate(512);
assert!(Reader::open(std::io::Cursor::new(&bytes)).is_err());
}
#[test]
fn multi_group_image_round_trips() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new().file(
b"/f".to_vec(),
b"multi-group".to_vec(),
Metadata::new(0o644, time),
);
let image = format(src, 512 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
assert_eq!(r.superblock().blocks_count, 131072);
let g3 = r.group_descriptor(3).unwrap();
assert_eq!(g3.block_bitmap, 8);
assert_eq!(g3.inode_table, 1549);
let root = r.inode(2).unwrap();
let f = r
.read_dir(&root)
.unwrap()
.iter()
.find(|e| e.name == b"f")
.unwrap()
.inode;
let f_inode = r.inode(f).unwrap();
assert_eq!(r.read_data(&f_inode).unwrap(), b"multi-group");
}
#[test]
fn opens_a_filesystem_at_an_arbitrary_offset() {
let time = Timestamp::from_secs(1);
let src = TreeBuilder::new().file(
b"/hi".to_vec(),
b"there".to_vec(),
Metadata::new(0o644, time),
);
let image = format(src, 64 * MIB, opts()).unwrap();
let base = 1_048_576u64; let mut padded = vec![0x9au8; base as usize];
padded.extend_from_slice(image.as_bytes());
let mut r = Reader::open_with(
std::io::Cursor::new(&padded),
&OpenOptions::new().base(base),
)
.unwrap();
assert_eq!(r.policy(), ReadPolicy::Strict);
let root = r.inode(2).unwrap();
let names: Vec<_> = r
.read_dir(&root)
.unwrap()
.into_iter()
.map(|e| e.name)
.collect();
assert!(names.contains(&b"hi".to_vec()));
let hi = r
.walk()
.unwrap()
.into_iter()
.find(|e| e.path == b"/hi")
.unwrap()
.inode;
assert_eq!(r.read_data(&hi).unwrap(), b"there");
assert!(Reader::open(std::io::Cursor::new(&padded)).is_err());
}
#[test]
fn open_with_refuses_a_base_that_overflows_the_superblock_position() {
let src = std::io::Cursor::new(vec![0u8; 4096]);
assert!(matches!(
Reader::open_with(src, &OpenOptions::new().base(u64::MAX).policy(ReadPolicy::Lenient)),
Err(ReadError::OutOfRange {
what: "bytes",
index
}) if index == u64::MAX
));
}
#[test]
fn errors_classify_as_typed_anomalies() {
let a = ReadError::NoSuchInode { inode: 7 }.anomaly();
assert_eq!(a.severity, Severity::Structural);
assert_eq!(a.category, Category::Inode);
assert_eq!(a.location.inode, Some(7));
let cm = ReadError::ChecksumMismatch {
object: "inode",
index: 2,
stored: 1,
computed: 2,
}
.anomaly();
assert_eq!(cm.severity, Severity::Integrity);
assert_eq!(cm.category, Category::Inode);
assert_eq!(cm.location.inode, Some(2));
let oor = ReadError::OutOfRange {
what: "block",
index: 99,
}
.anomaly();
assert_eq!(oor.severity, Severity::Structural);
assert_eq!(oor.category, Category::Superblock);
assert_eq!(oor.location.block, Some(99));
assert!(ReadPolicy::Strict.is_fatal(Severity::Structural));
assert!(ReadPolicy::Strict.is_fatal(Severity::Integrity));
assert!(ReadPolicy::Strict.is_fatal(Severity::Conformance));
assert!(!ReadPolicy::Strict.is_fatal(Severity::Cosmetic));
assert_eq!(ReadPolicy::default(), ReadPolicy::Strict);
}
#[test]
fn lenient_policy_is_fatal_at_nothing() {
for sev in [
Severity::Cosmetic,
Severity::Conformance,
Severity::Integrity,
Severity::Structural,
] {
assert!(!ReadPolicy::Lenient.is_fatal(sev), "{sev:?} under lenient");
}
assert!(ReadPolicy::Strict.is_fatal(Severity::Structural));
assert!(!ReadPolicy::Strict.is_fatal(Severity::Cosmetic));
assert_eq!(ReadPolicy::default(), ReadPolicy::Strict);
}
#[test]
fn scans_a_clean_multigroup_image_as_clean() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.directory(b"/etc".to_vec(), m(0o755))
.file(b"/etc/hostname".to_vec(), b"ferrosys\n".to_vec(), m(0o644))
.file(b"/big".to_vec(), vec![0x42; 200_000], m(0o600));
let image = format(src, 512 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let report = r.scan();
assert!(
report.is_clean(),
"unexpected anomalies: {:?}",
report.anomalies()
);
assert_eq!(report.worst_severity(), None);
assert!(!report.has_fatal(ReadPolicy::Strict));
assert!(!report.has_fatal(ReadPolicy::Lenient));
assert_eq!(report.to_table(), "no anomalies\n");
assert!(!report.is_truncated());
assert_eq!(
report.to_json(),
"{\"schema\":1,\"clean\":true,\"count\":0,\"truncated\":false,\"anomalies\":[]}"
);
}
fn opts_no_csum() -> FormatOptions {
let mut o = opts();
o.feature = FeatureSet::DEFAULT
.with_feature("metadata_csum", false)
.expect("a known name")
.with_feature("metadata_csum_seed", false)
.expect("a known name");
assert_eq!(o.feature.validate(), Ok(()));
o
}
#[test]
fn refuses_an_unsupported_incompat_feature_and_reports_it() {
let clean = format(TreeBuilder::new(), 64 * MIB, opts())
.unwrap()
.into_bytes();
assert!(Reader::open(std::io::Cursor::new(&clean)).is_ok());
let incompat = 1024 + 0x60;
for (name, byte, mask, want) in [
("meta_bg", 0, 0x10u8, 0x10u32),
("unknown high bit", 3, 0x80u8, 0x8000_0000u32),
] {
let mut bytes = clean.clone();
bytes[incompat + byte] |= mask;
assert_eq!(
Reader::open(std::io::Cursor::new(&bytes)).err(),
Some(ReadError::UnsupportedIncompat { bits: want }),
"a strict open refuses {name}",
);
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap_or_else(|_| panic!("a lenient open accepts {name}"));
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.category == Category::Superblock && a.severity == Severity::Structural);
let found = found.unwrap_or_else(|| {
panic!("scan reports {name} as a structural superblock anomaly: {report:?}")
});
assert!(
found.detail.contains(name) || found.detail.contains("0x80000000"),
"the anomaly names the feature it found: {}",
found.detail
);
assert!(report.has_fatal(ReadPolicy::Strict));
}
}
#[test]
fn flags_an_extent_flagged_inode_without_the_extent_feature() {
let src = TreeBuilder::new().file(
b"/hello".to_vec(),
b"world\n".to_vec(),
Metadata::new(0o644, Timestamp::from_secs(1_700_000_000)),
);
let mut bytes = format(src, 64 * MIB, opts_no_csum()).unwrap().into_bytes();
bytes[1024 + 0x60] &= !0x40;
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(!r.feature().has_extents());
let report = r.scan();
let flagged: Vec<u32> = report
.anomalies()
.iter()
.filter(|a| {
a.category == Category::Inode
&& a.severity == Severity::Structural
&& a.detail.contains("extent format")
})
.filter_map(|a| a.location.inode)
.collect();
assert!(
flagged.contains(&ROOT_INO),
"the root inode is flagged: {report:?}"
);
assert!(
flagged.len() >= 2,
"every extent-mapped inode is flagged: {flagged:?}"
);
assert!(report.has_fatal(ReadPolicy::Strict));
}
fn craft_extent_inode(
bytes: &mut [u8],
number: u32,
mode: u16,
runs: u32,
len: u16,
start: u64,
size: u64,
) {
use crate::ondisk::{EXTENT_ENTRY_SIZE, ExtentHeader, ExtentLeaf};
let mut inode = Inode::empty(256);
inode.mode = mode;
inode.links_count = 1;
inode.flags = InodeFlags::EXTENTS;
inode.size = size;
let header = ExtentHeader {
entries: runs as u16,
max: runs as u16,
depth: 0,
generation: 0,
};
inode.block[..EXTENT_ENTRY_SIZE].copy_from_slice(&header.to_bytes());
for r in 0..runs {
let leaf = ExtentLeaf {
block: r * u32::from(len),
len,
start,
initialized: true,
};
let off = EXTENT_ENTRY_SIZE * (1 + r as usize);
inode.block[off..off + EXTENT_ENTRY_SIZE]
.copy_from_slice(&leaf.to_bytes().expect("a representable run"));
}
let at = inode_offset(bytes, number);
inode
.write_to(&mut bytes[at..at + 256], 256)
.expect("write the crafted inode");
}
#[test]
fn a_directory_mapping_one_block_many_times_is_judged_once_per_block() {
const RUNS: u32 = 4;
const LEN: u16 = 1000;
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut bytes = image.into_bytes();
craft_extent_inode(
&mut bytes,
3,
0o040755,
RUNS,
LEN,
2000,
u64::from(u32::MAX),
);
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let report = r.scan();
let per_block = report
.anomalies()
.iter()
.filter(|a| a.category == Category::Directory && a.location.inode == Some(3))
.count();
assert_eq!(
per_block,
LEN as usize,
"one finding per block named, not per logical offset ({} offsets name {LEN} blocks)",
RUNS as usize * LEN as usize
);
assert!(!report.is_truncated(), "this image is fully scanned");
}
#[test]
fn a_report_stops_at_its_cap_and_says_so() {
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut bytes = image.into_bytes();
for number in [3u32, 4, 5] {
craft_extent_inode(
&mut bytes,
number,
0o040755,
4,
4000,
2000,
u64::from(u32::MAX),
);
}
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let report = r.scan();
assert!(
report.is_truncated(),
"a report past the cap says it stopped short"
);
assert_eq!(
report.anomalies().len(),
ScanReport::MAX_ANOMALIES,
"a truncated report holds exactly the cap"
);
assert!(report.to_json().contains("\"truncated\":true"));
assert!(report.to_table().contains("report truncated at 10000"));
assert!(
report
.to_sarif(None)
.contains("\"toolExecutionNotifications\""),
"SARIF records the short run as a notification about the invocation"
);
assert!(report.has_fatal(ReadPolicy::Strict));
let mut tight = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new()
.policy(ReadPolicy::Lenient)
.limits(Limits::new().max_anomalies(7)),
)
.unwrap();
let short = tight.scan();
assert!(short.is_truncated());
assert_eq!(short.anomalies().len(), 7);
let notice = "report truncated at 7 anomalies; the rest of the image was not scanned";
assert!(short.to_table().contains(notice), "{}", short.to_table());
assert!(short.to_sarif(None).contains(notice));
let mut none = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new()
.policy(ReadPolicy::Lenient)
.limits(Limits::new().max_anomalies(0)),
)
.unwrap();
let empty = none.scan();
assert!(empty.is_truncated());
assert!(empty.anomalies().is_empty());
assert!(
!empty.is_clean(),
"a truncated report claimed the image was clean"
);
assert!(empty.to_json().contains("\"clean\":false"));
assert!(empty.to_table().contains("report truncated at 0 anomalies"));
}
#[test]
fn a_walk_is_bounded_by_the_names_the_source_has_room_for() {
let source = TreeBuilder::new()
.directory(
b"/a".to_vec(),
Metadata::new(0o755, Timestamp::from_secs(0)),
)
.file(
b"/a/f".to_vec(),
b"x".to_vec(),
Metadata::new(0o644, Timestamp::from_secs(0)),
);
let image = format(source, 64 * MIB, opts()).unwrap();
let bytes = image.into_bytes();
let mut r = Reader::open_with(std::io::Cursor::new(&bytes), &OpenOptions::new()).unwrap();
let full = r.walk().unwrap();
assert!(full.len() >= 3, "{full:?}");
let mut capped = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().limits(Limits::new().max_walk_entries(2)),
)
.unwrap();
assert!(matches!(
capped.walk(),
Err(ReadError::WalkTooLarge { limit: 2 })
));
}
#[test]
fn a_file_read_is_capped_only_where_a_caller_asks() {
let source = TreeBuilder::new().file(
b"/f".to_vec(),
vec![7u8; 8192],
Metadata::new(0o644, Timestamp::from_secs(0)),
);
let image = format(source, 64 * MIB, opts()).unwrap();
let bytes = image.into_bytes();
let mut r = Reader::open_with(std::io::Cursor::new(&bytes), &OpenOptions::new()).unwrap();
let (_, inode) = r.lookup(b"/f").unwrap();
assert_eq!(r.read_data(&inode).unwrap().len(), 8192);
let mut capped = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().limits(Limits::new().max_file_bytes(100)),
)
.unwrap();
let (_, inode) = capped.lookup(b"/f").unwrap();
assert!(matches!(
capped.read_data(&inode),
Err(ReadError::FileTooLarge {
size: 8192,
limit: 100
})
));
let mut sink = Vec::new();
assert!(matches!(
capped.read_data_to(&inode, &mut sink),
Err(ReadError::FileTooLarge { .. })
));
assert!(sink.is_empty(), "nothing is written before the refusal");
let mut buf = [0u8; 100];
assert_eq!(capped.read_into(&inode, 0, &mut buf).unwrap(), 100);
assert_eq!(buf, [7u8; 100]);
}
#[test]
fn a_capped_read_never_maps_the_claim_behind_it() {
const CLAIM: u64 = 1 << 44; let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut bytes = image.into_bytes();
craft_extent_inode(&mut bytes, 12, 0o100600, 1, 4, 2000, CLAIM);
for cap in [0u64, 10, 8192] {
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new()
.policy(ReadPolicy::Lenient)
.limits(Limits::new().max_file_bytes(cap)),
)
.unwrap();
let inode = r.inode(12).unwrap();
assert!(
matches!(
r.read_data(&inode),
Err(ReadError::FileTooLarge { size: CLAIM, .. })
),
"a {CLAIM}-byte claim must be refused under a {cap}-byte cap"
);
}
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let inode = r.inode(12).unwrap();
let mut buf = [0u8; 4096];
assert_eq!(r.read_into(&inode, 0, &mut buf).unwrap(), 4096);
}
#[test]
fn a_ranged_read_reads_the_window_it_is_given() {
for label in ["extent", "block-mapped"] {
let mut o = opts();
if label == "block-mapped" {
o.feature = FeatureSet::EXT2;
}
let mut contents = Vec::new();
for block in 0..20u8 {
contents.extend(std::iter::repeat_n(block, 4096));
}
let source = TreeBuilder::new().file(
b"/f".to_vec(),
contents.clone(),
Metadata::new(0o644, Timestamp::from_secs(0)),
);
let image = format(source, 64 * MIB, o).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let (_, inode) = r.lookup(b"/f").unwrap();
assert_eq!(
r.read_data(&inode).unwrap(),
contents,
"{label}: whole file"
);
for (offset, len) in [
(0usize, 10usize),
(4090, 12),
(65536, 8192),
(4096 * 19, 4096),
] {
let mut buf = vec![0u8; len];
let filled = r.read_into(&inode, offset as u64, &mut buf).unwrap();
assert_eq!(filled, len, "{label}: {len} bytes at {offset}");
assert_eq!(&buf[..filled], &contents[offset..offset + len]);
}
let mut buf = vec![0u8; 4096];
let filled = r
.read_into(&inode, contents.len() as u64 - 10, &mut buf)
.unwrap();
assert_eq!(filled, 10, "{label}: a read at the end is short");
assert_eq!(
r.read_into(&inode, contents.len() as u64, &mut buf)
.unwrap(),
0,
"{label}: a read past the end fills nothing"
);
let mut sink = Vec::new();
assert_eq!(
r.read_data_to(&inode, &mut sink).unwrap(),
contents.len() as u64
);
assert_eq!(sink, contents, "{label}: streamed bytes");
}
}
#[test]
fn a_ranged_read_of_a_sparse_file_reads_holes_as_zeros() {
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut bytes = image.into_bytes();
craft_extent_inode(&mut bytes, 12, 0o100600, 1, 4, 2000, 4 * 4096);
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let inode = r.inode(12).unwrap();
let mut buf = vec![0xffu8; 8192];
let filled = r.read_into(&inode, 4096, &mut buf).unwrap();
assert_eq!(filled, 8192);
assert!(
buf.iter().all(|&b| b == 0),
"a hole reads as zeros, overwriting the buffer's previous contents"
);
}
#[test]
fn a_walk_with_visits_every_name_without_gathering_them() {
let time = Timestamp::from_secs(0);
let source = TreeBuilder::new()
.directory(b"/etc".to_vec(), Metadata::new(0o755, time))
.file(
b"/etc/hostname".to_vec(),
b"host\n".to_vec(),
Metadata::new(0o644, time),
)
.directory(b"/usr".to_vec(), Metadata::new(0o755, time))
.file(
b"/usr/x".to_vec(),
b"x".to_vec(),
Metadata::new(0o644, time),
);
let image = format(source, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let gathered: Vec<Vec<u8>> = r.walk().unwrap().into_iter().map(|e| e.path).collect();
let mut streamed = Vec::new();
let mut bytes_seen = 0u64;
r.walk_with::<ReadError>(|reader, entry| {
if entry.inode.mode & 0o170000 == 0o100000 {
bytes_seen += reader.read_data(&entry.inode)?.len() as u64;
}
streamed.push(entry.path);
Ok(())
})
.unwrap();
assert_eq!(streamed, gathered);
assert_eq!(bytes_seen, 6, "hostname's five bytes and x's one");
let mut count = 0usize;
let stopped = r.walk_with::<ReadError>(|_, _| {
count += 1;
if count == 2 {
return Err(ReadError::BadJournal);
}
Ok(())
});
assert!(matches!(stopped, Err(ReadError::BadJournal)));
assert_eq!(count, 2, "the walk stops at the failing entry");
let mut capped = Reader::open_with(
std::io::Cursor::new(image.as_bytes()),
&OpenOptions::new().limits(Limits::new().max_walk_entries(2)),
)
.unwrap();
assert!(matches!(
capped.walk_with::<ReadError>(|_, _| Ok(())),
Err(ReadError::WalkTooLarge { limit: 2 })
));
}
#[test]
fn a_named_seed_overrides_the_one_the_image_implies() {
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let bytes = image.into_bytes();
let mut own = Reader::open_with(std::io::Cursor::new(&bytes), &OpenOptions::new()).unwrap();
own.verify_checksums()
.expect("the image verifies against its own seed");
let mut wrong = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().csum_seed(0xdead_beef),
)
.unwrap();
assert!(
matches!(
wrong.verify_checksums(),
Err(ReadError::ChecksumMismatch { .. })
),
"a seed the image's checksums were not computed from must not verify"
);
}
#[test]
fn the_journal_and_orphan_file_are_read_within_the_image_they_claim_to_be_in() {
const CLAIM: u64 = 1 << 44; let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut bytes = image.into_bytes();
craft_extent_inode(&mut bytes, 8, 0o100600, 1, 4, 2000, CLAIM);
craft_extent_inode(&mut bytes, 12, 0o100600, 1, 4, 2000, CLAIM);
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert_eq!(r.superblock().journal_inum, 8);
assert_eq!(r.superblock().orphan_file_inum, 12);
let report = r.scan();
assert!(
report
.anomalies()
.iter()
.any(|a| a.category == Category::Orphan),
"the orphan file's claim is faulted: {}",
report.to_table()
);
assert!(
report
.anomalies()
.iter()
.any(|a| a.category == Category::Journal),
"the journal's first block is judged: {}",
report.to_table()
);
assert!(matches!(
r.journal_superblock(),
Err(ReadError::Parse(_) | ReadError::BadJournal)
));
}
#[test]
fn flags_an_attribute_block_without_the_ext_attr_feature() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new()
.file(b"/f".to_vec(), b"data".to_vec(), Metadata::new(0o644, time))
.xattr(b"user.big".to_vec(), vec![0xAB; 2000]);
let mut bytes = format(src, 64 * MIB, opts_no_csum()).unwrap().into_bytes();
{
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(r.feature().has_ext_attr());
assert!(
r.scan().is_clean(),
"the image is coherent while the feature stands"
);
}
bytes[1024 + 0x5c] &= !0x08;
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(!r.feature().has_ext_attr());
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.category == Category::Xattr && a.detail.contains("attribute block"))
.unwrap_or_else(|| panic!("the orphaned attribute block is flagged: {report:?}"));
assert_eq!(found.severity, Severity::Structural);
assert!(found.location.inode.is_some() && found.location.block.is_some());
assert!(report.has_fatal(ReadPolicy::Strict));
}
#[test]
fn flags_a_large_regular_file_without_the_large_file_feature() {
let mut bytes = format(TreeBuilder::new(), 64 * MIB, opts_no_csum())
.unwrap()
.into_bytes();
{
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(r.feature().has_large_file());
assert!(r.scan().is_clean());
}
bytes[1024 + 0x64] &= !0x02;
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(!r.feature().has_large_file());
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.detail.contains("regular file"))
.unwrap_or_else(|| panic!("the large file is flagged: {report:?}"));
assert_eq!(found.severity, Severity::Conformance);
assert_eq!(found.category, Category::Inode);
assert_eq!(
found.location.inode,
Some(7),
"the resize inode is the file that reaches the bound"
);
assert_eq!(
report
.anomalies()
.iter()
.filter(|a| a.detail.contains("regular file"))
.count(),
1
);
assert!(report.has_fatal(ReadPolicy::Strict));
}
#[test]
fn flags_an_indexed_directory_without_the_dir_index_feature() {
let time = Timestamp::from_secs(1_700_000_000);
let mut src = TreeBuilder::new().directory(b"/d".to_vec(), Metadata::new(0o755, time));
for i in 0..600u32 {
let name = format!("/d/entry-{i:04}-padded-out-to-force-an-index").into_bytes();
src = src.file(name, Vec::new(), Metadata::new(0o644, time));
}
let mut bytes = format(src, 64 * MIB, opts_no_csum()).unwrap().into_bytes();
{
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(r.feature().has_dir_index());
let (_, dir) = r.lookup(b"/d").expect("the directory");
assert!(
dir.flags.contains(InodeFlags::INDEX),
"the directory is large enough to be indexed"
);
assert!(r.scan().is_clean());
}
bytes[1024 + 0x5c] &= !0x20;
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(!r.feature().has_dir_index());
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.detail.contains("hash-indexed"))
.unwrap_or_else(|| panic!("the unadvertised index is flagged: {report:?}"));
assert_eq!(found.severity, Severity::Conformance);
assert_eq!(found.category, Category::Directory);
assert!(found.location.inode.is_some());
assert!(report.has_fatal(ReadPolicy::Strict));
}
#[test]
fn flags_the_hash_index_flag_on_something_that_is_not_a_directory() {
let time = Timestamp::from_secs(1_700_000_000);
let src =
TreeBuilder::new().file(b"/f".to_vec(), b"data".to_vec(), Metadata::new(0o644, time));
let mut bytes = format(src, 64 * MIB, opts_no_csum()).unwrap().into_bytes();
let (number, _) = {
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(r.feature().has_dir_index());
assert!(r.scan().is_clean());
r.lookup(b"/f").expect("the file")
};
let at = inode_offset(&bytes, number) + 0x20;
bytes[at + 1] |= 0x10;
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let file = r.inode(number).unwrap();
assert!(file.flags.contains(InodeFlags::INDEX));
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.detail.contains("not a directory"))
.unwrap_or_else(|| panic!("the flag on a non-directory is flagged: {report:?}"));
assert_eq!(found.severity, Severity::Conformance);
assert_eq!(found.category, Category::Inode);
assert_eq!(found.location.inode, Some(number));
assert!(
!report
.anomalies()
.iter()
.any(|a| a.detail.contains("does not enable the dir_index feature")),
"a regular file was described as a hash-indexed directory: {report:?}"
);
bytes[1024 + 0x5c] &= !0x20;
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let report = r.scan();
assert!(
!report
.anomalies()
.iter()
.any(|a| a.detail.contains("does not enable the dir_index feature")),
"{report:?}"
);
assert!(
report
.anomalies()
.iter()
.any(|a| a.detail.contains("not a directory"))
);
}
#[test]
fn the_dirent_bound_is_the_shortest_record_the_format_encodes() {
assert_eq!(MIN_DIRENT_LEN, u64::from(crate::ondisk::min_rec_len(1)));
assert!(MIN_DIRENT_LEN <= u64::from(crate::ondisk::min_rec_len(255)));
}
#[test]
fn flags_metadata_outside_its_group_without_flex_bg() {
let image = format(TreeBuilder::new(), 256 * MIB, opts_no_csum()).unwrap();
let mut bytes = image.into_bytes();
{
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(r.feature().has_flex_bg());
assert!(
r.scan().is_clean(),
"a flex image places metadata legally: {:?}",
r.scan().anomalies()
);
}
bytes[1024 + 0x60 + 1] &= !0x02;
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(!r.feature().has_flex_bg());
let report = r.scan();
let outside: Vec<&Anomaly> = report
.anomalies()
.iter()
.filter(|a| a.detail.contains("outside the group"))
.collect();
assert!(
!outside.is_empty(),
"the packed metadata is now out of place: {report:?}"
);
assert!(
outside.iter().any(|a| {
a.location.group == Some(1)
&& a.category == Category::Bitmap
&& a.severity == Severity::Structural
}),
"group 1's bitmap is flagged as outside its group: {report:?}"
);
assert!(report.has_fatal(ReadPolicy::Strict));
}
#[test]
fn scan_collects_multiple_anomalies_and_renders_a_table() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new().file(
b"/hostname".to_vec(),
b"ferrosys\n".to_vec(),
Metadata::new(0o644, time),
);
let bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let root_off = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
r.group_descriptor(0).unwrap().inode_table as usize * 4096 + 256
};
let mut corrupt = bytes.clone();
corrupt[1024 + 0x30] ^= 0xff; corrupt[root_off] ^= 0xff;
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
let report = r.scan();
assert!(
report
.anomalies()
.iter()
.any(|a| a.category == Category::Superblock && a.severity == Severity::Integrity)
);
assert!(
report
.anomalies()
.iter()
.any(|a| a.category == Category::Inode
&& a.severity == Severity::Integrity
&& a.location.inode == Some(2))
);
assert!(report.anomalies().len() >= 2);
assert_eq!(report.worst_severity(), Some(Severity::Integrity));
assert!(report.has_fatal(ReadPolicy::Strict));
assert!(!report.has_fatal(ReadPolicy::Lenient));
let table = report.to_table();
let mut lines = table.lines();
let header = lines.next().unwrap();
assert!(header.starts_with("SEVERITY"));
assert!(
header.contains("CATEGORY") && header.contains("LOCATION") && header.contains("DETAIL")
);
assert_eq!(lines.count(), report.anomalies().len());
assert!(table.contains("integrity"));
assert!(table.contains("inode 2"));
}
#[test]
fn scan_files_an_out_of_range_extent_against_the_extent_tree() {
let time = Timestamp::from_secs(1_700_000_000);
let src =
TreeBuilder::new().file(b"/f".to_vec(), vec![0x42; 4096], Metadata::new(0o644, time));
let bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let (ino, inode_off) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (n, _) = r.lookup(b"/f").expect("lookup /f");
let isize = r.superblock().inode_size as usize;
let table = r.group_descriptor(0).unwrap().inode_table as usize;
(n, table * 4096 + (n as usize - 1) * isize)
};
let bogus = 0x00ff_ffffu32; let mut corrupt = bytes.clone();
corrupt[inode_off + 0x3c..inode_off + 0x40].copy_from_slice(&bogus.to_le_bytes());
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
let report = r.scan();
let extent = report
.anomalies()
.iter()
.find(|a| a.category == Category::ExtentTree)
.expect("an out-of-range extent is filed against the extent tree");
assert_eq!(extent.location.inode, Some(ino));
assert_eq!(extent.location.block, Some(u64::from(bogus)));
assert_eq!(extent.severity, Severity::Structural);
assert!(
!report
.anomalies()
.iter()
.any(|a| a.category == Category::Superblock),
"the out-of-range block was mis-filed against the superblock"
);
}
#[test]
fn scan_files_an_out_of_range_bitmap_block_against_the_bitmap() {
let bytes = format(TreeBuilder::new(), 64 * MIB, opts())
.unwrap()
.into_bytes();
let desc_off = 4096;
let bogus = 0x00ff_ffffu32; let mut corrupt = bytes.clone();
corrupt[desc_off..desc_off + 4].copy_from_slice(&bogus.to_le_bytes());
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
let report = r.scan();
let bitmap = report
.anomalies()
.iter()
.find(|a| a.category == Category::Bitmap && a.location.block == Some(u64::from(bogus)))
.expect("an out-of-range bitmap block is filed against the bitmap");
assert_eq!(bitmap.location.group, Some(0));
assert_eq!(bitmap.severity, Severity::Structural);
assert!(
!report
.anomalies()
.iter()
.any(|a| a.category == Category::Superblock),
"the out-of-range bitmap block was mis-filed against the superblock"
);
}
#[test]
fn scan_files_an_out_of_range_xattr_block_against_the_attribute_block() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new().file(b"/f".to_vec(), Vec::new(), Metadata::new(0o644, time));
let bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let (ino, inode_off) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (n, _) = r.lookup(b"/f").expect("lookup /f");
let isize = r.superblock().inode_size as usize;
let table = r.group_descriptor(0).unwrap().inode_table as usize;
(n, table * 4096 + (n as usize - 1) * isize)
};
let bogus = 0x00ff_ffffu32;
let mut corrupt = bytes.clone();
corrupt[inode_off + 0x68..inode_off + 0x6c].copy_from_slice(&bogus.to_le_bytes());
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
let report = r.scan();
let xattr = report
.anomalies()
.iter()
.find(|a| a.category == Category::Xattr && a.location.block == Some(u64::from(bogus)))
.expect("an out-of-range xattr block is filed against the attribute block");
assert_eq!(xattr.location.inode, Some(ino));
assert!(
!report
.anomalies()
.iter()
.any(|a| a.category == Category::Superblock),
"the out-of-range xattr block was mis-filed against the superblock"
);
}
#[test]
fn scan_collects_both_bitmap_faults_in_one_group() {
let bytes = format(TreeBuilder::new(), 64 * MIB, opts())
.unwrap()
.into_bytes();
let (block_bmp, inode_bmp) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let d = r.group_descriptor(0).unwrap();
(d.block_bitmap, d.inode_bitmap)
};
let mut corrupt = bytes.clone();
corrupt[block_bmp as usize * 4096] ^= 0xff;
corrupt[inode_bmp as usize * 4096] ^= 0xff;
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
let report = r.scan();
let bitmap_faults = report
.anomalies()
.iter()
.filter(|a| a.category == Category::Bitmap)
.count();
assert_eq!(
bitmap_faults,
2,
"both bitmaps of the group fault, so both are reported, got {:?}",
report.anomalies()
);
}
#[test]
fn scan_collects_multiple_faults_in_one_directory() {
let time = Timestamp::from_secs(1_700_000_000);
let mut src = TreeBuilder::new().directory(b"/d".to_vec(), Metadata::new(0o755, time));
for i in 0..300u32 {
src = src.file(
format!("/d/file-{i:04}").into_bytes(),
Vec::new(),
Metadata::new(0o644, time),
);
}
let bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let (first, nblocks) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (_, dir) = r.lookup(b"/d").unwrap();
let leaves = r.extent_leaves(&dir).unwrap();
(leaves[0].start, dir.size / 4096)
};
assert!(nblocks >= 3, "the directory must span several blocks");
let mut corrupt = bytes.clone();
corrupt[(first + 1) as usize * 4096 + 40] ^= 0xff;
corrupt[(first + 2) as usize * 4096 + 40] ^= 0xff;
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
let report = r.scan();
let dir_faults = report
.anomalies()
.iter()
.filter(|a| a.category == Category::Directory)
.count();
assert_eq!(
dir_faults,
2,
"both corrupt directory blocks are reported, got {:?}",
report.anomalies()
);
}
#[test]
fn extent_tail_offset_follows_the_declared_capacity() {
use crate::extent::node_capacity;
const BS: usize = 4096;
let node = |eh_max: usize| {
let mut n = vec![0u8; BS];
put_u16(&mut n, 4, eh_max as u16); n
};
assert_eq!(
extent_tail_offset(&node(node_capacity(BS)), BS),
tail_offset(BS)
);
assert_eq!(
extent_tail_offset(&node(node_capacity(BS) - 1), BS),
tail_offset(BS) - EXTENT_ENTRY_SIZE
);
assert_eq!(extent_tail_offset(&node(0xffff), BS), tail_offset(BS));
}
#[test]
fn anomaly_projects_to_json_with_escaping() {
let a = Anomaly {
severity: Severity::Structural,
category: Category::ExtentTree,
location: Location {
block: Some(99),
group: None,
inode: Some(12),
},
detail: "bad \"node\"\n\\path".to_string(),
};
let expected = String::from("{\"severity\":\"structural\",\"category\":\"extent tree\",")
+ "\"location\":{\"block\":99,\"inode\":12},"
+ "\"detail\":\"bad \\\"node\\\"\\n\\\\path\"}";
assert_eq!(a.to_json(), expected);
let empty = Anomaly {
severity: Severity::Cosmetic,
category: Category::Journal,
location: Location::default(),
detail: "x".to_string(),
};
assert_eq!(
empty.to_json(),
"{\"severity\":\"cosmetic\",\"category\":\"journal\",\"location\":{},\"detail\":\"x\"}"
);
}
#[test]
fn the_scan_document_is_a_versioned_golden_shape() {
let report = ScanReport {
anomalies: vec![
Anomaly {
severity: Severity::Integrity,
category: Category::Inode,
location: Location {
block: Some(40),
group: Some(3),
inode: Some(12),
},
detail: "checksum mismatch".to_string(),
},
Anomaly {
severity: Severity::Cosmetic,
category: Category::Journal,
location: Location::default(),
detail: "note".to_string(),
},
],
truncated: false,
cap: ScanReport::MAX_ANOMALIES,
};
assert_eq!(
report.to_json(),
"{\"schema\":1,\"clean\":false,\"count\":2,\"truncated\":false,\"anomalies\":[\
{\"severity\":\"integrity\",\"category\":\"inode\",\
\"location\":{\"block\":40,\"group\":3,\"inode\":12},\
\"detail\":\"checksum mismatch\"},\
{\"severity\":\"cosmetic\",\"category\":\"journal\",\"location\":{},\
\"detail\":\"note\"}]}"
);
assert_eq!(
report.to_table(),
"SEVERITY CATEGORY LOCATION DETAIL\n\
integrity inode group 3 inode 12 block 40 checksum mismatch\n\
cosmetic journal - note\n"
);
let clean = ScanReport {
anomalies: Vec::new(),
truncated: false,
cap: ScanReport::MAX_ANOMALIES,
};
assert_eq!(
clean.to_json(),
"{\"schema\":1,\"clean\":true,\"count\":0,\"truncated\":false,\"anomalies\":[]}"
);
assert_eq!(clean.to_table(), "no anomalies\n");
assert_eq!(SCAN_SCHEMA_VERSION, 1);
}
#[test]
fn report_projects_to_sarif() {
let clean = ScanReport::default();
assert_eq!(
clean.to_sarif(None),
"{\"$schema\":\"https://json.schemastore.org/sarif-2.1.0.json\",\
\"version\":\"2.1.0\",\"runs\":[{\"tool\":{\"driver\":{\"name\":\"ferrosys\",\
\"rules\":[]}},\"results\":[]}]}"
);
let report = ScanReport {
anomalies: vec![
Anomaly {
severity: Severity::Integrity,
category: Category::Inode,
location: Location {
block: Some(40),
group: Some(3),
inode: Some(12),
},
detail: "checksum \"bad\"".to_string(),
},
Anomaly {
severity: Severity::Cosmetic,
category: Category::Journal,
location: Location::default(),
detail: "note".to_string(),
},
],
truncated: false,
cap: ScanReport::MAX_ANOMALIES,
};
let expected = String::from(
"{\"$schema\":\"https://json.schemastore.org/sarif-2.1.0.json\",\
\"version\":\"2.1.0\",\"runs\":[{\"tool\":{\"driver\":{\"name\":\"ferrosys\",\"rules\":[",
) + "{\"id\":\"inode\",\"name\":\"inode\",\"shortDescription\":{\"text\":\"inode anomaly\"}},"
+ "{\"id\":\"journal\",\"name\":\"journal\",\"shortDescription\":{\"text\":\"journal anomaly\"}}"
+ "]}},\"results\":["
+ "{\"ruleId\":\"inode\",\"level\":\"error\",\"message\":{\"text\":\"checksum \\\"bad\\\"\"},"
+ "\"locations\":[{\"physicalLocation\":{\"artifactLocation\":{\"uri\":\"disk.img\"}},"
+ "\"logicalLocations\":[{\"fullyQualifiedName\":\"group 3 inode 12 block 40\"}]}],"
+ "\"properties\":{\"severity\":\"integrity\",\"category\":\"inode\",\"block\":40,\"group\":3,\"inode\":12}},"
+ "{\"ruleId\":\"journal\",\"level\":\"note\",\"message\":{\"text\":\"note\"},"
+ "\"locations\":[{\"physicalLocation\":{\"artifactLocation\":{\"uri\":\"disk.img\"}}}],"
+ "\"properties\":{\"severity\":\"cosmetic\",\"category\":\"journal\"}}"
+ "]}]}";
assert_eq!(report.to_sarif(Some("disk.img")), expected);
let bare = ScanReport {
anomalies: vec![Anomaly {
severity: Severity::Conformance,
category: Category::Superblock,
location: Location::default(),
detail: "x".to_string(),
}],
truncated: false,
cap: ScanReport::MAX_ANOMALIES,
};
assert!(bare.to_sarif(None).contains(
"\"ruleId\":\"superblock\",\"level\":\"warning\",\"message\":{\"text\":\"x\"},\
\"properties\":{\"severity\":\"conformance\",\"category\":\"superblock\"}"
));
}
#[test]
fn reader_never_panics_on_mangled_images() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.directory(b"/etc".to_vec(), m(0o755))
.file(b"/etc/hostname".to_vec(), b"ferrosys\n".to_vec(), m(0o644))
.file(b"/big".to_vec(), vec![0x42; 40_000], m(0o600));
let image = format(src, 64 * MIB, opts()).unwrap().into_bytes();
fn drive(bytes: &[u8]) {
if let Ok(mut r) = Reader::open(std::io::Cursor::new(bytes)) {
let _ = r.walk();
let _ = r.verify_checksums();
let _ = r.scan();
}
if let Ok(mut r) = Reader::open_with(
std::io::Cursor::new(bytes),
&OpenOptions::new().base(512).policy(ReadPolicy::Lenient),
) {
let _ = r.scan();
}
}
drive(&image);
for (off, fill) in [
(0x00usize, 0xffu8), (0x14, 0xff), (0x20, 0x00), (0x28, 0x00), ] {
let mut mangled = image.clone();
mangled[1024 + off..1024 + off + 4].fill(fill);
drive(&mangled);
}
for len in [0usize, 1, 512, 1023, 1024, 1025, 2048, 4096, 8192, 65_536] {
drive(&image[..len.min(image.len())]);
}
let mut flip = image.clone();
let span = flip.len().min(64 * 1024);
let mut i = 0usize;
while i < span {
let orig = flip[i];
flip[i] ^= 0xff;
drive(&flip);
flip[i] = orig;
i += 251; }
drive(&vec![0x00u8; 4096 * 8]);
drive(&vec![0xffu8; 4096 * 8]);
let ramp: Vec<u8> = (0..8192u32).map(|k| (k % 256) as u8).collect();
drive(&ramp);
}
#[test]
fn walk_bounds_a_directory_cycle() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.directory(b"/a".to_vec(), m(0o755))
.directory(b"/a/b".to_vec(), m(0o755));
let mut bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let (block_off, block_size) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let root = r.inode(2).unwrap();
let a_ino = r
.read_dir(&root)
.unwrap()
.into_iter()
.find(|e| e.name == b"a")
.unwrap()
.inode;
let a_inode = r.inode(a_ino).unwrap();
let bs = 1024usize << r.superblock().log_block_size;
let start = r.extent_leaves(&a_inode).unwrap()[0].start;
(start as usize * bs, bs)
};
let mut off = block_off;
let end = block_off + block_size;
loop {
let rec_len = u16::from_le_bytes([bytes[off + 4], bytes[off + 5]]) as usize;
assert!(
rec_len >= 8 && off + rec_len <= end,
"walked a valid dir block"
);
let name_len = bytes[off + 6] as usize;
if name_len == 1 && bytes[off + 8] == b'b' {
bytes[off..off + 4].copy_from_slice(&2u32.to_le_bytes());
break;
}
off += rec_len;
}
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let tree = r.walk().unwrap();
let paths: Vec<&[u8]> = tree.iter().map(|e| e.path.as_slice()).collect();
assert!(paths.contains(&b"/a".as_slice()));
assert!(paths.contains(&b"/a/b".as_slice()));
assert_eq!(
paths.iter().filter(|p| **p == b"/a").count(),
1,
"the cycle did not multiply entries"
);
}
#[test]
fn the_walk_names_the_inode_each_path_points_at() {
let time = Timestamp::from_secs(1_700_000_000);
let m = Metadata::new(0o644, time);
let src = TreeBuilder::new()
.file(b"/original".to_vec(), b"shared".to_vec(), m)
.hardlink(b"/link".to_vec(), b"/original".to_vec(), m)
.file(b"/twin".to_vec(), b"shared".to_vec(), m);
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let by_path: std::collections::BTreeMap<Vec<u8>, u32> = r
.walk()
.unwrap()
.into_iter()
.map(|e| (e.path, e.number))
.collect();
assert_eq!(
by_path[&b"/link".to_vec()],
by_path[&b"/original".to_vec()],
"a hard link is the same inode under a second name"
);
assert_ne!(
by_path[&b"/twin".to_vec()],
by_path[&b"/original".to_vec()],
"identical contents are not the same file"
);
let entry = r
.walk()
.unwrap()
.into_iter()
.find(|e| e.path == b"/original")
.expect("the file is in the tree");
assert_eq!(r.inode(entry.number).unwrap(), entry.inode);
assert_eq!(entry.inode.links_count, 2, "the link is counted");
}
#[test]
fn walk_descends_a_tree_nested_past_any_recursion_cap() {
let time = Timestamp::from_secs(1_700_000_000);
let depth = 200usize;
let mut src = TreeBuilder::new();
let mut path = Vec::new();
for i in 0..depth {
path.extend_from_slice(format!("/d{i:03}").as_bytes());
src = src.directory(path.clone(), Metadata::new(0o755, time));
}
let mut leaf = path.clone();
leaf.extend_from_slice(b"/leaf");
src = src.file(leaf.clone(), b"deep\n".to_vec(), Metadata::new(0o644, time));
let bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let paths: Vec<Vec<u8>> = r
.walk()
.expect("a deep tree walks in full")
.into_iter()
.map(|e| e.path)
.collect();
assert!(
paths.contains(&leaf),
"the entry {depth} levels down was not reached"
);
let in_chain = paths.iter().filter(|p| p.starts_with(b"/d000")).count();
assert_eq!(
in_chain,
depth + 1,
"every directory in the chain and the leaf appears exactly once"
);
for i in 0..depth {
let mut prefix = Vec::new();
for j in 0..=i {
prefix.extend_from_slice(format!("/d{j:03}").as_bytes());
}
assert!(
paths.contains(&prefix),
"level {i} is missing from the walk"
);
}
}
fn merged_usr() -> TreeBuilder {
let t = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, t);
TreeBuilder::new()
.directory(b"/usr".to_vec(), m(0o755))
.directory(b"/usr/lib".to_vec(), m(0o755))
.directory(b"/usr/lib/modules".to_vec(), m(0o755))
.file(
b"/usr/lib/modules/vmlinuz".to_vec(),
b"not really a kernel".to_vec(),
m(0o644),
)
.directory(b"/etc".to_vec(), m(0o755))
.file(
b"/etc/fstab".to_vec(),
b"/ ext4 defaults\n".to_vec(),
m(0o644),
)
.symlink(b"/lib".to_vec(), b"usr/lib".to_vec(), m(0o777))
.symlink(
b"/absolute".to_vec(),
b"/usr/lib/modules".to_vec(),
m(0o777),
)
.symlink(b"/loop_a".to_vec(), b"loop_b".to_vec(), m(0o777))
.symlink(b"/loop_b".to_vec(), b"loop_a".to_vec(), m(0o777))
.symlink(b"/dangling".to_vec(), b"nowhere".to_vec(), m(0o777))
}
#[test]
fn lookup_follows_a_symlink_into_merged_usr() {
let image = format(merged_usr(), 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let (through_link, _) = r.lookup(b"/lib/modules").expect("/lib/modules resolves");
let (direct, _) = r.lookup(b"/usr/lib/modules").expect("/usr/lib/modules");
assert_eq!(through_link, direct, "the link reaches the same inode");
let (_, inode) = r.lookup(b"/lib/modules/vmlinuz").unwrap();
assert_eq!(r.read_data(&inode).unwrap(), b"not really a kernel");
let (abs, _) = r.lookup(b"/absolute").expect("/absolute resolves");
assert_eq!(abs, direct);
assert_eq!(r.lookup(b"lib/modules").unwrap().0, direct);
assert_eq!(r.lookup(b"//lib/./modules/").unwrap().0, direct);
assert_eq!(r.lookup(b"/").unwrap().0, 2);
}
#[test]
fn lookup_no_follow_stops_at_the_link() {
let image = format(merged_usr(), 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let (_, link) = r.lookup_no_follow(b"/lib").expect("/lib as a link");
assert_eq!(link.mode & 0o170000, 0o120000, "it is a symlink");
assert_eq!(r.read_symlink(&link).unwrap(), b"usr/lib");
let (_, dir) = r.lookup(b"/lib").expect("/lib followed");
assert_eq!(dir.mode & 0o170000, 0o040000, "it is a directory");
assert_eq!(
r.lookup_no_follow(b"/lib/modules").unwrap().0,
r.lookup(b"/usr/lib/modules").unwrap().0
);
}
#[test]
fn lookup_bounds_a_symlink_cycle_and_names_what_is_missing() {
let image = format(merged_usr(), 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
assert!(matches!(
r.lookup(b"/loop_a"),
Err(ReadError::SymlinkLoop { .. })
));
assert!(matches!(
r.lookup(b"/dangling"),
Err(ReadError::NotFound { .. })
));
assert!(matches!(
r.lookup(b"/nope"),
Err(ReadError::NotFound { .. })
));
assert!(matches!(
r.lookup(b"/etc/fstab/deeper"),
Err(ReadError::NotADirectory { .. })
));
assert!(r.lookup_no_follow(b"/loop_a").is_ok());
}
#[test]
fn a_reserved_inode_without_an_extra_area_verifies_on_its_low_half_alone() {
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut bytes = image.into_bytes();
let (table, inode_size, csum) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let table = r.group_descriptor(0).unwrap().inode_table as usize;
let csum = r.checksummer();
(table, r.superblock().inode_size as usize, csum)
};
let seed = csum.base_seed();
let off = table * 4096;
bytes[off + 0x80..off + inode_size].fill(0);
put_u16(&mut bytes[off..], Inode::CHECKSUM_LO_OFFSET, 0);
let mut c = csum.crc32c(seed, &1u32.to_le_bytes());
c = csum.crc32c(c, &0u32.to_le_bytes()); c = csum.crc32c(c, &bytes[off..off + inode_size]);
put_u16(&mut bytes[off..], Inode::CHECKSUM_LO_OFFSET, c as u16);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert_eq!(
r.inode(1).unwrap().extra_isize,
0,
"the inode declares no extra area"
);
let report = r.scan();
assert!(
report.is_clean(),
"an inode storing only its low checksum half was rejected: {:?}",
report.anomalies()
);
r.verify_checksums()
.expect("and the strict verifier accepts it too");
}
#[test]
fn a_field_this_crate_does_not_model_does_not_break_the_inode_checksum() {
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut bytes = image.into_bytes();
let (table, inode_size, csum) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let table = r.group_descriptor(0).unwrap().inode_table as usize;
let csum = r.checksummer();
(table, r.superblock().inode_size as usize, csum)
};
let seed = csum.base_seed();
let off = table * 4096 + inode_size;
crate::ondisk::put_u32(&mut bytes[off..], 0x24, 0xdead_beef); put_u16(&mut bytes[off..], Inode::CHECKSUM_LO_OFFSET, 0);
put_u16(&mut bytes[off..], Inode::CHECKSUM_HI_OFFSET, 0);
let mut c = csum.crc32c(seed, &2u32.to_le_bytes());
c = csum.crc32c(c, &0u32.to_le_bytes());
c = csum.crc32c(c, &bytes[off..off + inode_size]);
put_u16(&mut bytes[off..], Inode::CHECKSUM_LO_OFFSET, c as u16);
put_u16(
&mut bytes[off..],
Inode::CHECKSUM_HI_OFFSET,
(c >> 16) as u16,
);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let report = r.scan();
assert!(
report.is_clean(),
"an inode carrying a field this crate does not model was rejected: {:?}",
report.anomalies()
);
}
}