use std::collections::{BTreeMap, BTreeSet};
use std::net::IpAddr;
use crate::diff::change::{Change, Presence};
use crate::diff::port::{self, Clocks, PortDelta, PresenceFor};
use crate::diff::scope::ScopeIndex;
use crate::model::finding::{ClaimId, Finding, Severity};
use crate::model::host::os::OsFingerprint;
use crate::model::host::{
Filtering, Host, HostName, HostStatus, IpProtocolState, NameSource, NetworkRole,
};
use crate::model::mac::MacAddr;
#[derive(Debug, Clone)]
pub struct HostDelta {
address: IpAddr,
presence: Presence,
baseline: Option<Host>,
current: Option<Host>,
baseline_records: usize,
current_records: usize,
changes: Vec<HostChange>,
ports: Vec<PortDelta>,
}
impl HostDelta {
pub fn address(&self) -> IpAddr {
self.address
}
pub fn presence(&self) -> Presence {
self.presence
}
pub fn baseline(&self) -> Option<&Host> {
self.baseline.as_ref()
}
pub fn current(&self) -> Option<&Host> {
self.current.as_ref()
}
pub fn records(&self) -> (usize, usize) {
(self.baseline_records, self.current_records)
}
pub fn is_regrouped(&self) -> bool {
self.baseline_records > 1 || self.current_records > 1
}
pub fn changes(&self) -> &[HostChange] {
&self.changes
}
pub fn ports(&self) -> &[PortDelta] {
&self.ports
}
pub fn is_empty(&self) -> bool {
self.presence.is_in_both() && self.changes.is_empty() && self.ports.is_empty()
}
}
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq)]
pub enum HostChange {
Status(Change<HostStatus>),
Hostname(Change<Option<String>>),
Names {
gained: Vec<HostName>,
lost: Vec<HostName>,
},
Addresses {
gained: Vec<IpAddr>,
lost: Vec<IpAddr>,
},
Os(Box<Change<Option<OsFingerprint>>>),
Macs {
gained: Vec<MacAddr>,
lost: Vec<MacAddr>,
},
Vendor(Change<Option<String>>),
Roles {
gained: Vec<NetworkRole>,
lost: Vec<NetworkRole>,
},
Filtering {
gained: Vec<Filtering>,
lost: Vec<Filtering>,
},
IpProtocols {
changed: Vec<IpProtocolChange>,
},
Findings {
appeared: Vec<Finding>,
resolved: Vec<Finding>,
reassessed: Vec<Reassessment>,
},
}
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct IpProtocolChange {
pub protocol: u8,
pub state: Change<IpProtocolState>,
}
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Reassessment {
pub finding: Finding,
pub severity: Change<Severity>,
}
impl Reassessment {
pub fn new(finding: Finding, severity: Change<Severity>) -> Self {
Self { finding, severity }
}
}
#[allow(clippy::too_many_arguments)]
pub(crate) fn compare(
baseline: Option<&Host>,
current: Option<&Host>,
baseline_records: usize,
current_records: usize,
baseline_scope: &ScopeIndex,
current_scope: &ScopeIndex,
address: &IpAddr,
clocks: &Clocks,
) -> HostDelta {
let address = *address;
let known = current
.or(baseline)
.expect("a delta has a record on one side");
let baseline_coverage = baseline_scope.of_host(known);
let current_coverage = current_scope.of_host(baseline.or(current).expect("likewise"));
let presence = match (baseline, current) {
(Some(_), Some(_)) => Presence::Both,
(None, Some(_)) => Presence::Added {
before: baseline_coverage,
},
(Some(_), None) => Presence::Removed {
after: current_coverage,
},
(None, None) => unreachable!("a host delta has a record on at least one side"),
};
let changes = match (baseline, current) {
(Some(before), Some(after)) => changes_between(before, after),
_ => Vec::new(),
};
let ports = port::compare(
&baseline.map(collect_ports).unwrap_or_default(),
¤t.map(collect_ports).unwrap_or_default(),
PresenceFor {
baseline: &|number, protocol| {
baseline_scope.endpoint(baseline_coverage, number, protocol)
},
current: &|number, protocol| current_scope.endpoint(current_coverage, number, protocol),
},
clocks,
);
HostDelta {
address,
presence,
baseline: baseline.cloned(),
current: current.cloned(),
baseline_records,
current_records,
changes,
ports,
}
}
fn collect_ports(host: &Host) -> Vec<&crate::model::port::Port> {
host.ports().collect()
}
fn changes_between(before: &Host, after: &Host) -> Vec<HostChange> {
let mut changes = Vec::new();
if let Some(status) = Change::between(before.status(), after.status()) {
changes.push(HostChange::Status(status));
}
if let Some(hostname) = Change::between(
before.hostname().map(str::to_owned),
after.hostname().map(str::to_owned),
) {
changes.push(HostChange::Hostname(hostname));
}
let heard: BTreeSet<NameSource> = after.names().map(HostName::source).collect();
let (gained, lost) = difference(
before
.names()
.filter(|name| heard.contains(&name.source()))
.cloned(),
after.names().cloned(),
);
if !gained.is_empty() || !lost.is_empty() {
changes.push(HostChange::Names { gained, lost });
}
let (gained, lost) = difference(before.ips().iter().copied(), after.ips().iter().copied());
if !gained.is_empty() || !lost.is_empty() {
changes.push(HostChange::Addresses { gained, lost });
}
if let Some(now) = after.os()
&& !same_system(before.os(), Some(now))
{
changes.push(HostChange::Os(Box::new(Change::new(
before.os().cloned(),
Some(now.clone()),
))));
}
let seen_on_link = |host: &Host| {
host.hardware()
.is_some_and(|hardware| !hardware.macs().is_empty())
};
if seen_on_link(before) && seen_on_link(after) {
let (gained, lost) = difference(
before
.hardware()
.into_iter()
.flat_map(|hardware| hardware.macs().keys().copied()),
after
.hardware()
.into_iter()
.flat_map(|hardware| hardware.macs().keys().copied()),
);
if !gained.is_empty() || !lost.is_empty() {
changes.push(HostChange::Macs { gained, lost });
}
}
if let Some(now) = after.vendor()
&& before.vendor() != Some(now)
{
changes.push(HostChange::Vendor(Change::new(
before.vendor().map(str::to_owned),
Some(now.to_owned()),
)));
}
let (gained, lost) = difference(
before.network_roles().iter().copied(),
after.network_roles().iter().copied(),
);
if !gained.is_empty() || !lost.is_empty() {
changes.push(HostChange::Roles { gained, lost });
}
let (gained, lost) = difference(
before.filtering().iter().copied(),
after.filtering().iter().copied(),
);
if !gained.is_empty() || !lost.is_empty() {
changes.push(HostChange::Filtering { gained, lost });
}
let changed = ip_protocols_between(before, after);
if !changed.is_empty() {
changes.push(HostChange::IpProtocols { changed });
}
let (appeared, resolved, reassessed) = findings_between(before.findings(), after.findings());
if !appeared.is_empty() || !resolved.is_empty() || !reassessed.is_empty() {
changes.push(HostChange::Findings {
appeared,
resolved,
reassessed,
});
}
changes
}
fn ip_protocols_between(before: &Host, after: &Host) -> Vec<IpProtocolChange> {
let established = |host: &Host, number: &u8| {
host.ip_protocols()
.get(number)
.copied()
.filter(IpProtocolState::is_established)
};
before
.ip_protocols()
.keys()
.filter_map(|number| {
let was = established(before, number)?;
let is = established(after, number)?;
Change::between(was, is).map(|state| IpProtocolChange {
protocol: *number,
state,
})
})
.collect()
}
pub(super) fn findings_between<'a>(
before: impl Iterator<Item = &'a Finding>,
after: impl Iterator<Item = &'a Finding>,
) -> (Vec<Finding>, Vec<Finding>, Vec<Reassessment>) {
let before: BTreeMap<ClaimId, &Finding> = before.map(|f| (f.claim_id(), f)).collect();
let after: BTreeMap<ClaimId, &Finding> = after.map(|f| (f.claim_id(), f)).collect();
let appeared = after
.iter()
.filter(|(claim, _)| !before.contains_key(*claim))
.map(|(_, finding)| (*finding).clone())
.collect();
let resolved = before
.iter()
.filter(|(claim, _)| !after.contains_key(*claim))
.map(|(_, finding)| (*finding).clone())
.collect();
let reassessed = after
.iter()
.filter_map(|(claim, finding)| {
let was = before.get(claim)?;
Change::between(was.severity(), finding.severity()).map(|severity| Reassessment {
finding: (*finding).clone(),
severity,
})
})
.collect();
(appeared, resolved, reassessed)
}
fn same_system(before: Option<&OsFingerprint>, after: Option<&OsFingerprint>) -> bool {
match (before, after) {
(None, None) => true,
(Some(before), Some(after)) => {
before.name() == after.name()
&& before.family() == after.family()
&& before.device() == after.device()
&& before.generation() == after.generation()
&& before.vendor() == after.vendor()
&& before.kernel() == after.kernel()
&& before.arch() == after.arch()
&& before.cpes() == after.cpes()
}
_ => false,
}
}
fn difference<T: Ord + Clone>(
before: impl Iterator<Item = T>,
after: impl Iterator<Item = T>,
) -> (Vec<T>, Vec<T>) {
let before: BTreeSet<T> = before.collect();
let after: BTreeSet<T> = after.collect();
let gained = after.difference(&before).cloned().collect();
let lost = before.difference(&after).cloned().collect();
(gained, lost)
}
#[cfg(test)]
mod tests {
use std::net::Ipv4Addr;
use super::*;
use crate::model::confidence::Confidence;
use crate::model::finding::{DetectionClass, DetectionId, Reference, Severity, Version};
fn host(last: u8) -> Host {
let mut host = Host::new(IpAddr::V4(Ipv4Addr::new(203, 0, 113, last)));
host.set_status(HostStatus::Up);
host
}
fn finding(id: &str, title: &str, severity: Severity) -> Finding {
Finding::new(
DetectionId::new(id, Version::new(1, 0, 0), "hash").expect("a valid detection id"),
title,
severity,
Confidence::Certain,
DetectionClass::Passive,
)
.expect("a titled finding")
}
fn findings_change(
changes: &[HostChange],
) -> Option<(&[Finding], &[Finding], &[Reassessment])> {
changes.iter().find_map(|change| match change {
HostChange::Findings {
appeared,
resolved,
reassessed,
} => Some((
appeared.as_slice(),
resolved.as_slice(),
reassessed.as_slice(),
)),
_ => None,
})
}
#[test]
fn a_filter_that_appeared_in_front_of_a_host_is_reported() {
use crate::model::host::Filtering;
let before = host(1);
let mut after = host(1);
after.add_filtering(Filtering::StatefulFilter);
let changes = changes_between(&before, &after);
let filtering = changes
.iter()
.find_map(|change| match change {
HostChange::Filtering { gained, lost } => Some((gained, lost)),
_ => None,
})
.expect("a filtering change");
assert_eq!(filtering.0, &[Filtering::StatefulFilter]);
assert!(filtering.1.is_empty());
assert!(
changes_between(&host(1), &host(1))
.iter()
.all(|change| !matches!(change, HostChange::Filtering { .. }))
);
}
#[test]
fn a_name_is_compared_only_in_a_protocol_the_current_scan_heard() {
use crate::model::host::NameKind;
let name = |kind, source, name| HostName::new(kind, source, name).expect("a name");
let old_host = name(NameKind::Host, NameSource::Ntlm, "dc01.corp.example");
let new_host = name(NameKind::Host, NameSource::Ntlm, "dc02.corp.example");
let directory = name(NameKind::Domain, NameSource::Ldap, "corp.example");
let mut before = host(1);
before.record_name(old_host.clone());
before.record_name(directory);
let mut after = host(1);
after.record_name(new_host.clone());
let changes = changes_between(&before, &after);
let names = changes
.iter()
.find_map(|change| match change {
HostChange::Names { gained, lost } => Some((gained, lost)),
_ => None,
})
.expect("the renamed machine is a change");
assert_eq!(names.0, &[new_host]);
assert_eq!(
names.1,
&[old_host],
"the directory's domain is not lost: nothing asked it"
);
assert!(
changes_between(&before, &host(1))
.iter()
.all(|change| !matches!(change, HostChange::Names { .. })),
"a scan that heard no names says nothing about them"
);
}
#[test]
fn a_system_the_current_scan_did_not_identify_is_not_a_change() {
let mut before = host(1);
before.set_os(OsFingerprint::new("Linux", 90).with_family("Linux"));
let unidentified = host(1);
assert!(
changes_between(&before, &unidentified)
.iter()
.all(|change| !matches!(change, HostChange::Os(_))),
"{:?}",
changes_between(&before, &unidentified)
);
let mut other = host(1);
other.set_os(OsFingerprint::new("Windows", 90).with_family("Windows"));
assert!(
changes_between(&before, &other)
.iter()
.any(|change| matches!(change, HostChange::Os(_)))
);
assert!(
changes_between(&unidentified, &before)
.iter()
.any(|change| matches!(change, HostChange::Os(_))),
"a system identified where none was is still reported"
);
}
#[test]
fn a_scan_that_did_not_reach_the_segment_loses_no_hardware() {
let mac = MacAddr::new(0x02, 0, 0, 0, 0, 1);
use crate::model::host::hardware::{HardwareDescription, HardwareInfo};
let mut hardware = HardwareInfo::new(mac);
hardware.merge(
HardwareInfo::described(HardwareDescription {
vendor: Some("Example Devices"),
..HardwareDescription::default()
})
.expect("a vendor is a description"),
);
let mut before = host(1);
before.set_hardware(hardware);
assert_eq!(before.vendor(), Some("Example Devices"), "the fixture");
let changes = changes_between(&before, &host(1));
assert!(
changes
.iter()
.all(|change| !matches!(change, HostChange::Macs { .. } | HostChange::Vendor(_))),
"{changes:?}"
);
let mut replaced = host(1);
replaced.record_mac(MacAddr::new(0x02, 0, 0, 0, 0, 2));
let changes = changes_between(&before, &replaced);
assert!(
changes
.iter()
.any(|change| matches!(change, HostChange::Macs { .. })),
"another address seen on the segment is still a change: {changes:?}"
);
}
#[test]
fn a_host_that_did_not_move_reports_nothing() {
let before = host(1);
let after = host(1);
assert!(changes_between(&before, &after).is_empty());
}
#[test]
fn a_finding_that_appeared_is_reported() {
let before = host(1);
let mut after = host(1);
after.add_finding(finding("cve", "Log4Shell", Severity::Critical));
let changes = changes_between(&before, &after);
let (appeared, resolved, _) = findings_change(&changes).expect("a findings change");
assert_eq!(appeared.len(), 1);
assert_eq!(appeared[0].title(), "Log4Shell");
assert!(resolved.is_empty());
}
#[test]
fn a_finding_that_went_away_is_reported_as_resolved() {
let mut before = host(1);
before.add_finding(finding("cve", "Log4Shell", Severity::Critical));
let after = host(1);
let changes = changes_between(&before, &after);
let (appeared, resolved, _) = findings_change(&changes).expect("a findings change");
assert!(appeared.is_empty());
assert_eq!(resolved.len(), 1);
assert_eq!(resolved[0].title(), "Log4Shell");
}
#[test]
fn the_same_finding_on_both_sides_is_not_a_change() {
let mut before = host(1);
before.add_finding(finding("cve", "Log4Shell", Severity::Critical));
let mut after = host(1);
after.add_finding(finding("cve", "Log4Shell", Severity::Critical));
assert!(findings_change(&changes_between(&before, &after)).is_none());
}
#[test]
fn a_detection_version_bump_is_not_a_finding_appearing() {
let mut before = host(1);
before.add_finding(
Finding::new(
DetectionId::new("cve", Version::new(1, 0, 0), "hash").unwrap(),
"Log4Shell",
Severity::Critical,
Confidence::Certain,
DetectionClass::Passive,
)
.unwrap()
.with_reference(Reference::cve("CVE-2021-44228").unwrap()),
);
let mut after = host(1);
after.add_finding(
Finding::new(
DetectionId::new("cve", Version::new(2, 0, 0), "other").unwrap(),
"Log4Shell, restated",
Severity::Critical,
Confidence::Certain,
DetectionClass::Passive,
)
.unwrap()
.with_reference(Reference::cve("CVE-2021-44228").unwrap()),
);
assert!(
findings_change(&changes_between(&before, &after)).is_none(),
"the same CVE under one detection is one claim across versions"
);
}
#[test]
fn a_severity_that_moved_under_one_claim_is_reported_as_a_reassessment() {
let mut before = host(1);
before.add_finding(finding("audit", "Deprecated TLS", Severity::Medium));
let mut after = host(1);
after.add_finding(finding("audit", "Deprecated TLS", Severity::Critical));
let changes = changes_between(&before, &after);
let (appeared, resolved, reassessed) =
findings_change(&changes).expect("a findings change");
assert!(
appeared.is_empty() && resolved.is_empty(),
"the claim is on both sides, so it neither appeared nor resolved"
);
assert_eq!(reassessed.len(), 1);
assert_eq!(reassessed[0].severity.before, Severity::Medium);
assert_eq!(reassessed[0].severity.after, Severity::Critical);
assert_eq!(reassessed[0].finding.title(), "Deprecated TLS");
}
#[test]
fn an_excerpt_that_changed_under_one_claim_is_not_a_reassessment() {
use crate::model::finding::Excerpt;
let mut before = host(1);
before.add_finding(
finding("audit", "Deprecated TLS", Severity::Medium).with_excerpt(Excerpt::new("one")),
);
let mut after = host(1);
after.add_finding(
finding("audit", "Deprecated TLS", Severity::Medium).with_excerpt(Excerpt::new("two")),
);
assert!(findings_change(&changes_between(&before, &after)).is_none());
}
#[test]
fn two_findings_from_one_detection_are_told_apart_by_subject() {
let before = host(1);
let mut after = host(1);
after.add_finding(finding("audit", "Weak cipher", Severity::Medium));
after.add_finding(finding("audit", "Expired certificate", Severity::High));
let changes = changes_between(&before, &after);
let (appeared, _, _) = findings_change(&changes).expect("a findings change");
assert_eq!(appeared.len(), 2);
}
}