use crate::model::host::OsFingerprint;
use crate::model::host::{OsEvidence, OsSource};
use super::db::RuleDb;
use super::observation::{StackObservation, StackReply};
use super::series::SeriesClasses;
use super::signature::{OsDefinition, Provenance};
pub const MAX_STACK_ACCURACY: u8 = 70;
pub const MIN_REPORTABLE_ACCURACY: u8 = 40;
const MEASURED_ACCURACY: f32 = 65.0;
const PUBLISHED_ACCURACY: f32 = 50.0;
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq)]
pub struct OsVerdict {
pub family: Option<String>,
pub device: Option<String>,
pub vendor: Option<String>,
pub product: Option<String>,
pub version: Option<String>,
pub cpe: Option<String>,
pub kernel: Option<String>,
pub arch: Option<String>,
pub accuracy: u8,
pub detail_accuracy: Option<u8>,
pub source: OsSource,
pub evidence: String,
}
impl OsVerdict {
pub fn as_evidence(&self) -> OsEvidence {
OsEvidence {
source: self.source,
family: self.family.clone(),
device: self.device.clone(),
vendor: self.vendor.clone(),
product: self.product.clone(),
version: self.version.clone(),
kernel: self.kernel.clone(),
arch: self.arch.clone(),
cpe: self.cpe.clone(),
confidence: f32::from(self.accuracy) / 100.0,
evidence: self.evidence.clone(),
}
}
pub fn label(&self) -> String {
match (&self.product, &self.vendor) {
(Some(product), Some(vendor)) if Some(product.as_str()) == self.family.as_deref() => {
vendor.clone()
}
(Some(product), Some(vendor))
if self.device.is_some() && !product.starts_with(vendor.as_str()) =>
{
format!("{vendor} {product}")
}
(Some(product), _) => product.clone(),
(None, vendor) => self
.family
.clone()
.or_else(|| vendor.clone())
.unwrap_or_else(|| self.device.clone().unwrap_or_default()),
}
}
pub fn to_fingerprint(&self) -> OsFingerprint {
let mut fingerprint =
OsFingerprint::new(self.label(), self.accuracy).with_evidence(&*self.evidence);
if let Some(family) = &self.family {
fingerprint = fingerprint.with_family(&**family);
}
if let Some(device) = &self.device {
fingerprint = fingerprint.with_device(&**device);
}
if let Some(vendor) = &self.vendor {
fingerprint = fingerprint.with_vendor(&**vendor);
}
if let Some(version) = &self.version {
fingerprint = fingerprint.with_generation(&**version);
}
if let Some(cpe) = &self.cpe {
fingerprint.add_cpe(&**cpe);
}
if let Some(kernel) = &self.kernel {
fingerprint = fingerprint.with_kernel(&**kernel);
}
if let Some(arch) = &self.arch {
fingerprint = fingerprint.with_arch(&**arch);
}
if let Some(accuracy) = self.detail_accuracy {
fingerprint = fingerprint.with_detail_accuracy(accuracy);
}
fingerprint
}
}
pub fn classify(db: &RuleDb, reply: &StackReply) -> Option<OsVerdict> {
let matched: Vec<&OsDefinition> = db.matching(reply).collect();
score(matched, reply.summary())
}
pub fn classify_series(db: &RuleDb, readings: &[(StackReply, SeriesClasses)]) -> Option<OsVerdict> {
let matched: Vec<&OsDefinition> = readings
.iter()
.flat_map(|(reply, series)| db.matching_with_series(reply, series))
.collect();
let mut lines: Vec<String> = readings
.iter()
.map(|(reply, series)| format!("{} {}", reply.summary(), series.summary()))
.collect();
lines.sort_unstable();
lines.dedup();
score(matched, lines.join(" | "))
}
struct Contradiction;
fn consensus<'a>(
matched: &[&'a OsDefinition],
part: impl Fn(&'a OsDefinition) -> Option<&'a str>,
) -> Result<Option<String>, Contradiction> {
let mut stated = matched.iter().copied().filter_map(part);
let Some(candidate) = stated.next() else {
return Ok(None);
};
match stated.all(|other| other == candidate) {
true => Ok(Some(candidate.to_owned())),
false => Err(Contradiction),
}
}
fn score(matched: Vec<&OsDefinition>, evidence: String) -> Option<OsVerdict> {
if matched.is_empty() {
return None;
}
let family = consensus(&matched, |rule| rule.os.family.as_deref()).ok()?;
let device = consensus(&matched, |rule| rule.os.device.as_deref()).ok()?;
if family.is_none() && device.is_none() {
return None;
}
let agreed = |part: fn(&OsDefinition) -> Option<&str>| -> Option<String> {
consensus(&matched, part).unwrap_or_default()
};
let weight = matched
.iter()
.map(|rule| rule.weight)
.fold(f32::INFINITY, f32::min);
let base = if matched
.iter()
.all(|rule| rule.provenance == Provenance::Measured)
{
MEASURED_ACCURACY
} else {
PUBLISHED_ACCURACY
};
let accuracy = (base * weight).clamp(0.0, f32::from(MAX_STACK_ACCURACY)) as u8;
if accuracy < MIN_REPORTABLE_ACCURACY {
return None;
}
let (vendor, product, version, cpe) = (
agreed(|rule| rule.os.vendor.as_deref()),
agreed(|rule| rule.os.product.as_deref()),
agreed(|rule| rule.os.version.as_deref()),
agreed(|rule| rule.os.cpe.as_deref()),
);
Some(OsVerdict {
family,
device,
detail_accuracy: (vendor.is_some()
|| product.is_some()
|| version.is_some()
|| cpe.is_some())
.then_some(accuracy),
vendor,
product,
version,
kernel: None,
arch: None,
cpe,
accuracy,
source: OsSource::TcpStack,
evidence,
})
}
pub fn classify_reply(
ip: crate::model::capture::IpObservation,
segment: &[u8],
) -> Option<OsVerdict> {
let observed = StackObservation::from_tcp(ip, segment)?;
classify(RuleDb::global(), &observed.into())
}
pub fn classify_echo_reply(
ip: crate::model::capture::IpObservation,
message: &[u8],
sent_payload: &[u8],
) -> Option<OsVerdict> {
let observed = super::observation::EchoObservation::from_echo_reply(ip, message, sent_payload)?;
classify(RuleDb::global(), &observed.into())
}
#[cfg(test)]
mod tests {
use super::*;
use crate::model::capture::{IpObservation, Ipv4Observation};
use crate::protocols::tcp::flags;
fn ip() -> IpObservation {
IpObservation::V4(Ipv4Observation {
ttl: 64,
identification: 0,
dont_fragment: true,
more_fragments: false,
dscp: 0,
ecn: 0,
})
}
fn segment(flag_byte: u8, window: u16, options: &[u8]) -> Vec<u8> {
let mut bytes = vec![0u8; 20 + options.len()];
bytes[0..2].copy_from_slice(&80u16.to_be_bytes());
bytes[2..4].copy_from_slice(&50_000u16.to_be_bytes());
bytes[4..8].copy_from_slice(&1u32.to_be_bytes());
bytes[12] = (((20 + options.len()) / 4) as u8) << 4;
bytes[13] = flag_byte;
bytes[14..16].copy_from_slice(&window.to_be_bytes());
bytes[20..].copy_from_slice(options);
bytes
}
const DEBIAN_BOOKWORM: [u8; 20] = [
0x02, 0x04, 0x05, 0xb4, 0x04, 0x02, 0x08, 0x0a, 0xad, 0x58, 0xa5, 0xa7, 0x64, 0x48, 0x96,
0x12, 0x01, 0x03, 0x03, 0x07,
];
#[test]
fn a_recorded_linux_reply_is_named_linux() {
let verdict = classify_reply(
ip(),
&segment(flags::SYN | flags::ACK, 65_160, &DEBIAN_BOOKWORM),
)
.expect("a labelled Linux host is identified");
assert_eq!(verdict.family.as_deref(), Some("Linux"));
assert_eq!(verdict.source, OsSource::TcpStack);
let fingerprint = verdict.to_fingerprint();
assert_eq!(fingerprint.name(), "Linux");
assert_eq!(fingerprint.family(), Some("Linux"));
}
#[test]
fn the_weight_bound_leaves_no_dead_range() {
use super::super::MAX_RULE_WEIGHT;
let saturates_at = f32::from(MAX_STACK_ACCURACY) / MEASURED_ACCURACY;
assert!(
saturates_at < MAX_RULE_WEIGHT,
"a measured rule saturates at {saturates_at}, which is at or above the \
bound of {MAX_RULE_WEIGHT}, so no weight reaches the ceiling"
);
assert!(
MAX_RULE_WEIGHT < saturates_at * 2.0,
"weights from {saturates_at} to {MAX_RULE_WEIGHT} all produce the same \
answer, so most of the range an author can reach for does nothing"
);
}
#[test]
fn stack_evidence_alone_never_reaches_high_confidence() {
let verdict = classify_reply(
ip(),
&segment(flags::SYN | flags::ACK, 65_160, &DEBIAN_BOOKWORM),
)
.expect("a labelled Linux host is identified");
assert!(verdict.accuracy <= MAX_STACK_ACCURACY);
assert!(
!verdict.to_fingerprint().is_highly_confident(),
"one reply's shape is one observation, however many of its fields agree"
);
}
#[test]
fn a_shape_no_rule_describes_is_reported_as_nothing() {
let nothing_emits = [2, 4, 0x05, 0xb4, 99, 2, 1, 1];
let verdict = classify_reply(
ip(),
&segment(flags::SYN | flags::ACK, 65_160, ¬hing_emits),
);
assert!(verdict.is_none());
}
#[test]
fn a_linux_host_with_tuned_receive_buffers_is_still_linux() {
for window in [12_345u16, 29_200, 64_240, 65_160] {
let verdict = classify_reply(
ip(),
&segment(flags::SYN | flags::ACK, window, &DEBIAN_BOOKWORM),
)
.unwrap_or_else(|| panic!("a Linux handshake advertising {window} names nothing"));
assert_eq!(verdict.family.as_deref(), Some("Linux"));
}
}
#[test]
fn a_distribution_is_named_by_its_distribution() {
let verdict = OsVerdict {
family: Some("Linux".to_owned()),
device: None,
vendor: Some("Debian".to_owned()),
product: Some("Linux".to_owned()),
version: Some("12".to_owned()),
kernel: None,
arch: None,
cpe: None,
accuracy: 84,
detail_accuracy: Some(55),
source: OsSource::ServiceBanner,
evidence: "service banner names Linux".to_owned(),
};
let fingerprint = verdict.to_fingerprint();
assert_eq!(fingerprint.name(), "Debian");
assert_eq!(fingerprint.family(), Some("Linux"));
assert_eq!(
fingerprint.to_string(),
"Linux [84%] · Debian 12 [55%]",
"the family carries what several sources agreed; the release carries \
what the one source that named it was worth"
);
}
#[test]
fn a_model_number_is_labelled_with_the_maker_that_built_it() {
let verdict = OsVerdict {
family: Some("Network device".to_owned()),
device: Some("Printer".to_owned()),
vendor: Some("Brother".to_owned()),
product: Some("NC-8700w".to_owned()),
version: Some("ZL".to_owned()),
kernel: None,
arch: None,
cpe: None,
accuracy: 40,
detail_accuracy: Some(56),
source: OsSource::SnmpAgent,
evidence: "snmp agent names NC-8700w".to_owned(),
};
let fingerprint = verdict.to_fingerprint();
assert_eq!(fingerprint.name(), "Brother NC-8700w");
assert_eq!(fingerprint.device(), Some("Printer"));
assert_eq!(fingerprint.family(), Some("Network device"));
let spelled_out = OsVerdict {
product: Some("Brother HL-1660e".to_owned()),
..verdict
};
assert_eq!(spelled_out.label(), "Brother HL-1660e");
}
#[test]
fn a_verdict_without_a_family_is_still_named() {
let verdict = OsVerdict {
family: None,
device: Some("Printer".to_owned()),
vendor: Some("Brother".to_owned()),
product: Some("NC-8700w".to_owned()),
version: Some("ZL".to_owned()),
kernel: None,
arch: None,
cpe: None,
accuracy: 56,
detail_accuracy: Some(56),
source: OsSource::SnmpAgent,
evidence: "snmp agent names NC-8700w".to_owned(),
};
let fingerprint = verdict.to_fingerprint();
assert_eq!(fingerprint.name(), "Brother NC-8700w");
assert_eq!(fingerprint.family(), None);
}
#[test]
fn a_vendor_without_a_product_does_not_replace_the_family() {
let verdict = OsVerdict {
family: Some("Windows".to_owned()),
device: None,
vendor: Some("Microsoft".to_owned()),
product: None,
version: Some("10".to_owned()),
kernel: None,
arch: None,
cpe: None,
accuracy: 60,
detail_accuracy: Some(60),
source: OsSource::ServiceBanner,
evidence: "service banner names Windows".to_owned(),
};
assert_eq!(verdict.to_fingerprint().name(), "Windows");
}
#[test]
fn a_reset_names_nothing() {
assert!(classify_reply(ip(), &segment(flags::RST | flags::ACK, 0, &[])).is_none());
}
#[test]
fn rules_that_contradict_each_other_name_nothing() {
use super::super::signature::{
MatchRule, OsDefinition, OsIdentity, Predicate, Provenance, ReplyKind,
};
let rule = |family: &str| OsDefinition {
os: OsIdentity {
family: Some(family.to_string()),
device: None,
vendor: None,
product: None,
version: None,
cpe: None,
},
provenance: Provenance::Measured,
notes: None,
weight: 1.0,
r#match: MatchRule {
reply: ReplyKind::SynAck,
initial_hops: Some(Predicate {
equals: Some(64),
..Default::default()
}),
..Default::default()
},
example: Vec::new(),
};
let db = RuleDb::try_from_rules(vec![rule("Linux"), rule("Windows")])
.expect("the rules are well formed");
let observed = StackObservation::from_tcp(
ip(),
&segment(flags::SYN | flags::ACK, 65_160, &DEBIAN_BOOKWORM),
)
.unwrap()
.into();
assert_eq!(db.matching(&observed).count(), 2, "both rules match");
assert!(
classify(&db, &observed).is_none(),
"and the contradiction is reported as no answer, not as the heavier rule"
);
}
}
#[cfg(test)]
mod second_family {
use super::*;
use crate::model::capture::{IpObservation, Ipv4Observation};
use crate::protocols::tcp::flags;
fn darwin_options() -> Vec<u8> {
let mut options = vec![2, 4, 0x05, 0xb4]; options.push(1); options.extend_from_slice(&[3, 3, 6]); options.push(1); options.push(1); options.extend_from_slice(&[8, 10]); options.extend_from_slice(&0x1122_3344u32.to_be_bytes());
options.extend_from_slice(&0x5566_7788u32.to_be_bytes());
options.extend_from_slice(&[4, 2]); options.push(0); options.push(0); options
}
fn segment(flag_byte: u8, window: u16, options: &[u8]) -> Vec<u8> {
let mut bytes = vec![0u8; 20 + options.len()];
bytes[0..2].copy_from_slice(&22u16.to_be_bytes());
bytes[2..4].copy_from_slice(&50_000u16.to_be_bytes());
bytes[4..8].copy_from_slice(&1u32.to_be_bytes());
bytes[12] = (((20 + options.len()) / 4) as u8) << 4;
bytes[13] = flag_byte;
bytes[14..16].copy_from_slice(&window.to_be_bytes());
bytes[20..].copy_from_slice(options);
bytes
}
fn ip() -> IpObservation {
IpObservation::V4(Ipv4Observation {
ttl: 64,
identification: 0,
dont_fragment: true,
more_fragments: false,
dscp: 0,
ecn: 0,
})
}
#[tokio::test(flavor = "current_thread")]
async fn a_measured_darwin_reply_is_named_macos_and_not_linux() {
let observed = classify_reply(
ip(),
&segment(flags::SYN | flags::ACK, 65_535, &darwin_options()),
)
.expect("a labelled Mac is identified");
assert_eq!(observed.family.as_deref(), Some("macOS"));
assert_eq!(observed.vendor.as_deref(), Some("Apple"));
assert_eq!(observed.accuracy, MEASURED_ACCURACY as u8);
}
#[test]
fn a_flat_window_is_not_read_as_a_multiple() {
let observed = StackObservation::from_tcp(
ip(),
&segment(flags::SYN | flags::ACK, 65_535, &darwin_options()),
)
.expect("the reply parses");
assert_eq!(observed.window, 65_535);
assert_eq!(observed.effective_mss(), Some(1448));
assert_eq!(
observed.window_in_units(),
Some((45, 375)),
"the derived figures exist, and describe the path rather than the sender"
);
}
}
#[cfg(test)]
mod series_backed {
use super::*;
use crate::fingerprint::os::series::{ClockClass, IdClass, IsnClass};
use crate::model::capture::{IpObservation, Ipv4Observation};
use crate::protocols::tcp::flags;
use super::super::signature::{MatchRule, OsIdentity, Predicate, ReplyKind};
fn ip() -> IpObservation {
IpObservation::V4(Ipv4Observation {
ttl: 64,
identification: 0,
dont_fragment: true,
more_fragments: false,
dscp: 0,
ecn: 0,
})
}
fn syn_ack() -> StackReply {
let mut bytes = vec![0u8; 20];
bytes[0..2].copy_from_slice(&22u16.to_be_bytes());
bytes[2..4].copy_from_slice(&50_000u16.to_be_bytes());
bytes[12] = 5 << 4;
bytes[13] = flags::SYN | flags::ACK;
bytes[14..16].copy_from_slice(&64_240u16.to_be_bytes());
StackObservation::from_tcp(ip(), &bytes)
.expect("a handshake answer")
.into()
}
fn hashed() -> SeriesClasses {
SeriesClasses {
identifiers: IdClass::Zero,
sequences: IsnClass::Hashed,
clock: ClockClass::Hertz(1000),
}
}
fn named(family: &str, version: Option<&str>) -> OsIdentity {
OsIdentity {
family: Some(family.to_owned()),
device: None,
vendor: None,
product: version.map(|_| "Debian".to_owned()),
version: version.map(str::to_owned),
cpe: None,
}
}
fn rule(os: OsIdentity, r#match: MatchRule) -> OsDefinition {
OsDefinition {
os,
provenance: Provenance::Measured,
notes: None,
weight: 1.0,
r#match,
example: Vec::new(),
}
}
fn at_64() -> Option<Predicate<u8>> {
Some(Predicate {
equals: Some(64),
..Default::default()
})
}
fn is(name: &str) -> Option<Predicate<String>> {
Some(Predicate {
equals: Some(name.to_owned()),
..Default::default()
})
}
#[test]
fn a_series_rule_cannot_be_satisfied_by_one_reply() {
let db = RuleDb::try_from_rules(vec![rule(
named("Linux", Some("6.x")),
MatchRule {
reply: ReplyKind::SynAck,
initial_hops: at_64(),
sequence_class: is("hashed"),
..Default::default()
},
)])
.expect("the rules are well formed");
let reply = syn_ack();
assert!(
classify(&db, &reply).is_none(),
"the passive path has no series, so a series rule must fail against it"
);
let verdict = classify_series(&db, &[(reply, hashed())])
.expect("the same rule matches once the series is known");
assert_eq!(verdict.family.as_deref(), Some("Linux"));
assert_eq!(verdict.version.as_deref(), Some("6.x"));
}
#[test]
fn a_broader_rule_matching_beside_a_finer_one_does_not_erase_the_version() {
let db = RuleDb::try_from_rules(vec![
rule(
named("Linux", None),
MatchRule {
reply: ReplyKind::SynAck,
initial_hops: at_64(),
..Default::default()
},
),
rule(
named("Linux", Some("6.x")),
MatchRule {
reply: ReplyKind::SynAck,
initial_hops: at_64(),
sequence_class: is("hashed"),
..Default::default()
},
),
])
.expect("the rules are well formed");
let reply = syn_ack();
assert_eq!(
db.matching_with_series(&reply, &hashed()).count(),
2,
"both rules describe this host"
);
let verdict =
classify_series(&db, &[(reply, hashed())]).expect("a host both rules describe");
assert_eq!(verdict.family.as_deref(), Some("Linux"));
assert_eq!(
verdict.version.as_deref(),
Some("6.x"),
"the finer rule states a version and the broader one abstains"
);
}
#[test]
fn two_rules_naming_different_versions_keep_neither() {
let with_version = |version: &str, class: &str| {
rule(
named("Linux", Some(version)),
MatchRule {
reply: ReplyKind::SynAck,
initial_hops: at_64(),
sequence_class: is(class),
..Default::default()
},
)
};
let db = RuleDb::try_from_rules(vec![
with_version("6.x", "hashed"),
with_version("7.x", "hashed"),
])
.expect("the rules are well formed");
let verdict = classify_series(&db, &[(syn_ack(), hashed())]).expect("the family is agreed");
assert_eq!(verdict.family.as_deref(), Some("Linux"));
assert!(
verdict.version.is_none(),
"a contradiction about the release is not a release"
);
}
#[test]
fn a_host_read_several_ways_still_yields_one_verdict() {
let db = RuleDb::try_from_rules(vec![rule(
named("Linux", None),
MatchRule {
reply: ReplyKind::SynAck,
initial_hops: at_64(),
..Default::default()
},
)])
.expect("the rules are well formed");
let one = classify_series(&db, &[(syn_ack(), hashed())]).expect("one reading names it");
let twice = classify_series(&db, &[(syn_ack(), hashed()), (syn_ack(), hashed())])
.expect("two readings still name it");
assert_eq!(one.family, twice.family);
assert_eq!(
one.accuracy, twice.accuracy,
"reading one stack twice is not two pieces of evidence"
);
}
}