use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::path::Path;
pub const RULE_ID_SEPARATOR: char = '#';
pub const CORPUS_ROOT: &str = "assets/fingerprinting";
pub fn corpus_slug(path: &Path) -> Option<String> {
let root = Path::new(CORPUS_ROOT);
let relative = path.strip_prefix(root).ok()?;
let stem = relative.to_str()?.strip_suffix(".toml")?;
Some(stem.replace(std::path::MAIN_SEPARATOR, "/"))
}
pub fn rule_id(slug: &str, name: &str) -> String {
format!("{slug}{RULE_ID_SEPARATOR}{name}")
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RuleIdDefect {
Unnamed,
SeparatorInName(String),
Duplicate(String),
}
impl std::fmt::Display for RuleIdDefect {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Unnamed => write!(f, "states no name, so it cannot be identified or cited"),
Self::SeparatorInName(name) => write!(
f,
"is named '{name}', which contains the '{RULE_ID_SEPARATOR}' that separates a \
file from the rule inside it"
),
Self::Duplicate(name) => {
write!(
f,
"is named '{name}', which another rule in this file claimed"
)
}
}
}
}
pub fn claim_rule_id(
slug: &str,
name: Option<&str>,
seen: &mut std::collections::BTreeSet<String>,
) -> Result<String, RuleIdDefect> {
let name = name
.filter(|n| !n.is_empty())
.ok_or(RuleIdDefect::Unnamed)?;
if name.contains(RULE_ID_SEPARATOR) {
return Err(RuleIdDefect::SeparatorInName(name.to_string()));
}
if !seen.insert(name.to_string()) {
return Err(RuleIdDefect::Duplicate(name.to_string()));
}
Ok(rule_id(slug, name))
}
pub const MAX_COMPILED_REGEX_BYTES: usize = 32 * 1024 * 1024;
pub const MAX_UDP_PROBE_BYTES: usize = 512;
pub fn unescape(payload: &str) -> Vec<u8> {
let mut out = Vec::with_capacity(payload.len());
let mut chars = payload.chars();
while let Some(c) = chars.next() {
if c != '\\' {
out.extend_from_slice(c.encode_utf8(&mut [0u8; 4]).as_bytes());
continue;
}
match chars.next() {
Some('r') => out.push(b'\r'),
Some('n') => out.push(b'\n'),
Some('t') => out.push(b'\t'),
Some('0') => out.push(0),
Some('\\') => out.push(b'\\'),
Some('x') => {
let hi = chars.next().and_then(|h| h.to_digit(16));
let lo = chars.next().and_then(|l| l.to_digit(16));
match (hi, lo) {
(Some(hi), Some(lo)) => out.push((hi * 16 + lo) as u8),
_ => out.extend_from_slice(b"\\x"),
}
}
Some(other) => {
out.push(b'\\');
out.extend_from_slice(other.encode_utf8(&mut [0u8; 4]).as_bytes());
}
None => out.push(b'\\'),
}
}
out
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ServiceSignature {
pub name: String,
pub default_ports: Vec<u16>,
#[serde(default)]
pub shared_ports: Vec<u16>,
pub description: Option<String>,
pub attribution: Option<String>,
#[serde(default)]
pub speaks: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Probe {
pub name: Option<String>,
pub payload: String,
pub protocol: String,
#[serde(default)]
pub rarity: u8,
#[serde(default)]
pub generic: bool,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MatchRule {
pub name: Option<String>,
pub pattern: String,
pub version_group: Option<u8>,
pub vendor: Option<String>,
pub product: Option<String>,
pub context: Option<String>,
pub example: Option<String>,
pub metadata: Option<HashMap<String, String>>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ServiceDefinition {
pub service: ServiceSignature,
#[serde(default)]
pub probe: Vec<Probe>,
#[serde(default)]
pub r#match: Vec<MatchRule>,
}
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum DefinitionError {
Pattern {
rule: usize,
reason: String,
},
VersionGroup {
rule: usize,
group: u8,
available: usize,
},
ProbeProtocol {
probe: usize,
protocol: String,
},
GenericProbeNotTcp {
probe: usize,
protocol: String,
},
UdpProbeSize {
probe: usize,
bytes: usize,
},
}
impl std::fmt::Display for DefinitionError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
DefinitionError::Pattern { rule, reason } => {
write!(f, "match #{rule} has an unusable pattern: {reason}")
}
DefinitionError::VersionGroup {
rule,
group,
available,
} => write!(
f,
"match #{rule} references version_group {group}, but the pattern has \
{available} {}",
if *available == 1 {
"capture group"
} else {
"capture groups"
}
),
DefinitionError::ProbeProtocol { probe, protocol } => write!(
f,
"probe #{probe} has unknown protocol '{protocol}' (expected 'tcp' or 'udp')"
),
DefinitionError::GenericProbeNotTcp { probe, protocol } => write!(
f,
"probe #{probe} is marked generic over {protocol}; a generic probe is sent \
to every open port that registers none of its own, which only makes sense \
over TCP"
),
DefinitionError::UdpProbeSize { probe, bytes } if *bytes == 0 => write!(
f,
"udp probe #{probe} decodes to zero bytes; an empty datagram cannot elicit \
a reply"
),
DefinitionError::UdpProbeSize { probe, bytes } => write!(
f,
"udp probe #{probe} is {bytes} bytes, over the {MAX_UDP_PROBE_BYTES}-byte \
probe ceiling"
),
}
}
}
impl std::error::Error for DefinitionError {}
impl ServiceDefinition {
pub fn validate(&self) -> Result<(), DefinitionError> {
for (rule, r#match) in self.r#match.iter().enumerate() {
let compiled = super::pattern::compile(&r#match.pattern, MAX_COMPILED_REGEX_BYTES)
.map_err(|reason| DefinitionError::Pattern {
rule,
reason: reason.to_string(),
})?;
if let Some(group) = r#match.version_group
&& usize::from(group) >= compiled.captures_len()
{
return Err(DefinitionError::VersionGroup {
rule,
group,
available: compiled.captures_len() - 1,
});
}
}
for (probe, authored) in self.probe.iter().enumerate() {
if !matches!(authored.protocol.as_str(), "tcp" | "udp") {
return Err(DefinitionError::ProbeProtocol {
probe,
protocol: authored.protocol.clone(),
});
}
if authored.generic && authored.protocol != "tcp" {
return Err(DefinitionError::GenericProbeNotTcp {
probe,
protocol: authored.protocol.clone(),
});
}
if authored.protocol == "udp" {
let bytes = unescape(&authored.payload).len();
if bytes == 0 || bytes > MAX_UDP_PROBE_BYTES {
return Err(DefinitionError::UdpProbeSize { probe, bytes });
}
}
}
Ok(())
}
}
#[cfg(test)]
mod identity {
use super::*;
use std::collections::BTreeSet;
#[test]
fn a_corpus_path_becomes_the_slug_an_identifier_is_written_from() {
assert_eq!(
corpus_slug(Path::new("assets/fingerprinting/remote/ssh.toml")).as_deref(),
Some("remote/ssh")
);
assert_eq!(
corpus_slug(Path::new(
"assets/fingerprinting/imported/rapid7/dns/dns_versionbind.toml"
))
.as_deref(),
Some("imported/rapid7/dns/dns_versionbind")
);
}
#[test]
fn a_path_outside_the_corpus_has_no_slug() {
assert_eq!(corpus_slug(Path::new("src/fingerprint/signature.rs")), None);
assert_eq!(
corpus_slug(Path::new("assets/detect/database/redis-unauth.toml")),
None
);
assert_eq!(corpus_slug(Path::new("remote/ssh.toml")), None);
}
#[test]
fn a_name_carrying_a_colon_still_yields_a_splittable_identifier() {
let id = rule_id("imported/rapid7/dns/dns_versionbind", "ISC BIND: Ubuntu");
let (slug, name) = id.split_once(RULE_ID_SEPARATOR).expect("one separator");
assert_eq!(slug, "imported/rapid7/dns/dns_versionbind");
assert_eq!(name, "ISC BIND: Ubuntu");
}
#[test]
fn a_name_claimed_twice_in_one_file_is_refused() {
let mut seen = BTreeSet::new();
assert!(claim_rule_id("remote/ssh", Some("openssh_match"), &mut seen).is_ok());
assert_eq!(
claim_rule_id("remote/ssh", Some("openssh_match"), &mut seen),
Err(RuleIdDefect::Duplicate("openssh_match".to_string()))
);
}
#[test]
fn the_same_name_in_two_files_is_two_identifiers() {
let mut ssh = BTreeSet::new();
let mut ftp = BTreeSet::new();
let a = claim_rule_id("remote/ssh", Some("banner"), &mut ssh).expect("first file");
let b = claim_rule_id("file_transfer/ftp", Some("banner"), &mut ftp).expect("second file");
assert_ne!(a, b);
}
#[test]
fn an_unnamed_or_empty_rule_cannot_be_identified() {
let mut seen = BTreeSet::new();
assert_eq!(
claim_rule_id("remote/ssh", None, &mut seen),
Err(RuleIdDefect::Unnamed)
);
assert_eq!(
claim_rule_id("remote/ssh", Some(""), &mut seen),
Err(RuleIdDefect::Unnamed)
);
}
#[test]
fn a_name_carrying_the_separator_is_refused() {
let mut seen = BTreeSet::new();
assert_eq!(
claim_rule_id("remote/ssh", Some("a#b"), &mut seen),
Err(RuleIdDefect::SeparatorInName("a#b".to_string()))
);
}
}