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 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"),
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 siblings = [
("os.vendor", vendor.as_deref()),
("os.family", family.as_deref()),
("os.product", product.as_deref()),
("os.version", version.as_deref()),
];
let cpe23 = fill(self.cpe23.as_deref(), captures)
.and_then(|template| fill_siblings(&template, &siblings));
Self {
vendor,
family,
product,
version,
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,
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,
cpe: None,
accuracy: 65,
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;
use crate::fingerprint::prefilter::Prefilter;
#[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 = db
.signatures_for_port(port)
.iter()
.chain(db.prefilter().candidates(banner).iter())
.filter_map(|&index| db.signature(index).identify(banner))
.find_map(|matched| matched.os);
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"
);
}
}