#![allow(dead_code)]
use crate::config::DetectionEnvelope;
use crate::model::finding::Finding;
use crate::model::host::Host;
use crate::model::port::{Port, PortState, Protocol};
use std::collections::HashMap;
use std::sync::Mutex;
use std::sync::atomic::{AtomicU32, AtomicUsize, Ordering};
use std::time::{Duration, Instant};
use super::db::FlowDb;
use super::{FlowSeed, Probe, ProbeRefusal};
use crate::config::limits::DETECTION_FLOW_CONCURRENCY;
use crate::detect::manifest::{CapabilitySpec, Class, DEFAULT_MAX_BYTES, DEFAULT_MAX_MILLIS};
pub(crate) fn run_flows(
host: &mut Host,
corpus: &FlowDb,
envelope: &DetectionEnvelope,
probe_for: impl Fn(&Port) -> Option<Box<dyn Probe>> + Sync,
) {
let host_addr = host.scoped_ip().addr().to_string();
let mut hits: Vec<(u16, Protocol, Finding)> = Vec::new();
for port in host.ports() {
if port.state() != PortState::Open {
continue;
}
let number = port.number();
let protocol = port.protocol();
let service = port.service().map(|service| service.name());
let (produced, _refusals) = detect_port(
corpus,
envelope,
&host_addr,
service,
number,
protocol,
|_caps| probe_for(port),
);
for finding in produced {
hits.push((number, protocol, finding));
}
}
for (number, protocol, finding) in hits {
host.add_port_finding(number, protocol, finding);
}
}
pub(crate) fn detect_port(
corpus: &FlowDb,
envelope: &DetectionEnvelope,
host: &str,
service: Option<&str>,
number: u16,
protocol: Protocol,
probe_for: impl Fn(&CapabilitySpec) -> Option<Box<dyn Probe>> + Sync,
) -> (Vec<Finding>, Vec<(String, ProbeRefusal)>) {
let applicable: Vec<_> = corpus
.flows()
.filter(|flow| {
let manifest = &flow.flow().detection;
enabled(manifest.capabilities.class, envelope)
&& manifest.when.applies(service, number, protocol)
})
.collect();
if applicable.is_empty() {
return (Vec::new(), Vec::new());
}
let seed = FlowSeed::new(host, number);
let cache = Mutex::new(HashMap::new());
let strikes = AtomicU32::new(0);
let run_one = |index: usize| -> Option<Run> {
let flow = applicable[index];
let manifest = &flow.flow().detection;
let inner = probe_for(&manifest.capabilities)?;
let millis = manifest
.capabilities
.max_millis
.map_or(DEFAULT_MAX_MILLIS, u64::from);
let mut probe = CachingProbe {
inner,
cache: &cache,
strikes: &strikes,
stalled: false,
dead_after: Duration::from_millis(millis / 4 * 3),
budget: manifest
.capabilities
.max_bytes
.map_or(DEFAULT_MAX_BYTES, u64::from),
};
let found = flow.run(&seed, &mut probe);
let refusal = probe
.last_refusal()
.map(|refusal| (manifest.id.clone(), refusal));
Some(Run {
index,
findings: found,
refusal,
})
};
let mut runs: Vec<Run> = Vec::with_capacity(applicable.len());
runs.extend(run_one(0));
let widen = strikes.load(Ordering::Relaxed) == 0;
let width = if widen {
DETECTION_FLOW_CONCURRENCY.min(applicable.len() - 1)
} else {
1
};
if width <= 1 {
runs.extend((1..applicable.len()).filter_map(&run_one));
} else {
let next = AtomicUsize::new(1);
let done: Mutex<Vec<Run>> = Mutex::new(Vec::with_capacity(applicable.len()));
std::thread::scope(|scope| {
for _ in 0..width {
scope.spawn(|| {
loop {
if strikes.load(Ordering::Relaxed) >= DEAD_PORT_STRIKES {
break;
}
let index = next.fetch_add(1, Ordering::Relaxed);
if index >= applicable.len() {
break;
}
if let Some(run) = run_one(index) {
done.lock()
.unwrap_or_else(|held| held.into_inner())
.push(run);
}
}
});
}
});
runs.extend(done.into_inner().unwrap_or_else(|held| held.into_inner()));
}
runs.sort_by_key(|run| run.index);
let mut findings = Vec::new();
let mut refusals = Vec::new();
for run in runs {
findings.extend(run.findings);
refusals.extend(run.refusal);
}
(findings, refusals)
}
struct Run {
index: usize,
findings: Vec<Finding>,
refusal: Option<(String, ProbeRefusal)>,
}
struct CachingProbe<'a> {
inner: Box<dyn Probe>,
cache: &'a Mutex<HashMap<Vec<u8>, Vec<u8>>>,
strikes: &'a AtomicU32,
dead_after: Duration,
stalled: bool,
budget: u64,
}
const DEAD_PORT_STRIKES: u32 = 2;
impl Probe for CachingProbe<'_> {
fn speak(&mut self, bytes: &[u8]) -> Option<Vec<u8>> {
{
let cache = self.cache.lock().unwrap_or_else(|held| held.into_inner());
if let Some(reply) = cache.get(bytes)
&& reply.len() as u64 <= self.budget
{
return Some(reply.clone());
}
}
if self.strikes.load(Ordering::Relaxed) >= DEAD_PORT_STRIKES {
return None;
}
let started = Instant::now();
let reply = self.inner.speak(bytes);
if started.elapsed() >= self.dead_after {
self.strikes.fetch_add(1, Ordering::Relaxed);
self.stalled = true;
}
let reply = reply?;
if self.inner.reply_complete() {
self.cache
.lock()
.unwrap_or_else(|held| held.into_inner())
.entry(bytes.to_vec())
.or_insert_with(|| reply.clone());
}
Some(reply)
}
fn reply_complete(&self) -> bool {
self.inner.reply_complete()
}
fn last_refusal(&self) -> Option<ProbeRefusal> {
if self.stalled {
return None;
}
self.inner.last_refusal()
}
}
pub(crate) fn interested(
corpus: &FlowDb,
envelope: &DetectionEnvelope,
service: Option<&str>,
number: u16,
protocol: Protocol,
) -> bool {
corpus.flows().any(|flow| {
let manifest = &flow.flow().detection;
enabled(manifest.capabilities.class, envelope)
&& manifest.when.applies(service, number, protocol)
})
}
fn enabled(class: Class, envelope: &DetectionEnvelope) -> bool {
envelope.permits(class.into_model())
}
#[cfg(test)]
mod tests {
use super::*;
use crate::model::finding::DetectionClass;
use crate::model::port::Service;
use std::net::{IpAddr, Ipv4Addr};
fn default_envelope() -> DetectionEnvelope {
DetectionEnvelope::default()
}
fn benign_envelope() -> DetectionEnvelope {
DetectionEnvelope::up_to(Class::ActiveBenign.into_model())
}
struct Canned(&'static [u8]);
impl Probe for Canned {
fn speak(&mut self, _bytes: &[u8]) -> Option<Vec<u8>> {
Some(self.0.to_vec())
}
}
fn host_with(port: Port) -> Host {
let mut host = Host::new(IpAddr::V4(Ipv4Addr::new(192, 0, 2, 1)));
host.add_port(port);
host
}
fn open(number: u16, protocol: Protocol, service: &str) -> Port {
Port::new(number, protocol, PortState::Open).with_service(Service::new(service, 100))
}
#[test]
fn a_matching_flow_runs_and_records_its_finding_on_the_port() {
let mut host = host_with(open(6379, Protocol::Tcp, "redis"));
run_flows(&mut host, FlowDb::global(), &benign_envelope(), |_port| {
Some(Box::new(Canned(b"# Server\r\nredis_version:7.2.4")))
});
let port = host.ports().find(|port| port.number() == 6379).unwrap();
let findings: Vec<_> = port.findings().collect();
assert_eq!(findings.len(), 1, "the redis flow fired");
assert_eq!(findings[0].detection().id(), "redis-unauth-access");
assert_eq!(findings[0].detection().content_hash().len(), 64);
}
#[test]
fn the_envelope_decides_which_classes_run() {
let default = default_envelope();
assert!(enabled(Class::Passive, &default));
assert!(!enabled(Class::ActiveBenign, &default));
assert!(!enabled(Class::ActiveMutating, &default));
assert!(!enabled(Class::Exploit, &default));
assert!(!enabled(Class::Dos, &default));
let permissive = DetectionEnvelope::up_to(DetectionClass::Exploit);
assert!(enabled(Class::Exploit, &permissive));
}
#[test]
fn a_flow_is_skipped_when_its_gate_or_the_port_does_not_fit() {
let mut http = host_with(open(6379, Protocol::Tcp, "http"));
run_flows(&mut http, FlowDb::global(), &benign_envelope(), |_| {
Some(Box::new(Canned(b"# Server\r\nredis_version:7.2.4")))
});
let port = http.ports().find(|port| port.number() == 6379).unwrap();
assert_eq!(port.findings().count(), 0, "the service gate did not match");
let mut closed = host_with(
Port::new(6379, Protocol::Tcp, PortState::Closed)
.with_service(Service::new("redis", 100)),
);
run_flows(&mut closed, FlowDb::global(), &benign_envelope(), |_| {
Some(Box::new(Canned(b"# Server\r\nredis_version:7.2.4")))
});
let port = closed.ports().find(|port| port.number() == 6379).unwrap();
assert_eq!(port.findings().count(), 0, "a closed port was probed");
}
#[test]
fn an_intrusive_flow_does_not_run_under_the_default_policy() {
use crate::detect::flow::db::CompiledFlow;
use crate::detect::flow::schema::FlowDetection;
let source = r#"
[detection]
id = "dangerous"
version = "1.0.0"
title = "Dangerous"
[detection.when]
service = "redis"
[detection.capabilities]
class = "exploit"
speak = "target"
[[step]]
send = "ATTACK"
expect = "ok"
[[step.finding]]
when = "matched"
severity = "critical"
summary = "the exploit fired"
"#;
let flow: FlowDetection = toml::from_str(source).expect("a valid flow");
let corpus = FlowDb::from_flows(vec![CompiledFlow::from_parts(flow, "0".repeat(64))]);
let mut host = host_with(open(6379, Protocol::Tcp, "redis"));
run_flows(&mut host, &corpus, &default_envelope(), |_| {
Some(Box::new(Canned(b"ok")))
});
let port = host.ports().find(|port| port.number() == 6379).unwrap();
assert_eq!(
port.findings().count(),
0,
"an exploit-class flow ran under the default envelope"
);
let mut opened = host_with(open(6379, Protocol::Tcp, "redis"));
let permissive = DetectionEnvelope::up_to(DetectionClass::Exploit);
run_flows(&mut opened, &corpus, &permissive, |_| {
Some(Box::new(Canned(b"ok")))
});
let port = opened.ports().find(|port| port.number() == 6379).unwrap();
assert_eq!(
port.findings().count(),
1,
"an exploit the operator opted into did not run"
);
}
#[test]
fn a_flow_whose_budget_cuts_it_short_is_returned_as_a_refusal() {
struct Refusing;
impl Probe for Refusing {
fn speak(&mut self, _bytes: &[u8]) -> Option<Vec<u8>> {
None
}
fn last_refusal(&self) -> Option<ProbeRefusal> {
Some(ProbeRefusal::Bytes)
}
}
let (findings, refusals) = detect_port(
FlowDb::global(),
&benign_envelope(),
"192.0.2.10",
Some("redis"),
6379,
Protocol::Tcp,
|_caps| Some(Box::new(Refusing)),
);
assert!(findings.is_empty(), "a refused flow drew no finding");
assert!(
refusals
.iter()
.any(|(id, refusal)| id == "redis-unauth-access" && *refusal == ProbeRefusal::Bytes),
"the budget refusal was not surfaced: {refusals:?}"
);
}
struct Counting {
calls: std::sync::Arc<AtomicU32>,
reply: Vec<u8>,
complete: bool,
}
impl Probe for Counting {
fn speak(&mut self, _bytes: &[u8]) -> Option<Vec<u8>> {
self.calls.fetch_add(1, Ordering::Relaxed);
Some(self.reply.clone())
}
fn reply_complete(&self) -> bool {
self.complete
}
}
fn counting(reply: &[u8], complete: bool) -> (Box<Counting>, std::sync::Arc<AtomicU32>) {
let calls = std::sync::Arc::new(AtomicU32::new(0));
let probe = Box::new(Counting {
calls: calls.clone(),
reply: reply.to_vec(),
complete,
});
(probe, calls)
}
#[test]
fn a_complete_reply_is_served_from_the_cache_to_a_later_flow() {
let request = b"GET / HTTP/1.1\r\nHost: h\r\n\r\n";
let cache = Mutex::new(HashMap::new());
let strikes = AtomicU32::new(0);
let (first, first_calls) = counting(b"the page", true);
let (second, second_calls) = counting(b"never read", true);
let mut a = CachingProbe {
inner: first,
cache: &cache,
strikes: &strikes,
stalled: false,
dead_after: Duration::from_millis(1500),
budget: 4096,
};
let mut b = CachingProbe {
inner: second,
cache: &cache,
strikes: &strikes,
stalled: false,
dead_after: Duration::from_millis(1500),
budget: 4096,
};
let from_a = a.speak(request);
let from_b = b.speak(request);
assert_eq!(from_a.as_deref(), Some(&b"the page"[..]));
assert_eq!(from_b, from_a, "the second flow got the first flow's reply");
assert_eq!(
first_calls.load(Ordering::Relaxed),
1,
"the first flow did the one real fetch"
);
assert_eq!(
second_calls.load(Ordering::Relaxed),
0,
"the second flow never touched the socket"
);
}
#[test]
fn a_different_request_is_fetched_rather_than_served() {
let cache = Mutex::new(HashMap::new());
let strikes = AtomicU32::new(0);
let (first, _) = counting(b"root", true);
let (second, second_calls) = counting(b"login", true);
let mut a = CachingProbe {
inner: first,
cache: &cache,
strikes: &strikes,
stalled: false,
dead_after: Duration::from_millis(1500),
budget: 4096,
};
let mut b = CachingProbe {
inner: second,
cache: &cache,
strikes: &strikes,
stalled: false,
dead_after: Duration::from_millis(1500),
budget: 4096,
};
a.speak(b"GET / HTTP/1.1\r\n\r\n");
let from_b = b.speak(b"GET /login HTTP/1.1\r\n\r\n");
assert_eq!(from_b.as_deref(), Some(&b"login"[..]));
assert_eq!(
second_calls.load(Ordering::Relaxed),
1,
"a request not in the cache is fetched"
);
}
#[test]
fn a_reply_larger_than_a_flow_budget_is_not_shared() {
let request = b"GET / HTTP/1.1\r\n\r\n";
let cache = Mutex::new(HashMap::new());
let strikes = AtomicU32::new(0);
let (first, _) = counting(&[b'x'; 100], true);
let mut a = CachingProbe {
inner: first,
cache: &cache,
strikes: &strikes,
stalled: false,
dead_after: Duration::from_millis(1500),
budget: 4096,
};
a.speak(request);
let (second, second_calls) = counting(&[b'y'; 40], true);
let mut b = CachingProbe {
inner: second,
cache: &cache,
strikes: &strikes,
stalled: false,
dead_after: Duration::from_millis(1500),
budget: 40,
};
let from_b = b.speak(request);
assert_eq!(
second_calls.load(Ordering::Relaxed),
1,
"the oversized cache entry was not served"
);
assert_eq!(
from_b,
Some(vec![b'y'; 40]),
"the flow got its own budgeted reply"
);
}
#[test]
fn an_incomplete_reply_is_never_cached() {
let request = b"GET / HTTP/1.1\r\n\r\n";
let cache = Mutex::new(HashMap::new());
let strikes = AtomicU32::new(0);
let (first, _) = counting(b"cut short", false);
let mut a = CachingProbe {
inner: first,
cache: &cache,
strikes: &strikes,
stalled: false,
dead_after: Duration::from_millis(1500),
budget: 4096,
};
a.speak(request);
assert!(
cache.lock().expect("uncontended in a test").is_empty(),
"a reply cut short by a budget was not cached"
);
let (second, second_calls) = counting(b"cut short", false);
let mut b = CachingProbe {
inner: second,
cache: &cache,
strikes: &strikes,
stalled: false,
dead_after: Duration::from_millis(1500),
budget: 4096,
};
b.speak(request);
assert_eq!(
second_calls.load(Ordering::Relaxed),
1,
"with nothing cached the next flow fetched"
);
}
#[test]
fn findings_come_back_in_corpus_order_however_the_flows_finish() {
use crate::detect::flow::db::CompiledFlow;
use crate::detect::flow::schema::FlowDetection;
let corpus = FlowDb::from_flows(
(0..DETECTION_FLOW_CONCURRENCY * 3)
.map(|n| {
let source = format!(
r#"
[detection]
id = "ordered-{n:02}"
version = "1.0.0"
title = "ordered {n:02}"
[detection.when]
service = "redis"
[detection.capabilities]
class = "active-benign"
[[step]]
send = "PING"
expect = "ok"
[[step.finding]]
when = "matched"
severity = "low"
summary = "flow {n:02} fired"
"#
);
let flow: FlowDetection = toml::from_str(&source).expect("a valid flow");
CompiledFlow::from_parts(flow, "0".repeat(64))
})
.collect(),
);
let answered = std::sync::atomic::AtomicU64::new(0);
let ordered = || {
let (findings, _) = detect_port(
&corpus,
&benign_envelope(),
"192.0.2.10",
Some("redis"),
6379,
Protocol::Tcp,
|_caps| {
let nth = answered.fetch_add(1, Ordering::Relaxed);
std::thread::sleep(Duration::from_micros((nth * 37) % 900));
Some(Box::new(Canned(b"ok")))
},
);
findings
.iter()
.map(|finding| finding.detection().id().to_string())
.collect::<Vec<_>>()
};
let first = ordered();
assert_eq!(
first.len(),
DETECTION_FLOW_CONCURRENCY * 3,
"every flow should have fired: {first:?}"
);
let mut sorted = first.clone();
sorted.sort();
assert_eq!(first, sorted, "the findings are not in corpus order");
for _ in 0..4 {
assert_eq!(ordered(), first, "the order moved between runs");
}
}
#[test]
fn a_stalling_port_is_not_widened_onto() {
use crate::detect::flow::db::CompiledFlow;
use crate::detect::flow::schema::FlowDetection;
let corpus = FlowDb::from_flows(
(0..DETECTION_FLOW_CONCURRENCY * 4)
.map(|n| {
let source = format!(
r#"
[detection]
id = "stalls-{n:02}"
version = "1.0.0"
title = "stalls {n:02}"
[detection.when]
service = "redis"
[detection.capabilities]
class = "active-benign"
max_millis = 40
[[step]]
send = "PING"
expect = "ok"
"#
);
let flow: FlowDetection = toml::from_str(&source).expect("a valid flow");
CompiledFlow::from_parts(flow, "0".repeat(64))
})
.collect(),
);
struct Stalling(std::sync::Arc<AtomicU32>);
impl Probe for Stalling {
fn speak(&mut self, _bytes: &[u8]) -> Option<Vec<u8>> {
self.0.fetch_add(1, Ordering::Relaxed);
std::thread::sleep(Duration::from_millis(40));
None
}
}
let opened = std::sync::Arc::new(AtomicU32::new(0));
let counted = std::sync::Arc::clone(&opened);
detect_port(
&corpus,
&benign_envelope(),
"192.0.2.10",
Some("redis"),
6379,
Protocol::Tcp,
move |_caps| Some(Box::new(Stalling(std::sync::Arc::clone(&counted))) as Box<dyn Probe>),
);
let sockets = opened.load(Ordering::Relaxed);
assert!(
sockets <= DEAD_PORT_STRIKES + 1,
"a stalling port was asked {sockets} times over, not {}",
DEAD_PORT_STRIKES + 1
);
}
#[test]
fn a_port_that_never_answers_stops_being_probed() {
struct Silent(std::sync::Arc<AtomicU32>);
impl Probe for Silent {
fn speak(&mut self, _bytes: &[u8]) -> Option<Vec<u8>> {
self.0.fetch_add(1, Ordering::Relaxed);
None
}
}
let cache = Mutex::new(HashMap::new());
let strikes = AtomicU32::new(0);
let calls = std::sync::Arc::new(AtomicU32::new(0));
for n in 0..DEAD_PORT_STRIKES + 5 {
let mut probe = CachingProbe {
inner: Box::new(Silent(calls.clone())),
cache: &cache,
strikes: &strikes,
stalled: false,
dead_after: Duration::ZERO,
budget: 4096,
};
let request = format!("GET /{n} HTTP/1.1\r\n\r\n");
assert!(probe.speak(request.as_bytes()).is_none());
}
assert_eq!(
calls.load(Ordering::Relaxed),
DEAD_PORT_STRIKES,
"the socket was spared once the port had shown it will not answer"
);
}
#[test]
fn a_refusal_is_withheld_after_a_dead_wait_but_kept_otherwise() {
struct Refuser;
impl Probe for Refuser {
fn speak(&mut self, _bytes: &[u8]) -> Option<Vec<u8>> {
None
}
fn last_refusal(&self) -> Option<ProbeRefusal> {
Some(ProbeRefusal::Deadline)
}
}
let cache = Mutex::new(HashMap::new());
let strikes = AtomicU32::new(0);
let mut live = CachingProbe {
inner: Box::new(Refuser),
cache: &cache,
strikes: &strikes,
stalled: false,
dead_after: Duration::from_secs(3600),
budget: 4096,
};
live.speak(b"GET /a HTTP/1.1\r\n\r\n");
assert!(!live.stalled);
assert_eq!(live.last_refusal(), Some(ProbeRefusal::Deadline));
let strikes = AtomicU32::new(0);
let mut dead = CachingProbe {
inner: Box::new(Refuser),
cache: &cache,
strikes: &strikes,
stalled: false,
dead_after: Duration::ZERO,
budget: 4096,
};
dead.speak(b"GET /b HTTP/1.1\r\n\r\n");
assert!(dead.stalled);
assert_eq!(dead.last_refusal(), None);
}
#[test]
fn a_port_that_answers_but_runs_out_the_clock_stops_being_probed() {
let cache = Mutex::new(HashMap::new());
let strikes = AtomicU32::new(0);
for n in 0..DEAD_PORT_STRIKES + 5 {
let (inner, calls) = counting(b"slow but complete", true);
let mut probe = CachingProbe {
inner,
cache: &cache,
strikes: &strikes,
stalled: false,
dead_after: Duration::ZERO,
budget: 4096,
};
let request = format!("GET /{n} HTTP/1.1\r\n\r\n");
probe.speak(request.as_bytes());
let expected = if n < DEAD_PORT_STRIKES { 1 } else { 0 };
assert_eq!(
calls.load(Ordering::Relaxed),
expected,
"flow {n} {} touch the socket",
if expected == 1 {
"should"
} else {
"should not"
}
);
}
}
}