use std::collections::HashMap;
use std::sync::OnceLock;
use crate::fingerprint::os::OsMetadata;
use crate::fingerprint::signature::{MAX_COMPILED_REGEX_BYTES, MatchRule};
use crate::model::host::OsSource;
use crate::warn;
use super::model::{Evidence, SourceId};
use super::pattern::{self, CompiledPattern};
use crate::model::confidence::Confidence;
#[derive(Debug)]
pub struct Signature {
service: String,
identifies_service: bool,
product: Option<String>,
vendor: Option<String>,
version_group: Option<u8>,
pattern: String,
compiled: OnceLock<Option<CompiledPattern>>,
os: Option<Box<OsMetadata>>,
#[allow(clippy::box_collection)]
hardware: Option<Box<HashMap<String, String>>>,
cpe: Option<String>,
service_version: Option<String>,
component: Option<Component>,
extrainfo: Option<String>,
}
#[derive(Debug)]
struct Component {
product: Option<String>,
version: Option<String>,
}
impl Component {
fn from_map(rule: &MatchRule) -> Option<Self> {
let product = metadata_value(rule, "service.component.product");
let version = metadata_value(rule, "service.component.version");
(product.is_some() || version.is_some()).then_some(Self { product, version })
}
fn resolve(&self, captures: &[String]) -> Option<String> {
let product = super::os::fill(self.product.as_deref(), captures);
let version = super::os::fill(self.version.as_deref(), captures);
match (product, version) {
(Some(product), Some(version)) => Some(format!("{product} {version}")),
(Some(only), None) | (None, Some(only)) => Some(only),
(None, None) => None,
}
}
}
fn identifies_service(rule: &MatchRule) -> bool {
metadata_value(rule, "service.certainty")
.map(|certainty| !matches!(certainty.trim(), "0" | "0.0"))
.unwrap_or(true)
}
fn metadata_value(rule: &MatchRule, key: &str) -> Option<String> {
rule.metadata
.as_ref()?
.get(key)
.filter(|value| !value.is_empty())
.cloned()
}
fn resolve_service_cpe(template: &str, version: Option<&str>) -> Option<String> {
const VERSION: &str = "{service.version}";
if !template.contains(VERSION) {
return Some(template.to_string());
}
Some(template.replace(VERSION, version?))
}
impl Signature {
pub fn new(service: &str, rule: &MatchRule) -> Self {
Self {
service: service.to_string(),
identifies_service: identifies_service(rule),
product: rule.product.clone(),
vendor: rule.vendor.clone(),
version_group: rule.version_group,
pattern: rule.pattern.clone(),
compiled: OnceLock::new(),
hardware: rule.metadata.as_ref().and_then(|metadata| {
metadata
.keys()
.any(|key| key.starts_with("hw."))
.then(|| Box::new(metadata.clone()))
}),
os: rule
.metadata
.as_ref()
.and_then(OsMetadata::from_map)
.map(Box::new),
cpe: metadata_value(rule, "service.cpe23"),
service_version: metadata_value(rule, "service.version"),
component: Component::from_map(rule),
extrainfo: metadata_value(rule, "service.extrainfo"),
}
}
pub fn pattern(&self) -> &str {
&self.pattern
}
pub fn compile(&self) {
self.compiled();
}
#[cfg(test)]
pub(crate) fn is_compiled(&self) -> bool {
self.compiled.get().is_some()
}
fn compiled(&self) -> Option<&CompiledPattern> {
self.compiled
.get_or_init(
|| match pattern::compile(&self.pattern, MAX_COMPILED_REGEX_BYTES) {
Ok(compiled) => Some(compiled),
Err(e) => {
warn!(
"fingerprint signature for service '{}' was skipped: its pattern \
failed to compile ({e}); pattern = {:?}",
self.service, self.pattern
);
None
}
},
)
.as_ref()
}
pub fn identify(&self, response: &str, attested_by: OsSource) -> Option<Match> {
let wants_captures =
self.os.is_some() || self.component.is_some() || self.extrainfo.is_some();
let matched = self.compiled()?.identify_with_captures(
response,
self.version_group,
wants_captures,
)?;
let version = matched
.version
.as_deref()
.and_then(super::identity_field)
.map(str::to_owned);
let confidence = if version.is_some() {
Confidence::Strong
} else {
Confidence::Probable
};
let detail = self.product.is_some() as u8 + self.vendor.is_some() as u8;
let cpe = self.cpe.as_deref().and_then(|template| {
resolve_service_cpe(
template,
version.as_deref().or(self.service_version.as_deref()),
)
});
let mut evidence = Evidence::new(SourceId::BannerRegex, confidence);
if self.identifies_service {
evidence = evidence.with_service(self.service.clone());
}
evidence.product = self.product.clone();
evidence.vendor = self.vendor.clone();
evidence.version = version;
evidence.cpe = cpe;
let captures = matched.captures.as_deref().unwrap_or(&[]);
evidence.extrainfo = super::os::fill(self.extrainfo.as_deref(), captures)
.or_else(|| {
self.component
.as_ref()
.and_then(|component| component.resolve(captures))
})
.filter(|extra| super::identity_field(extra).is_some());
Some(Match {
evidence,
quality: MatchQuality {
confidence,
detail,
specificity: matched.match_len,
},
hardware: self.hardware.as_deref().and_then(|metadata| {
super::os::hardware_from(metadata, matched.captures.as_deref().unwrap_or(&[]))
}),
arch: self.os.as_deref().and_then(|metadata| {
metadata
.resolve(matched.captures.as_deref().unwrap_or(&[]))
.arch
}),
os: self.os.as_deref().and_then(|metadata| {
super::os::banner_evidence(
metadata,
matched.captures.as_deref().unwrap_or(&[]),
attested_by,
)
}),
})
}
}
pub fn resolved_service_name(winner: &Match, all: &[Match]) -> Option<String> {
if !is_generic_service(winner.evidence.service.as_deref()) {
return winner.evidence.service.clone();
}
let Some(product) = winner.evidence.product.as_deref() else {
return winner.evidence.service.clone();
};
all.iter()
.find(|m| {
m.quality.confidence == winner.quality.confidence
&& !is_generic_service(m.evidence.service.as_deref())
&& m.evidence
.service
.as_deref()
.is_some_and(|service| names_the_same(service, product))
})
.and_then(|m| m.evidence.service.clone())
.or_else(|| winner.evidence.service.clone())
}
fn is_generic_service(service: Option<&str>) -> bool {
matches!(service, Some("http"))
}
fn names_the_same(service: &str, product: &str) -> bool {
let service = service.to_ascii_lowercase();
let product = product.to_ascii_lowercase();
product.contains(&service) || service.contains(&product)
}
pub struct Match {
pub evidence: Evidence,
pub quality: MatchQuality,
pub hardware: Option<crate::model::host::HardwareInfo>,
pub arch: Option<String>,
pub os: Option<crate::model::host::OsEvidence>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct MatchQuality {
confidence: Confidence,
detail: u8,
specificity: usize,
}
impl MatchQuality {
pub fn specificity(self) -> usize {
self.specificity
}
}
#[cfg(test)]
mod tests {
use super::*;
fn rule(pattern: &str, version_group: Option<u8>, product: Option<&str>) -> MatchRule {
MatchRule {
name: None,
pattern: pattern.to_string(),
version_group,
vendor: None,
product: product.map(str::to_string),
context: None,
example: None,
metadata: None,
}
}
fn rule_with_metadata(
pattern: &str,
version_group: Option<u8>,
metadata: &[(&str, &str)],
) -> MatchRule {
let mut rule = rule(pattern, version_group, None);
rule.metadata = Some(
metadata
.iter()
.map(|(key, value)| (key.to_string(), value.to_string()))
.collect(),
);
rule
}
#[test]
fn a_rule_can_state_extrainfo_over_its_own_captures() {
let mut rule = rule(r"^OpenSSH_(\S+) (\S+)", Some(1), Some("OpenSSH"));
rule.metadata = Some(
[("service.extrainfo".to_string(), "{capture:2}".to_string())]
.into_iter()
.collect(),
);
let matched = Signature::new("ssh", &rule)
.identify("OpenSSH_10.0p2 Debian-7+deb13u4", OsSource::ServiceBanner)
.expect("the pattern matches");
assert_eq!(
matched.evidence.extrainfo.as_deref(),
Some("Debian-7+deb13u4")
);
}
#[test]
fn stated_extrainfo_past_the_bound_is_refused() {
let mut rule = rule(r"^OpenSSH_(\S+) (\S+)", Some(1), Some("OpenSSH"));
rule.metadata = Some(
[("service.extrainfo".to_string(), "{capture:2}".to_string())]
.into_iter()
.collect(),
);
let hostile = format!(
"OpenSSH_10.0p2 {}",
"A".repeat(crate::fingerprint::MAX_IDENTITY_BYTES + 1)
);
let matched = Signature::new("ssh", &rule)
.identify(&hostile, OsSource::ServiceBanner)
.expect("the pattern still matches");
assert_eq!(matched.evidence.extrainfo, None);
}
#[test]
fn the_component_a_rule_names_becomes_the_services_extra_info() {
let ev = Signature::new(
"http",
&rule_with_metadata(
r"(?i)^SimpleHTTP/((?:\d+\.)*\d+)\s*Python/((?:\d+\.)*\d+)$",
Some(1),
&[
("service.component.product", "Python"),
("service.component.version", "{capture:2}"),
],
),
)
.identify("SimpleHTTP/0.6 Python/3.13.5", OsSource::ServiceBanner)
.expect("matches")
.evidence;
assert_eq!(ev.version.as_deref(), Some("0.6"));
assert_eq!(ev.extrainfo.as_deref(), Some("Python 3.13.5"));
}
#[test]
fn a_service_cpe_is_resolved_carried_and_dropped_when_unfillable() {
let ev = Signature::new(
"http",
&rule_with_metadata(
r"^libwww-perl-daemon/([.0-9]+)$",
Some(1),
&[("service.cpe23", "cpe:/a:perl:perl:{service.version}")],
),
)
.identify("libwww-perl-daemon/1.36", OsSource::ServiceBanner)
.expect("matches")
.evidence;
assert_eq!(ev.cpe.as_deref(), Some("cpe:/a:perl:perl:1.36"));
let ev = Signature::new(
"http",
&rule_with_metadata(
"^Transmission$",
None,
&[("service.cpe23", "cpe:/a:transmissionbt:transmission:-")],
),
)
.identify("Transmission", OsSource::ServiceBanner)
.unwrap()
.evidence;
assert_eq!(
ev.cpe.as_deref(),
Some("cpe:/a:transmissionbt:transmission:-")
);
let ev = Signature::new(
"http",
&rule_with_metadata(
"^perl$",
None,
&[("service.cpe23", "cpe:/a:perl:perl:{service.version}")],
),
)
.identify("perl", OsSource::ServiceBanner)
.unwrap()
.evidence;
assert_eq!(ev.cpe, None);
let ev = Signature::new(
"ftp",
&rule_with_metadata(
"^220 Microsoft FTP",
None,
&[
("service.cpe23", "cpe:/a:microsoft:iis:{service.version}"),
("service.version", "5.0"),
],
),
)
.identify("220 Microsoft FTP Service", OsSource::ServiceBanner)
.unwrap()
.evidence;
assert_eq!(ev.cpe.as_deref(), Some("cpe:/a:microsoft:iis:5.0"));
}
#[test]
fn captures_version_and_reports_strong_confidence() {
let sig = Signature::new(
"ssh",
&rule(r"^SSH-[\d.]+-OpenSSH_([\w.]+)", Some(1), Some("OpenSSH")),
);
let ev = sig
.identify("SSH-2.0-OpenSSH_9.6p1 Debian", OsSource::ServiceBanner)
.expect("should match")
.evidence;
assert_eq!(ev.service.as_deref(), Some("ssh"));
assert_eq!(ev.product.as_deref(), Some("OpenSSH"));
assert_eq!(ev.version.as_deref(), Some("9.6p1"));
assert_eq!(ev.confidence, Confidence::Strong);
}
#[test]
fn bare_match_is_probable_and_names_no_product() {
let sig = Signature::new("http", &rule("^HTTP/1.1", None, None));
let ev = sig
.identify("HTTP/1.1 200 OK", OsSource::ServiceBanner)
.expect("should match")
.evidence;
assert_eq!(ev.confidence, Confidence::Probable);
assert_eq!(ev.service.as_deref(), Some("http"));
assert_eq!(
ev.product, None,
"the rule named no product, so neither does the evidence"
);
}
#[test]
fn specific_match_outranks_generic_for_same_response() {
let response = "HTTP/1.1 200 OK\r\nServer: nginx/1.25.3\r\n";
let generic = Signature::new("http", &rule(r"(?i)^HTTP/\d+\.\d+\s+\d+", None, None));
let mut nginx_rule = rule(r"(?i)Server:\s*nginx/([\d.]+)", Some(1), Some("nginx"));
nginx_rule.vendor = Some("NGINX".to_string());
let nginx = Signature::new("http", &nginx_rule);
let generic_q = generic
.identify(response, OsSource::ServiceBanner)
.expect("generic matches")
.quality;
let nginx_q = nginx
.identify(response, OsSource::ServiceBanner)
.expect("nginx matches")
.quality;
assert!(nginx_q > generic_q, "specific match must outrank generic");
}
#[test]
fn no_match_returns_none() {
let sig = Signature::new("http", &rule("^HTTP/1.1", None, None));
assert!(
sig.identify("SSH-2.0-OpenSSH_9.6", OsSource::ServiceBanner)
.is_none()
);
}
#[test]
fn backreference_signature_matches_via_the_fancy_engine() {
let sig = Signature::new("dup", &rule(r"^(\w+) \1$", None, None));
assert!(
sig.identify("token token", OsSource::ServiceBanner)
.is_some()
);
assert!(
sig.identify("token other", OsSource::ServiceBanner)
.is_none()
);
}
#[test]
fn unsupported_pattern_is_skipped_not_fatal() {
let sig = Signature::new("x", &rule("(", None, None));
assert!(sig.identify("aa", OsSource::ServiceBanner).is_none());
}
}