use std::sync::OnceLock;
use super::observation::StackReply;
use super::rules;
use super::signature::{OsDefinition, RuleError};
const EMBEDDED_RULES: &[u8] = include_bytes!(concat!(env!("OUT_DIR"), "/os_rules.bin"));
static DB: OnceLock<RuleDb> = OnceLock::new();
#[derive(Debug, Clone, PartialEq)]
pub struct InvalidRule {
pub index: usize,
pub identity: String,
pub error: RuleError,
}
impl std::fmt::Display for InvalidRule {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let Self {
index,
identity,
error,
} = self;
write!(f, "rule {index} ('{identity}') {error}")
}
}
impl std::error::Error for InvalidRule {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
Some(&self.error)
}
}
#[derive(Debug)]
pub struct RuleDb {
rules: Vec<OsDefinition>,
}
impl RuleDb {
pub fn global() -> &'static RuleDb {
DB.get_or_init(|| {
let rules: Vec<OsDefinition> = bincode::deserialize(EMBEDDED_RULES)
.expect("the embedded OS rule database failed to deserialize");
RuleDb { rules }
})
}
pub fn try_from_rules(rules: Vec<OsDefinition>) -> Result<Self, InvalidRule> {
for (index, rule) in rules.iter().enumerate() {
rule.validate().map_err(|error| InvalidRule {
index,
identity: rule.os.label().to_owned(),
error,
})?;
}
Ok(Self { rules })
}
pub fn from_rules_unchecked(rules: Vec<OsDefinition>) -> Self {
Self { rules }
}
pub fn rules(&self) -> &[OsDefinition] {
&self.rules
}
pub fn matching<'a>(&'a self, reply: &'a StackReply) -> impl Iterator<Item = &'a OsDefinition> {
rules::matching(&self.rules, reply, None)
}
pub fn matching_with_series<'a>(
&'a self,
reply: &'a StackReply,
series: &'a super::series::SeriesClasses,
) -> impl Iterator<Item = &'a OsDefinition> {
rules::matching(&self.rules, reply, Some(series))
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::fingerprint::os::{
MatchRule, OsIdentity, Predicate, PredicateDefect, Provenance, ReplyKind, RuleError,
};
fn identity(family: &str) -> OsIdentity {
OsIdentity {
family: Some(family.to_owned()),
device: None,
vendor: None,
product: None,
version: None,
cpe: None,
}
}
fn rule(family: &str, r#match: MatchRule) -> OsDefinition {
OsDefinition {
os: identity(family),
provenance: Provenance::Measured,
notes: None,
weight: 1.0,
r#match,
example: Vec::new(),
}
}
fn tests_something() -> MatchRule {
MatchRule {
reply: ReplyKind::SynAck,
initial_hops: Some(Predicate {
equals: Some(64),
any_of: None,
range: None,
}),
..Default::default()
}
}
#[test]
fn a_rule_that_tests_nothing_is_refused() {
let refused = RuleDb::try_from_rules(vec![rule("Windows 3.1", MatchRule::default())])
.expect_err("a rule matching everything is not loadable");
assert_eq!(refused.error, RuleError::NoPredicates);
assert_eq!(refused.index, 0);
assert_eq!(refused.identity, "Windows 3.1");
}
#[test]
fn the_checks_are_the_ones_the_build_makes() {
let cases: Vec<(OsDefinition, RuleError)> = vec![
(
OsDefinition {
os: OsIdentity {
family: None,
device: None,
..identity("ignored")
},
..rule("ignored", tests_something())
},
RuleError::Unidentified,
),
(
OsDefinition {
os: OsIdentity {
version: Some("22.04".to_owned()),
..identity("Linux")
},
..rule("Linux", tests_something())
},
RuleError::VersionWithoutProduct,
),
(
OsDefinition {
weight: 1e9,
..rule("Linux", tests_something())
},
RuleError::Weight(1e9),
),
(
rule(
"Linux",
MatchRule {
reply: ReplyKind::SynAck,
initial_hops: Some(Predicate {
equals: None,
any_of: None,
range: None,
}),
..Default::default()
},
),
RuleError::Predicate {
field: "initial_hops",
defect: PredicateDefect::NoForm,
},
),
(
rule(
"Linux",
MatchRule {
reply: ReplyKind::SynAck,
initial_hops: Some(Predicate {
equals: None,
any_of: Some(Vec::new()),
range: None,
}),
..Default::default()
},
),
RuleError::Predicate {
field: "initial_hops",
defect: PredicateDefect::EmptyAnyOf,
},
),
(
rule(
"Linux",
MatchRule {
reply: ReplyKind::SynAck,
initial_hops: Some(Predicate {
equals: None,
any_of: None,
range: Some([128, 64]),
}),
..Default::default()
},
),
RuleError::Predicate {
field: "initial_hops",
defect: PredicateDefect::BackwardsRange,
},
),
];
for (definition, expected) in cases {
let refused = RuleDb::try_from_rules(vec![definition])
.expect_err("the build would refuse this too");
assert_eq!(refused.error, expected);
}
}
#[test]
fn a_series_rule_without_a_series_example_is_refused() {
use crate::fingerprint::os::Example;
let series_rule = MatchRule {
reply: ReplyKind::SynAck,
initial_hops: Some(Predicate {
equals: Some(64),
any_of: None,
range: None,
}),
sequence_class: Some(Predicate {
equals: Some("hashed".to_owned()),
any_of: None,
range: None,
}),
..Default::default()
};
let single_reply = Example {
source: "one reply, no series".to_owned(),
reply: ReplyKind::SynAck,
remaining_hops: 64,
dont_fragment: true,
option_layout: "M".to_owned(),
window: Some(64_240),
mss: Some(1460),
window_scale: None,
timestamps: false,
sack_permitted: false,
echo_code: 0,
echo_payload_intact: true,
identifier_class: None,
sequence_class: None,
clock_class: None,
};
let mut definition = rule("Linux", series_rule);
definition.example = vec![single_reply.clone()];
let refused = RuleDb::try_from_rules(vec![definition.clone()])
.expect_err("nothing could check this rule");
assert!(matches!(refused.error, RuleError::ExampleWithoutSeries(_)));
definition.example = vec![Example {
sequence_class: Some("hashed".to_owned()),
..single_reply
}];
assert!(RuleDb::try_from_rules(vec![definition]).is_ok());
}
#[test]
fn a_well_formed_rule_loads() {
let db = RuleDb::try_from_rules(vec![rule("Linux", tests_something())])
.expect("a rule with a predicate and an identity");
assert_eq!(db.rules().len(), 1);
}
#[test]
fn every_shipped_rule_satisfies_the_shared_check() {
for (index, rule) in RuleDb::global().rules().iter().enumerate() {
assert!(
rule.validate().is_ok(),
"shipped rule {index} ('{}') would be refused: {:?}",
rule.os.label(),
rule.validate()
);
}
}
#[test]
fn the_unchecked_constructor_is_the_one_that_skips_the_checks() {
let db = RuleDb::from_rules_unchecked(vec![rule("Windows 3.1", MatchRule::default())]);
assert_eq!(db.rules().len(), 1);
}
#[test]
fn the_refusal_names_which_rule_and_why() {
let refused = RuleDb::try_from_rules(vec![
rule("Linux", tests_something()),
rule("Windows 3.1", MatchRule::default()),
])
.expect_err("the second rule is unusable");
let message = refused.to_string();
assert!(message.contains("rule 1"), "{message}");
assert!(message.contains("Windows 3.1"), "{message}");
assert!(message.contains("every reply of its kind"), "{message}");
}
}