use crate::model::host::OsFingerprint;
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, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum OsSource {
TcpStack,
HardwareVendor,
ServiceBanner,
Hostname,
}
#[derive(Debug, Clone, PartialEq)]
pub struct OsVerdict {
pub family: String,
pub vendor: Option<String>,
pub product: Option<String>,
pub version: Option<String>,
pub cpe: Option<String>,
pub kernel: Option<String>,
pub accuracy: u8,
pub detail_accuracy: Option<u8>,
pub source: OsSource,
pub evidence: String,
}
impl OsVerdict {
pub fn as_evidence(&self) -> super::evidence::OsEvidence {
super::evidence::OsEvidence {
source: self.source,
family: self.family.clone(),
vendor: self.vendor.clone(),
product: self.product.clone(),
version: self.version.clone(),
kernel: self.kernel.clone(),
cpe: self.cpe.clone(),
confidence: f32::from(self.accuracy) / 100.0,
evidence: self.evidence.clone(),
}
}
pub fn to_fingerprint(&self) -> OsFingerprint {
let name = match (&self.product, &self.vendor) {
(Some(product), Some(vendor)) if product == &self.family => vendor.clone(),
(Some(product), _) => product.clone(),
_ => self.family.clone(),
};
let mut fingerprint = OsFingerprint::new(name, self.accuracy)
.with_family(&*self.family)
.with_evidence(&*self.evidence);
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(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(" | "))
}
fn score(matched: Vec<&OsDefinition>, evidence: String) -> Option<OsVerdict> {
let (first, rest) = matched.split_first()?;
if rest.iter().any(|rule| rule.os.family != first.os.family) {
return None;
}
let agreed = |part: fn(&OsDefinition) -> &Option<String>| -> Option<String> {
let mut stated = matched.iter().filter_map(|rule| part(rule).as_deref());
let candidate = stated.next()?;
stated
.all(|other| other == candidate)
.then(|| candidate.to_owned())
};
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),
agreed(|rule| &rule.os.product),
agreed(|rule| &rule.os.version),
agreed(|rule| &rule.os.cpe),
);
Some(OsVerdict {
family: first.os.family.clone(),
detail_accuracy: (vendor.is_some()
|| product.is_some()
|| version.is_some()
|| cpe.is_some())
.then_some(accuracy),
vendor,
product,
version,
kernel: 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, "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 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, "Linux");
}
}
#[test]
fn a_distribution_is_named_by_its_distribution() {
let verdict = OsVerdict {
family: "Linux".to_owned(),
vendor: Some("Debian".to_owned()),
product: Some("Linux".to_owned()),
version: Some("12".to_owned()),
kernel: 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_vendor_without_a_product_does_not_replace_the_family() {
let verdict = OsVerdict {
family: "Windows".to_owned(),
vendor: Some("Microsoft".to_owned()),
product: None,
version: Some("10".to_owned()),
kernel: 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: family.to_string(),
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::from_rules(vec![rule("Linux"), rule("Windows")]);
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, "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: family.to_owned(),
vendor: None,
product: None,
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::from_rules(vec![rule(
named("Linux", Some("6.x")),
MatchRule {
reply: ReplyKind::SynAck,
initial_hops: at_64(),
sequence_class: is("hashed"),
..Default::default()
},
)]);
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, "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::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()
},
),
]);
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, "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::from_rules(vec![
with_version("6.x", "hashed"),
with_version("7.x", "hashed"),
]);
let verdict = classify_series(&db, &[(syn_ack(), hashed())]).expect("the family is agreed");
assert_eq!(verdict.family, "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::from_rules(vec![rule(
named("Linux", None),
MatchRule {
reply: ReplyKind::SynAck,
initial_hops: at_64(),
..Default::default()
},
)]);
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"
);
}
}