use std::collections::HashMap;
use super::evidence::OsEvidence;
use super::verdict::OsSource;
#[derive(Debug, Clone, Default, PartialEq)]
pub struct OsMetadata {
pub vendor: Option<String>,
pub family: Option<String>,
pub product: Option<String>,
pub version: Option<String>,
pub kernel: Option<String>,
pub cpe23: Option<String>,
pub certainty: Option<f32>,
}
impl OsMetadata {
pub fn from_map(metadata: &HashMap<String, String>) -> Option<Self> {
let get = |key: &str| metadata.get(key).filter(|v| !v.is_empty()).cloned();
let found = Self {
vendor: get("os.vendor"),
family: get("os.family"),
product: get("os.product"),
version: get("os.version"),
kernel: get("os.kernel"),
cpe23: get("os.cpe23"),
certainty: get("os.certainty").and_then(|v| v.parse().ok()),
};
(found.family.is_some() || found.product.is_some()).then_some(found)
}
pub fn resolve(&self, captures: &[String]) -> Self {
let vendor = fill(self.vendor.as_deref(), captures);
let family = fill(self.family.as_deref(), captures);
let product = fill(self.product.as_deref(), captures);
let version = fill(self.version.as_deref(), captures);
let kernel = fill(self.kernel.as_deref(), captures);
let siblings = [
("os.vendor", vendor.as_deref()),
("os.family", family.as_deref()),
("os.product", product.as_deref()),
("os.version", version.as_deref()),
("os.kernel", kernel.as_deref()),
];
let cpe23 = fill(self.cpe23.as_deref(), captures)
.and_then(|template| fill_siblings(&template, &siblings));
Self {
vendor,
family,
product,
version,
kernel,
cpe23,
certainty: self.certainty,
}
}
}
fn fill(template: Option<&str>, captures: &[String]) -> Option<String> {
let template = template?;
if !template.contains("{capture:") {
return Some(template.to_string());
}
let mut out = String::with_capacity(template.len());
let mut rest = template;
while let Some(start) = rest.find("{capture:") {
out.push_str(&rest[..start]);
let after = &rest[start + "{capture:".len()..];
let end = after.find('}')?;
let index: usize = after[..end].parse().ok()?;
let value = captures.get(index).filter(|value| !value.is_empty())?;
out.push_str(value);
rest = &after[end + 1..];
}
out.push_str(rest);
let out = out.trim().to_string();
(!out.is_empty()).then_some(out)
}
fn fill_siblings(template: &str, siblings: &[(&str, Option<&str>)]) -> Option<String> {
let mut out = template.to_string();
for (name, value) in siblings {
let token = format!("{{{name}}}");
if out.contains(&token) {
out = out.replace(&token, value.filter(|v| !v.is_empty())?);
}
}
(!out.trim().is_empty()).then(|| out.trim().to_string())
}
pub fn evidence_from(metadata: &OsMetadata, captures: &[String]) -> Option<OsEvidence> {
let resolved = metadata.resolve(captures);
let family = resolved
.family
.clone()
.or_else(|| resolved.product.clone())?;
let certainty = resolved.certainty.unwrap_or(1.0).clamp(0.0, 1.0);
if certainty <= f32::EPSILON {
return None;
}
let confidence = certainty * BANNER_CEILING;
let described = resolved
.product
.clone()
.or_else(|| resolved.family.clone())
.unwrap_or_else(|| family.clone());
Some(OsEvidence {
source: OsSource::ServiceBanner,
family,
vendor: resolved.vendor,
product: resolved.product,
version: resolved.version,
kernel: resolved.kernel,
cpe: resolved.cpe23,
confidence,
evidence: format!("service banner names {described}"),
})
}
const BANNER_CEILING: f32 = 0.55;
#[cfg(test)]
mod tests {
use super::*;
fn metadata(pairs: &[(&str, &str)]) -> OsMetadata {
let map: HashMap<String, String> = pairs
.iter()
.map(|(k, v)| ((*k).to_string(), (*v).to_string()))
.collect();
OsMetadata::from_map(&map).expect("names an operating system")
}
#[test]
fn a_real_rule_builds_its_values_from_what_the_pattern_captured() {
let rule = metadata(&[
("os.vendor", "Microsoft"),
("os.family", "Windows"),
("os.product", "{capture:1}"),
("os.edition", "{capture:2}"),
("os.version", "{capture:3}"),
]);
let resolved = rule.resolve(&[
"Windows Server 2003 Standard SP2".to_string(),
"Windows Server 2003".to_string(),
"Standard".to_string(),
"SP2".to_string(),
]);
assert_eq!(resolved.vendor.as_deref(), Some("Microsoft"));
assert_eq!(resolved.family.as_deref(), Some("Windows"));
assert_eq!(resolved.product.as_deref(), Some("Windows Server 2003"));
assert_eq!(resolved.version.as_deref(), Some("SP2"));
}
#[test]
fn a_platform_identifier_is_built_from_a_field_that_was_itself_captured() {
let rule = metadata(&[
("os.family", "Windows"),
("os.product", "Windows 2000"),
("os.version", "{capture:2}"),
("os.cpe23", "cpe:/o:microsoft:windows_2000:{os.version}"),
]);
let resolved = rule.resolve(&[
"Windows 2000 Professional SP4".to_string(),
"Professional".to_string(),
"SP4".to_string(),
]);
assert_eq!(
resolved.cpe23.as_deref(),
Some("cpe:/o:microsoft:windows_2000:SP4"),
"the sibling template must see the resolved capture, not the template"
);
}
#[test]
fn a_template_over_an_absent_capture_drops_the_field_rather_than_half_building_it() {
let rule = metadata(&[
("os.family", "Windows"),
("os.product", "Windows 2000"),
("os.version", "{capture:2}"),
("os.cpe23", "cpe:/o:microsoft:windows_2000:{os.version}"),
]);
let resolved = rule.resolve(&["Windows 2000".to_string(), String::new(), String::new()]);
assert_eq!(resolved.version, None);
assert_eq!(resolved.cpe23, None, "no dangling identifier");
assert_eq!(
resolved.product.as_deref(),
Some("Windows 2000"),
"and the fields that did resolve survive"
);
}
#[test]
fn metadata_that_names_no_system_is_not_kept() {
let map: HashMap<String, String> = [("os.arch".to_string(), "mips".to_string())]
.into_iter()
.collect();
assert!(OsMetadata::from_map(&map).is_none());
}
#[test]
fn the_corpus_own_hedging_lowers_what_a_rule_is_worth() {
let confident = metadata(&[("os.family", "Linux"), ("os.product", "Ubuntu")]);
let hedged = metadata(&[
("os.family", "Linux"),
("os.product", "Ubuntu"),
("os.certainty", "0.5"),
]);
let confident = evidence_from(&confident, &[]).expect("names a system");
let hedged = evidence_from(&hedged, &[]).expect("names a system");
assert!(
hedged.confidence < confident.confidence,
"an unqualified rule is the ordinary case and must outrank a hedged one"
);
}
#[test]
fn a_rule_the_corpus_calls_worthless_produces_no_evidence() {
let worthless = metadata(&[
("os.family", "Linux"),
("os.product", "Ubuntu"),
("os.certainty", "0.0"),
]);
assert!(evidence_from(&worthless, &[]).is_none());
}
#[test]
fn a_banner_alone_names_a_host_but_does_not_settle_it() {
let rule = metadata(&[("os.family", "Linux"), ("os.product", "Ubuntu")]);
let evidence = evidence_from(&rule, &[]).expect("names a system");
assert!(evidence.confidence <= BANNER_CEILING);
let alone = super::super::resolve(vec![evidence]).expect("a banner names a host");
assert!(alone.accuracy >= 40, "reported rather than discarded");
assert!(
!alone.to_fingerprint().is_highly_confident(),
"and not enough on its own to stop looking"
);
}
#[test]
fn a_banner_agreeing_with_the_wire_is_worth_more_than_either() {
use super::super::{OsSource, OsVerdict};
let banner = evidence_from(
&metadata(&[("os.family", "Linux"), ("os.product", "Ubuntu")]),
&[],
)
.expect("names a system");
let stack = OsVerdict {
family: "Linux".to_string(),
vendor: None,
product: None,
version: None,
kernel: None,
cpe: None,
accuracy: 65,
detail_accuracy: None,
source: OsSource::TcpStack,
evidence: "syn-ack opts=M,S,T,N,W".to_string(),
}
.as_evidence();
let together = super::super::resolve(vec![stack, banner]).expect("named");
assert!(
together.accuracy > 65,
"two independent sources agreeing must beat the better one alone"
);
assert_eq!(together.family, "Linux");
}
}
#[cfg(test)]
mod against_the_shipped_corpus {
use crate::fingerprint::SignatureDb;
#[test]
fn a_banner_that_names_a_release_yields_the_release() {
let db = SignatureDb::global();
let debian_12 = crate::fingerprint::analyzer::os_from_banner(
db,
22,
"SSH-2.0-OpenSSH_9.2p1 Debian-2+deb12u10",
)
.expect("a Debian OpenSSH banner names an operating system");
assert_eq!(debian_12.family, "Linux");
assert_eq!(
debian_12.version.as_deref(),
Some("12"),
"the release is the whole reason to read a banner: {debian_12:?}"
);
assert_eq!(
debian_12.cpe.as_deref(),
Some("cpe:/o:debian:debian_linux:12.0"),
"the CPE keeps its registered form, which is a name in somebody \
else's namespace rather than this engine's claim"
);
assert_eq!(debian_12.vendor.as_deref(), Some("Debian"));
let debian_13 = crate::fingerprint::analyzer::os_from_banner(
db,
22,
"SSH-2.0-OpenSSH_10.0p2 Debian-7+deb13u4",
)
.expect("a Debian OpenSSH banner names an operating system");
assert_eq!(debian_13.family, "Linux");
assert_eq!(
debian_13.version.as_deref(),
Some("13"),
"read from the release Debian stamps into its own package version, so a \
release the corpus has never seen still names itself: {debian_13:?}"
);
let backported = crate::fingerprint::analyzer::os_from_banner(
db,
22,
"SSH-2.0-OpenSSH_9.7p1 Debian-1~bpo12+1",
)
.expect("a backport names one too");
assert_eq!(backported.version.as_deref(), Some("12"));
let stripped =
crate::fingerprint::analyzer::os_from_banner(db, 22, "SSH-2.0-OpenSSH_10.0p2");
assert!(
stripped.is_none_or(|os| os.version.is_none()),
"a stripped banner carries no release and must not invent one"
);
}
#[test]
fn arch_is_named_by_its_kernel_because_nothing_else_names_it() {
let db = SignatureDb::global();
let found = crate::fingerprint::analyzer::os_from_banner(
db,
161,
"Linux host 6.12.1-arch1-1 #1 SMP PREEMPT_DYNAMIC Fri, 22 Nov 2024 12:00:00 +0000 x86_64",
)
.expect("an Arch kernel names Arch");
assert_eq!(found.vendor.as_deref(), Some("Arch Linux"));
assert_eq!(found.kernel.as_deref(), Some("6.12.1"));
assert_eq!(
found.version, None,
"a rolling release has no version, and inventing one would be worse \
than the silence it replaced"
);
let by_ssh = crate::fingerprint::analyzer::os_from_banner(db, 22, "SSH-2.0-OpenSSH_10.0p2");
assert!(
by_ssh.is_none_or(|os| os.vendor.is_none()),
"an unmarked upstream banner must not be attributed to any distribution"
);
}
#[test]
fn a_release_names_itself_without_a_machine_to_read_it_from() {
let db = SignatureDb::global();
for (banner, release) in [
("SSH-2.0-OpenSSH_7.4p1 Debian-10+deb9u7", "9"),
("SSH-2.0-OpenSSH_7.9p1 Debian-10+deb10u2", "10"),
("SSH-2.0-OpenSSH_8.4p1 Debian-5+deb11u3", "11"),
] {
let found = crate::fingerprint::analyzer::os_from_banner(db, 22, banner)
.unwrap_or_else(|| panic!("{banner} names nothing"));
assert_eq!(found.family, "Linux");
assert_eq!(found.vendor.as_deref(), Some("Debian"));
assert_eq!(
found.version.as_deref(),
Some(release),
"read from the stamp rather than from a table of known releases: {banner}"
);
}
}
#[test]
fn an_snmp_agent_names_the_system_it_is_running() {
let db = SignatureDb::global();
let sys_descr = "Linux zond 6.1.0-18-arm64 #1 SMP Debian 6.1.76-1 (2024-02-01) aarch64";
let found = crate::fingerprint::analyzer::os_from_banner(db, 161, sys_descr)
.expect("a uname string names an operating system");
assert_eq!(found.family, "Linux");
assert_eq!(
found.kernel.as_deref(),
Some("6.1.0"),
"the kernel release is the whole reason to read this field: {found:?}"
);
assert_eq!(
found.version, None,
"a kernel is not a distribution release, and must not occupy its field \
where it would contradict a banner that named one"
);
assert!(
!found.evidence.to_ascii_lowercase().contains("zond"),
"the nodename is somebody's hostname and must not travel with the finding"
);
}
#[test]
fn real_banners_name_an_operating_system_through_the_shipped_signatures() {
let db = SignatureDb::global();
let cases = [
(22u16, "SSH-2.0-OpenSSH_9.6p1 Debian-3"),
(80, "Microsoft-IIS/4.0"),
];
let mut named = 0usize;
for (port, banner) in cases {
let found = crate::fingerprint::analyzer::os_from_banner(db, port, banner);
if let Some(os) = found {
assert!(!os.family.is_empty(), "a named family is not an empty one");
assert!(os.confidence > 0.0);
named += 1;
}
}
assert_eq!(
named,
cases.len(),
"a shipped signature failed to name an operating system for text it was \
written against, which is what it looks like when the imported metadata \
stops reaching the matcher"
);
}
}