use super::{now_secs, Confidence, Evidence, Finding, ScanStatus, Severity, Subject};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case", tag = "state")]
pub enum FileState {
Hashed { sha256: String, size_bytes: u64 },
Missing,
Unreadable { reason: String },
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct Baseline {
pub recorded_at: u64,
pub files: BTreeMap<String, FileState>,
}
impl Baseline {
pub fn is_empty(&self) -> bool {
self.files.is_empty()
}
pub fn len(&self) -> usize {
self.files.len()
}
}
pub fn state_of(path: &Path) -> FileState {
let meta = match std::fs::metadata(path) {
Ok(m) => m,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return FileState::Missing,
Err(e) => {
return FileState::Unreadable {
reason: e.to_string(),
}
}
};
if meta.is_dir() {
return FileState::Unreadable {
reason: "path is a directory, not a file".into(),
};
}
let mut file = match std::fs::File::open(path) {
Ok(f) => f,
Err(e) => {
return FileState::Unreadable {
reason: e.to_string(),
}
}
};
use std::io::Read;
let mut hasher = Sha256::new();
let mut buf = vec![0u8; 64 * 1024];
loop {
match file.read(&mut buf) {
Ok(0) => break,
Ok(n) => hasher.update(&buf[..n]),
Err(e) => {
return FileState::Unreadable {
reason: e.to_string(),
}
}
}
}
FileState::Hashed {
sha256: hex::encode(hasher.finalize()),
size_bytes: meta.len(),
}
}
pub fn record(paths: &[PathBuf]) -> Baseline {
let mut files = BTreeMap::new();
for p in paths {
files.insert(p.to_string_lossy().to_string(), state_of(p));
}
Baseline {
recorded_at: now_secs(),
files,
}
}
pub fn scan(paths: &[PathBuf], baseline: &Baseline) -> ScanStatus {
if paths.is_empty() {
return ScanStatus::NoBaseline {
recorded: 0,
reason: concat!(
"no files are being watched, so there is nothing to baseline ",
"and nothing was recorded — pass --watch PATH to watch one. ",
"The listening sockets are checked regardless.",
)
.into(),
};
}
if baseline.is_empty() {
let fresh = record(paths);
return ScanStatus::NoBaseline {
recorded: fresh.len(),
reason: "no baseline existed, so nothing could be compared; one has \
now been recorded. A baseline taken after an intrusion \
records the intrusion — this run is not evidence that the \
machine is clean."
.into(),
};
}
let mut findings = Vec::new();
let mut checked = 0usize;
for path in paths {
let key = path.to_string_lossy().to_string();
let current = state_of(path);
checked += 1;
let Some(previous) = baseline.files.get(&key) else {
if let Some(f) = new_path_finding(&key, ¤t) {
findings.push(f);
}
continue;
};
if let Some(f) = compare(&key, previous, ¤t) {
findings.push(f);
}
}
if findings.is_empty() {
ScanStatus::Clean { checked }
} else {
ScanStatus::Findings { checked, findings }
}
}
fn subject(path: &str) -> Subject {
Subject::File {
path: path.to_string(),
}
}
fn new_path_finding(path: &str, current: &FileState) -> Option<Finding> {
match current {
FileState::Hashed { sha256, size_bytes } => Finding::new(
"file.unbaselined",
"watched file has no baseline entry",
Severity::Low,
Confidence::Certain,
subject(path),
vec![
Evidence::observed("file.sha256", sha256),
Evidence::observed("file.size_bytes", size_bytes.to_string()),
],
),
FileState::Missing => None,
FileState::Unreadable { reason } => Finding::new(
"file.unreadable",
"watched file could not be read",
Severity::Low,
Confidence::Certain,
subject(path),
vec![Evidence::observed("file.error", reason)],
),
}
}
fn compare(path: &str, previous: &FileState, current: &FileState) -> Option<Finding> {
match (previous, current) {
(
FileState::Hashed {
sha256: old,
size_bytes: old_size,
},
FileState::Hashed {
sha256: new,
size_bytes: new_size,
},
) => {
if old == new {
return None;
}
Finding::new(
"file.modified",
"watched file contents changed",
Severity::High,
Confidence::Certain,
subject(path),
vec![
Evidence::differs("file.sha256", new, old),
Evidence::differs(
"file.size_bytes",
new_size.to_string(),
old_size.to_string(),
),
],
)
}
(FileState::Hashed { sha256, .. }, FileState::Missing) => Finding::new(
"file.deleted",
"watched file no longer exists",
Severity::High,
Confidence::Certain,
subject(path),
vec![
Evidence::differs("file.exists", "false", "true"),
Evidence::observed("file.sha256_was", sha256),
],
),
(FileState::Missing, FileState::Hashed { sha256, size_bytes }) => Finding::new(
"file.created",
"watched path now exists where it did not",
Severity::Medium,
Confidence::Certain,
subject(path),
vec![
Evidence::differs("file.exists", "true", "false"),
Evidence::observed("file.sha256", sha256),
Evidence::observed("file.size_bytes", size_bytes.to_string()),
],
),
(FileState::Hashed { .. }, FileState::Unreadable { reason }) => Finding::new(
"file.became_unreadable",
"watched file was readable before and is not now",
Severity::Medium,
Confidence::Certain,
subject(path),
vec![
Evidence::differs("file.readable", "false", "true"),
Evidence::observed("file.error", reason),
],
),
(FileState::Unreadable { .. }, _) => None,
(FileState::Missing, FileState::Missing) => None,
(FileState::Missing, FileState::Unreadable { .. }) => None,
}
}
#[cfg(test)]
mod tests {
use super::*;
fn tmpdir(tag: &str) -> PathBuf {
let mut d = std::env::temp_dir();
d.push(format!("ironmon-ids-test-{tag}-{}", std::process::id()));
let _ = std::fs::create_dir_all(&d);
d
}
#[test]
fn watching_nothing_does_not_claim_a_baseline_was_recorded() {
let empty = Baseline {
recorded_at: 0,
files: BTreeMap::new(),
};
let status = scan(&[], &empty);
let ScanStatus::NoBaseline { recorded, reason } = status else {
panic!("watching nothing cannot be compared, so it is not Clean");
};
assert_eq!(recorded, 0, "nothing was watched, so nothing was recorded");
assert!(
!reason.contains("has now been recorded"),
"claims a recording that did not happen: {reason:?}"
);
assert!(
reason.contains("--watch"),
"should say how to watch something: {reason:?}"
);
}
#[test]
fn a_first_run_over_watched_files_still_warns_about_the_baseline() {
let dir = tmpdir("first-run");
let file = dir.join("watched");
std::fs::write(&file, b"contents").expect("write");
let empty = Baseline {
recorded_at: 0,
files: BTreeMap::new(),
};
let ScanStatus::NoBaseline { recorded, reason } = scan(&[file], &empty) else {
panic!("a first run cannot compare");
};
assert_eq!(recorded, 1);
assert!(
reason.contains("not evidence that the machine is clean"),
"the caveat that matters must survive: {reason:?}"
);
let _ = std::fs::remove_dir_all(&dir);
}
fn write(dir: &Path, name: &str, body: &str) -> PathBuf {
let p = dir.join(name);
std::fs::write(&p, body).unwrap();
p
}
#[test]
fn hashing_a_known_string_matches_the_published_vector() {
let dir = tmpdir("vector");
let p = write(&dir, "abc.txt", "abc");
match state_of(&p) {
FileState::Hashed { sha256, size_bytes } => {
assert_eq!(
sha256,
"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
);
assert_eq!(size_bytes, 3);
}
other => panic!("expected a hash, got {other:?}"),
}
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn a_missing_file_is_missing_and_not_unreadable() {
let dir = tmpdir("missing");
let p = dir.join("not-here.txt");
assert_eq!(state_of(&p), FileState::Missing);
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn the_first_scan_reports_no_baseline_rather_than_clean() {
let dir = tmpdir("firstrun");
let p = write(&dir, "a.txt", "hello");
let status = scan(&[p], &Baseline::default());
match &status {
ScanStatus::NoBaseline { recorded, reason } => {
assert_eq!(*recorded, 1);
assert!(reason.contains("not evidence"), "{reason}");
}
other => panic!("a first run must not report a verdict: {other:?}"),
}
assert!(
!status.is_conclusive(),
"reporting a first scan as clean is the most dangerous thing this \
module could do, because it is what a user wants to read"
);
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn an_unchanged_file_is_clean_and_a_changed_one_is_found() {
let dir = tmpdir("change");
let p = write(&dir, "b.txt", "original");
let base = record(std::slice::from_ref(&p));
assert_eq!(
scan(std::slice::from_ref(&p), &base),
ScanStatus::Clean { checked: 1 }
);
std::fs::write(&p, "tampered").unwrap();
let status = scan(std::slice::from_ref(&p), &base);
let findings = status.findings();
assert_eq!(findings.len(), 1, "{status:?}");
assert_eq!(findings[0].rule, "file.modified");
assert_eq!(findings[0].confidence, Confidence::Certain);
let hash_ev = findings[0]
.evidence
.iter()
.find(|e| e.kind == "file.sha256")
.expect("hash evidence");
assert!(hash_ev.expected.is_some());
assert_ne!(hash_ev.observed, *hash_ev.expected.as_ref().unwrap());
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn a_same_length_edit_is_still_detected() {
let dir = tmpdir("samelen");
let p = write(&dir, "c.txt", "AAAA");
let base = record(std::slice::from_ref(&p));
std::fs::write(&p, "BBBB").unwrap();
let status = scan(std::slice::from_ref(&p), &base);
assert_eq!(
status.findings().len(),
1,
"a content hash is the whole reason this does not use size or mtime"
);
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn deletion_and_creation_are_different_findings() {
let dir = tmpdir("delcreate");
let p = write(&dir, "d.txt", "here");
let base = record(std::slice::from_ref(&p));
std::fs::remove_file(&p).unwrap();
let deleted = scan(std::slice::from_ref(&p), &base);
assert_eq!(deleted.findings()[0].rule, "file.deleted");
let absent_base = record(std::slice::from_ref(&p)); std::fs::write(&p, "back").unwrap();
let created = scan(std::slice::from_ref(&p), &absent_base);
assert_eq!(created.findings()[0].rule, "file.created");
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn a_watched_path_with_no_baseline_entry_is_reported() {
let dir = tmpdir("unbaselined");
let known = write(&dir, "known.txt", "x");
let base = record(std::slice::from_ref(&known));
let fresh = write(&dir, "fresh.txt", "y");
let status = scan(&[known, fresh], &base);
let rules: Vec<&str> = status.findings().iter().map(|f| f.rule.as_str()).collect();
assert!(rules.contains(&"file.unbaselined"), "{rules:?}");
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn a_directory_is_unreadable_rather_than_silently_skipped() {
let dir = tmpdir("isdir");
match state_of(&dir) {
FileState::Unreadable { reason } => assert!(reason.contains("directory"), "{reason}"),
other => panic!("expected Unreadable, got {other:?}"),
}
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn a_baseline_round_trips_through_json() {
let dir = tmpdir("roundtrip");
let p = write(&dir, "e.txt", "data");
let base = record(std::slice::from_ref(&p));
let json = serde_json::to_string(&base).unwrap();
let back: Baseline = serde_json::from_str(&json).unwrap();
assert_eq!(back, base);
let _ = std::fs::remove_dir_all(&dir);
}
}