use crate::model::capture::{IpObservation, Ipv4Observation};
use super::db::RuleDb;
use super::observation::StackReply;
use super::observation::{StackObservation, TcpOptionKind};
use super::rules;
use super::signature::{Example, Provenance, ReplyKind};
fn observation_from(example: &Example) -> StackReply {
if example.reply == ReplyKind::EchoReply {
return StackReply::Echo(super::observation::EchoObservation {
ip: IpObservation::V4(Ipv4Observation {
ttl: example.remaining_hops,
identification: 0,
dont_fragment: example.dont_fragment,
more_fragments: false,
dscp: 0,
ecn: 0,
}),
code: example.echo_code,
payload_len: 0,
payload_intact: example.echo_payload_intact,
});
}
tcp_observation_from(example)
}
fn tcp_observation_from(example: &Example) -> StackReply {
let layout = example
.option_layout
.split(',')
.filter(|letter| !letter.is_empty())
.map(|letter| match letter {
"E" => TcpOptionKind::EndOfList,
"N" => TcpOptionKind::NoOp,
"M" => TcpOptionKind::MaximumSegmentSize,
"W" => TcpOptionKind::WindowScale,
"S" => TcpOptionKind::SackPermitted,
"K" => TcpOptionKind::Sack,
"T" => TcpOptionKind::Timestamp,
other => panic!("an example names an option letter nothing writes: {other:?}"),
})
.collect();
let flags = match example.reply {
ReplyKind::SynAck => crate::protocols::tcp::flags::SYN | crate::protocols::tcp::flags::ACK,
ReplyKind::Reset => crate::protocols::tcp::flags::RST,
ReplyKind::EchoReply => unreachable!("an echo example is built above"),
};
StackReply::Tcp(StackObservation {
flags,
ip: IpObservation::V4(Ipv4Observation {
ttl: example.remaining_hops,
identification: 0,
dont_fragment: example.dont_fragment,
more_fragments: false,
dscp: 0,
ecn: 0,
}),
window: example.window.unwrap_or_default(),
option_layout: layout,
mss: example.mss,
window_scale: example.window_scale,
timestamps: example
.timestamps
.then_some(super::observation::Timestamps { value: 1, echo: 0 }),
sack_permitted: example.sack_permitted,
quirks: Default::default(),
})
}
#[test]
fn every_example_matches_its_own_rule() {
let db = RuleDb::global();
let mut failures = Vec::new();
for rule in db.rules() {
for example in &rule.example {
let observed = observation_from(example);
if !rules::matches(&rule.r#match, &observed) {
failures.push(format!(
"'{}' no longer matches its own example: {}",
rule.os.family, example.source
));
}
}
}
assert!(failures.is_empty(), "{}", failures.join("\n"));
}
#[test]
fn no_example_matches_another_familys_rule() {
let db = RuleDb::global();
let mut failures = Vec::new();
for owner in db.rules() {
for example in &owner.example {
let observed = observation_from(example);
for other in db.rules() {
if other.os.family == owner.os.family {
continue;
}
if rules::matches(&other.r#match, &observed) {
failures.push(format!(
"'{}' matches an example belonging to '{}': {}",
other.os.family, owner.os.family, example.source
));
}
}
}
}
assert!(failures.is_empty(), "{}", failures.join("\n"));
}
#[test]
fn every_measured_rule_ships_what_it_measured() {
let mut offenders = Vec::new();
for rule in RuleDb::global().rules() {
if rule.provenance == Provenance::Measured && rule.example.is_empty() {
offenders.push(rule.os.family.as_str());
}
}
assert!(
offenders.is_empty(),
"these rules claim to be measured and record no observation: {offenders:?}. \
Either ship the values that were seen, or mark the rule `published`."
);
}
#[test]
fn every_published_rule_says_what_it_rests_on() {
let mut offenders = Vec::new();
for rule in RuleDb::global().rules() {
if rule.provenance == Provenance::Published
&& rule.notes.as_deref().unwrap_or("").trim().len() < 40
{
offenders.push(rule.os.family.as_str());
}
}
assert!(
offenders.is_empty(),
"these rules are unconfirmed and do not say what they rest on: {offenders:?}"
);
}
#[test]
fn the_corpus_covers_the_families_it_says_it_does() {
let db = RuleDb::global();
let mut families: Vec<&str> = db.rules().iter().map(|r| r.os.family.as_str()).collect();
families.sort_unstable();
families.dedup();
assert_eq!(
families,
vec!["FreeBSD", "Linux", "Network device", "Windows", "macOS"],
"the set of families changed; see assets/fingerprinting/os/README.md"
);
}
#[test]
fn every_rule_tests_something() {
for rule in RuleDb::global().rules() {
let r#match = &rule.r#match;
let stated = [
r#match.initial_hops.is_some(),
r#match.dont_fragment.is_some(),
r#match.option_layout.is_some(),
r#match.window.is_some(),
r#match.window_units.is_some(),
r#match.window_remainder.is_some(),
r#match.window_scale.is_some(),
r#match.mss.is_some(),
r#match.timestamps.is_some(),
r#match.sack_permitted.is_some(),
r#match.identifier_class.is_some(),
r#match.sequence_class.is_some(),
r#match.clock_class.is_some(),
]
.into_iter()
.filter(|stated| *stated)
.count();
assert!(
stated > 0,
"'{}' states no predicates, so it matches every reply of its kind",
rule.os.family
);
}
}
#[test]
fn a_handshake_rule_is_never_satisfied_by_a_reset() {
let db = RuleDb::global();
let example = db
.rules()
.iter()
.flat_map(|rule| &rule.example)
.find(|example| example.reply == ReplyKind::SynAck)
.expect("the corpus ships a handshake example");
let mut as_reset = match observation_from(example) {
StackReply::Tcp(observed) => observed,
StackReply::Echo(_) => unreachable!("the example was chosen as a handshake"),
};
as_reset.flags = crate::protocols::tcp::flags::RST;
let as_reset = StackReply::Tcp(as_reset);
for rule in db.rules() {
assert!(
!rules::matches(&rule.r#match, &as_reset),
"'{}' matched a reset, but it is written for a handshake",
rule.os.family
);
}
}
#[test]
fn the_cross_family_check_catches_a_rule_that_is_too_loose() {
use super::signature::{MatchRule, OsDefinition, OsIdentity, Predicate};
let observed = observation_from(
RuleDb::global()
.rules()
.iter()
.flat_map(|rule| &rule.example)
.find(|example| example.reply == ReplyKind::SynAck)
.expect("the corpus ships a handshake example"),
);
let too_loose = OsDefinition {
os: OsIdentity {
family: "Definitely Not Linux".to_string(),
vendor: None,
product: None,
version: None,
cpe: None,
},
provenance: Provenance::Published,
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(),
};
assert!(
rules::matches(&too_loose.r#match, &observed),
"a rule this loose must match a Linux example, or the cross-family check \
is incapable of catching one"
);
let mut elsewhere = match observed.clone() {
StackReply::Tcp(observed) => observed,
StackReply::Echo(_) => unreachable!("the example was chosen as a handshake"),
};
elsewhere.option_layout = vec![
TcpOptionKind::MaximumSegmentSize,
TcpOptionKind::Sack,
TcpOptionKind::Other(99),
];
let elsewhere = StackReply::Tcp(elsewhere);
let matched: Vec<&str> = RuleDb::global()
.matching(&elsewhere)
.map(|rule| rule.os.family.as_str())
.collect();
assert!(
matched.is_empty(),
"a shape nothing emits was matched by {matched:?}, so those rules are looser \
than the families they name"
);
}
#[test]
fn no_rule_names_a_real_address_or_host() {
let looks_like_ipv4 = |text: &str| {
text.split(|c: char| !(c.is_ascii_digit() || c == '.'))
.any(|token| {
let parts: Vec<&str> = token.split('.').collect();
parts.len() == 4
&& parts
.iter()
.all(|part| !part.is_empty() && part.parse::<u8>().is_ok())
})
};
let documentation_range = |text: &str| {
["192.0.2.", "198.51.100.", "203.0.113."]
.iter()
.any(|prefix| text.contains(prefix))
};
let mut offenders = Vec::new();
for rule in RuleDb::global().rules() {
for example in &rule.example {
let source = &example.source;
if looks_like_ipv4(source) && !documentation_range(source) {
offenders.push(format!("'{}': {source}", rule.os.family));
}
for suffix in [".local", ".lan", ".home", ".internal"] {
if source.contains(suffix) {
offenders.push(format!("'{}': {source}", rule.os.family));
}
}
}
}
assert!(
offenders.is_empty(),
"a published rule names somebody's network. Say what kind of machine was \
measured, not which one:\n{}",
offenders.join("\n")
);
}
#[test]
fn an_echo_reply_alone_can_name_a_family() {
let windows = echo_reply(128);
let verdict = super::verdict::classify(RuleDb::global(), &windows)
.expect("an echo reply with a Windows hop counter names Windows");
assert_eq!(verdict.family, "Windows");
let device = echo_reply(255);
let verdict = super::verdict::classify(RuleDb::global(), &device)
.expect("an echo reply with an infrastructure hop counter names one");
assert_eq!(verdict.family, "Network device");
}
#[test]
fn an_echo_reply_from_a_unix_hop_counter_names_nothing() {
let unix_like = echo_reply(64);
let matched: Vec<&str> = RuleDb::global()
.matching(&unix_like)
.map(|rule| rule.os.family.as_str())
.collect();
assert!(
matched.is_empty(),
"an echo reply with a hop counter of 64 was named {matched:?}, but Linux, \
macOS and the BSDs all start there and an echo reply carries nothing \
else to separate them"
);
}
fn echo_reply(hops: u8) -> StackReply {
StackReply::Echo(super::observation::EchoObservation {
ip: IpObservation::V4(Ipv4Observation {
ttl: hops,
identification: 0,
dont_fragment: true,
more_fragments: false,
dscp: 0,
ecn: 0,
}),
code: crate::protocols::icmp::ECHO_PROBE_CODE,
payload_len: 28,
payload_intact: true,
})
}