#![allow(dead_code)]
use std::collections::BTreeSet;
use std::fmt;
use super::expr::{self, ParseError};
use super::manifest::Class;
use super::schema::{FindingSpec, FlowDetection, MAX_FLOW_STEPS, MAX_LOOP_ITEMS, Step};
pub const RESERVED_ID_PREFIX: &str = "zond:";
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ValidationError {
TooManySteps(usize),
EmptyLoop(usize),
LoopTooLong(usize, usize),
LoopVarShadows(usize, String),
UnknownProtocol(String),
PassiveDoes(&'static str),
SendWithoutSpeak,
UndefinedVariable(usize, String, &'static str),
MatchedInStepGuard(usize),
MatchedWithoutExpect(usize),
GuardParseError(usize, &'static str, ParseError),
NoFindings,
MalformedVersion(String),
EmptyId,
EmptyTitle,
ReservedId(String),
ExpectWithoutSend(usize),
}
impl fmt::Display for ValidationError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
ValidationError::TooManySteps(count) => {
write!(
f,
"has {count} steps, over the {MAX_FLOW_STEPS}-step ceiling"
)
}
ValidationError::EmptyLoop(step) => {
write!(f, "step {step} loops over an empty list, so it never runs")
}
ValidationError::LoopTooLong(step, count) => write!(
f,
"step {step} loops over {count} items, over the {MAX_LOOP_ITEMS}-item cap"
),
ValidationError::LoopVarShadows(step, var) => write!(
f,
"step {step} binds loop variable `{var}`, which an earlier step already bound"
),
ValidationError::UnknownProtocol(protocol) => {
write!(
f,
"names protocol `{protocol}`, which is neither tcp nor udp"
)
}
ValidationError::PassiveDoes(what) => {
write!(f, "is passive but declares {what}, which is active")
}
ValidationError::SendWithoutSpeak => {
write!(f, "sends bytes but was granted no `speak` capability")
}
ValidationError::UndefinedVariable(step, var, place) => write!(
f,
"step {step} reads variable `{var}` in {place}, which no earlier step binds"
),
ValidationError::MatchedInStepGuard(step) => write!(
f,
"step {step}'s own guard reads `matched`, but nothing has matched when a step is gated"
),
ValidationError::MatchedWithoutExpect(step) => write!(
f,
"step {step} has a finding guarded on `matched` but no `expect` to match against"
),
ValidationError::GuardParseError(step, place, error) => {
write!(f, "step {step}'s {place} is not a valid guard: {error}")
}
ValidationError::NoFindings => {
write!(f, "declares no finding, so it can conclude nothing")
}
ValidationError::MalformedVersion(version) => {
write!(f, "has version `{version}`, not a major.minor.patch triple")
}
ValidationError::EmptyId => write!(f, "has an empty id"),
ValidationError::EmptyTitle => write!(f, "has an empty title"),
ValidationError::ReservedId(id) => {
write!(
f,
"id `{id}` claims the reserved `{RESERVED_ID_PREFIX}` namespace"
)
}
ValidationError::ExpectWithoutSend(step) => write!(
f,
"step {step} has an `expect` but no `send`, so nothing is drawn for it to match"
),
}
}
}
pub fn check(flow: &FlowDetection) -> Vec<ValidationError> {
let mut errors = Vec::new();
check_identity(flow, &mut errors);
check_capabilities(flow, &mut errors);
check_protocol(flow, &mut errors);
if flow.step.len() > MAX_FLOW_STEPS {
errors.push(ValidationError::TooManySteps(flow.step.len()));
}
if flow.step.iter().all(|step| step.finding.is_empty()) {
errors.push(ValidationError::NoFindings);
}
for (index, step) in flow.step.iter().enumerate() {
if !step.expect.is_empty() && step.send.is_none() {
errors.push(ValidationError::ExpectWithoutSend(index));
}
}
check_references(flow, &mut errors);
errors
}
fn check_identity(flow: &FlowDetection, errors: &mut Vec<ValidationError>) {
let id = &flow.detection.id;
if id.trim().is_empty() {
errors.push(ValidationError::EmptyId);
} else if id.starts_with(RESERVED_ID_PREFIX) {
errors.push(ValidationError::ReservedId(id.clone()));
}
if flow.detection.title.trim().is_empty() {
errors.push(ValidationError::EmptyTitle);
}
if !is_version_triple(&flow.detection.version) {
errors.push(ValidationError::MalformedVersion(
flow.detection.version.clone(),
));
}
}
fn check_capabilities(flow: &FlowDetection, errors: &mut Vec<ValidationError>) {
let caps = &flow.detection.capabilities;
let has_send = flow.step.iter().any(|step| step.send.is_some());
let has_for_each = flow.step.iter().any(|step| step.for_each.is_some());
if caps.class == Class::Passive {
if caps.speak.is_some() {
errors.push(ValidationError::PassiveDoes("speak"));
}
if caps.resolve {
errors.push(ValidationError::PassiveDoes("resolve"));
}
if has_send {
errors.push(ValidationError::PassiveDoes("a step that sends"));
}
if has_for_each {
errors.push(ValidationError::PassiveDoes("a for_each step"));
}
} else if has_send && caps.speak.is_none() {
errors.push(ValidationError::SendWithoutSpeak);
}
}
fn check_protocol(flow: &FlowDetection, errors: &mut Vec<ValidationError>) {
if let Some(protocol) = &flow.detection.when.protocol
&& protocol != "tcp"
&& protocol != "udp"
{
errors.push(ValidationError::UnknownProtocol(protocol.clone()));
}
}
fn check_references(flow: &FlowDetection, errors: &mut Vec<ValidationError>) {
let mut persisted: BTreeSet<String> = super::schema::SEED_VARS
.iter()
.map(|v| v.to_string())
.collect();
for (index, step) in flow.step.iter().enumerate() {
let loop_var = check_loop(index, step, &persisted, errors);
let mut gate_scope = persisted.clone();
gate_scope.extend(loop_var.clone());
check_step_guard(index, step, &gate_scope, errors);
if let Some(send) = &step.send {
check_template(index, send, "a send", &gate_scope, errors);
}
let mut finding_scope = gate_scope;
finding_scope.extend(step.bind.keys().cloned());
for finding in &step.finding {
check_finding(index, step, finding, &finding_scope, errors);
}
if step.for_each.is_none() {
persisted.extend(step.bind.keys().cloned());
}
}
}
fn check_loop(
index: usize,
step: &Step,
persisted: &BTreeSet<String>,
errors: &mut Vec<ValidationError>,
) -> Option<String> {
let for_each = step.for_each.as_ref()?;
if for_each.items.is_empty() {
errors.push(ValidationError::EmptyLoop(index));
}
if for_each.items.len() > MAX_LOOP_ITEMS {
errors.push(ValidationError::LoopTooLong(index, for_each.items.len()));
}
if persisted.contains(&for_each.var) || step.bind.contains_key(&for_each.var) {
errors.push(ValidationError::LoopVarShadows(index, for_each.var.clone()));
}
Some(for_each.var.clone())
}
fn check_step_guard(
index: usize,
step: &Step,
scope: &BTreeSet<String>,
errors: &mut Vec<ValidationError>,
) {
let Some(when) = &step.when else { return };
match expr::parse(when) {
Err(error) => errors.push(ValidationError::GuardParseError(index, "guard", error)),
Ok(guard) => {
if guard.uses_matched() {
errors.push(ValidationError::MatchedInStepGuard(index));
}
for var in guard.referenced_vars() {
if !scope.contains(&var) {
errors.push(ValidationError::UndefinedVariable(index, var, "its guard"));
}
}
}
}
}
fn check_finding(
index: usize,
step: &Step,
finding: &FindingSpec,
scope: &BTreeSet<String>,
errors: &mut Vec<ValidationError>,
) {
if let Some(when) = &finding.when {
match expr::parse(when) {
Err(error) => errors.push(ValidationError::GuardParseError(
index,
"finding guard",
error,
)),
Ok(guard) => {
if guard.uses_matched() && step.expect.is_empty() {
errors.push(ValidationError::MatchedWithoutExpect(index));
}
for var in guard.referenced_vars() {
if !scope.contains(&var) {
errors.push(ValidationError::UndefinedVariable(
index,
var,
"a finding guard",
));
}
}
}
}
}
check_template(index, &finding.summary, "a finding summary", scope, errors);
if let Some(title) = &finding.title {
check_template(index, title, "a finding title", scope, errors);
}
if let Some(detail) = &finding.detail {
check_template(index, detail, "a finding detail", scope, errors);
}
if let Some(source) = &finding.excerpt_from
&& source != "$response"
&& !scope.contains(source)
{
errors.push(ValidationError::UndefinedVariable(
index,
source.clone(),
"a finding excerpt_from",
));
}
}
fn check_template(
index: usize,
template: &str,
place: &'static str,
scope: &BTreeSet<String>,
errors: &mut Vec<ValidationError>,
) {
for var in template_vars(template) {
if !scope.contains(&var) {
errors.push(ValidationError::UndefinedVariable(index, var, place));
}
}
}
fn template_vars(template: &str) -> Vec<String> {
let mut vars = Vec::new();
let mut rest = template;
while let Some(brace) = rest.find(['{', '}']) {
let this = rest.as_bytes()[brace];
let after = &rest[brace + 1..];
if after.as_bytes().first() == Some(&this) {
rest = &after[1..];
} else if this == b'{' {
let Some(close) = after.find('}') else { break };
vars.push(after[..close].to_string());
rest = &after[close + 1..];
} else {
rest = after;
}
}
vars
}
pub fn is_version_triple(version: &str) -> bool {
let parts: Vec<&str> = version.split('.').collect();
parts.len() == 3 && parts.iter().all(|part| part.parse::<u16>().is_ok())
}
#[cfg(test)]
mod tests {
use super::*;
use crate::detect::flow::schema::FlowDetection;
fn flow(toml: &str) -> FlowDetection {
toml::from_str(toml).expect("the test flow parses")
}
fn sound() -> FlowDetection {
flow(
r#"
[detection]
id = "example"
version = "1.0.0"
title = "Example"
[detection.when]
service = "http"
protocol = "tcp"
[detection.capabilities]
class = "active-benign"
speak = "target"
[[step]]
send = "GET / HTTP/1.0\r\n\r\n"
expect = "Server:"
bind = { version = "Server: nginx/(?<version>[0-9.]+)" }
[[step.finding]]
when = "matched"
severity = "medium"
summary = "nginx {version}"
"#,
)
}
#[test]
fn a_sound_flow_has_no_errors() {
assert!(check(&sound()).is_empty(), "{:?}", check(&sound()));
}
#[test]
fn every_shipped_flow_validates() {
let shipped = crate::detect::flow::db::embedded_flows();
assert!(!shipped.is_empty(), "the corpus ships no flows at all");
for compiled in &shipped {
let errors = check(compiled.flow());
assert!(
errors.is_empty(),
"{}: {errors:?}",
compiled.flow().detection.id
);
}
}
#[test]
fn a_guard_naming_a_later_bound_variable_is_a_forward_reference() {
let flow = flow(
r#"
[detection]
id = "x"
version = "1.0.0"
title = "x"
[detection.when]
protocol = "tcp"
[detection.capabilities]
class = "active-benign"
speak = "target"
[[step]]
when = "bound(version)"
send = "a"
[[step.finding]]
severity = "low"
summary = "found"
[[step]]
send = "b"
bind = { version = "v(?<version>[0-9]+)" }
"#,
);
assert!(
check(&flow).iter().any(
|e| matches!(e, ValidationError::UndefinedVariable(0, v, _) if v == "version")
),
"{:?}",
check(&flow)
);
}
#[test]
fn a_template_naming_an_unbound_variable_is_caught() {
let mut flow = sound();
flow.step[0].finding[0].summary = "version {nope}".to_string();
assert!(
check(&flow)
.iter()
.any(|e| matches!(e, ValidationError::UndefinedVariable(0, v, _) if v == "nope"))
);
}
#[test]
fn the_seed_variables_are_in_scope_from_the_first_step() {
let flow = flow(
r#"
[detection]
id = "seed"
version = "1.0.0"
title = "seed"
[detection.when]
speaks = "http"
[detection.capabilities]
class = "active-benign"
speak = "target"
[[step]]
send = "HEAD / HTTP/1.1\r\nHost: {host}\r\n\r\n"
expect = "HTTP/"
[[step.finding]]
when = "matched"
severity = "info"
summary = "port {port} answered on {host}"
"#,
);
assert!(
check(&flow).is_empty(),
"a flow naming the seed variables was rejected: {:?}",
check(&flow)
);
}
#[test]
fn matched_in_a_step_guard_is_rejected() {
let mut flow = sound();
flow.step[0].when = Some("matched".to_string());
assert!(check(&flow).contains(&ValidationError::MatchedInStepGuard(0)));
}
#[test]
fn an_unparseable_guard_is_reported_not_silently_unmet() {
let mut flow = sound();
flow.step[0].finding[0].when = Some("bound(".to_string());
assert!(
check(&flow)
.iter()
.any(|e| matches!(e, ValidationError::GuardParseError(0, "finding guard", _)))
);
}
#[test]
fn a_passive_flow_that_sends_is_rejected() {
let flow = flow(
r#"
[detection]
id = "x"
version = "1.0.0"
title = "x"
[detection.when]
protocol = "tcp"
[detection.capabilities]
class = "passive"
speak = "target"
[[step]]
send = "probe"
expect = "ok"
[[step.finding]]
when = "matched"
severity = "low"
summary = "hit"
"#,
);
let errors = check(&flow);
assert!(errors.contains(&ValidationError::PassiveDoes("speak")));
assert!(errors.contains(&ValidationError::PassiveDoes("a step that sends")));
}
#[test]
fn a_send_without_speak_is_rejected() {
let mut flow = sound();
flow.detection.capabilities.speak = None;
assert!(check(&flow).contains(&ValidationError::SendWithoutSpeak));
}
#[test]
fn an_expect_without_a_send_is_dead_and_rejected() {
let mut flow = sound();
flow.step[0].send = None;
assert!(
check(&flow)
.iter()
.any(|e| matches!(e, ValidationError::ExpectWithoutSend(0))),
"{:?}",
check(&flow)
);
}
#[test]
fn an_empty_and_an_oversized_loop_are_both_rejected() {
let mut flow = sound();
flow.step[0].for_each = Some(crate::detect::flow::schema::ForEach {
var: "item".to_string(),
items: vec![],
});
assert!(check(&flow).contains(&ValidationError::EmptyLoop(0)));
flow.step[0].for_each = Some(crate::detect::flow::schema::ForEach {
var: "item".to_string(),
items: vec!["x".to_string(); MAX_LOOP_ITEMS + 1],
});
assert!(
check(&flow)
.iter()
.any(|e| matches!(e, ValidationError::LoopTooLong(0, _)))
);
}
#[test]
fn a_flow_with_no_finding_is_dead() {
let mut flow = sound();
flow.step[0].finding.clear();
assert!(check(&flow).contains(&ValidationError::NoFindings));
}
#[test]
fn a_malformed_version_empty_id_and_reserved_id_are_caught() {
let mut flow = sound();
flow.detection.version = "1.0".to_string();
assert!(
check(&flow)
.iter()
.any(|e| matches!(e, ValidationError::MalformedVersion(_)))
);
let mut flow = sound();
flow.detection.id = " ".to_string();
assert!(check(&flow).contains(&ValidationError::EmptyId));
let mut flow = sound();
flow.detection.id = "zond:cve-kev".to_string();
assert!(
check(&flow)
.iter()
.any(|e| matches!(e, ValidationError::ReservedId(_)))
);
}
#[test]
fn an_unknown_protocol_is_rejected() {
let mut flow = sound();
flow.detection.when.protocol = Some("sctp".to_string());
assert!(
check(&flow)
.iter()
.any(|e| matches!(e, ValidationError::UnknownProtocol(p) if p == "sctp"))
);
}
#[test]
fn a_loop_variable_shadowing_an_earlier_bind_is_rejected() {
let flow = flow(
r#"
[detection]
id = "x"
version = "1.0.0"
title = "x"
[detection.when]
protocol = "udp"
[detection.capabilities]
class = "active-benign"
speak = "target"
[[step]]
send = "a"
bind = { host = "(?<host>.+)" }
[[step]]
for_each = { var = "host", in = ["1", "2"] }
send = "b {host}"
expect = "ok"
[[step.finding]]
when = "matched"
severity = "low"
summary = "hit {host}"
"#,
);
assert!(
check(&flow)
.iter()
.any(|e| matches!(e, ValidationError::LoopVarShadows(1, v) if v == "host"))
);
}
#[test]
fn template_vars_reads_names_and_skips_escaped_braces() {
assert_eq!(template_vars("{host}:{port}"), vec!["host", "port"]);
assert_eq!(template_vars(r#"{{"key":"{host}"}}"#), vec!["host"]);
assert!(template_vars(r#"{{"key":"value"}}"#).is_empty());
assert_eq!(template_vars("a}b {host}"), vec!["host"]);
}
}