use super::{now_secs, Confidence, Evidence, Finding, ScanStatus, Severity, Subject};
use serde::{Deserialize, Serialize};
use std::collections::BTreeSet;
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
pub struct Listener {
pub protocol: String,
pub local_port: u16,
pub externally_reachable: bool,
pub process: Option<String>,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct Baseline {
pub recorded_at: u64,
pub listeners: BTreeSet<Listener>,
}
impl Baseline {
pub fn is_empty(&self) -> bool {
self.listeners.is_empty()
}
pub fn len(&self) -> usize {
self.listeners.len()
}
}
const NOTABLE_PORTS: &[(u16, &str)] = &[
(23, "telnet, unencrypted remote shell"),
(1080, "SOCKS proxy"),
(1337, "conventional in remote-access tooling"),
(3389, "RDP"),
(4444, "Metasploit default handler"),
(5555, "adb and various remote-access tools"),
(5900, "VNC"),
(6666, "conventional in remote-access tooling"),
(31337, "conventional in remote-access tooling"),
];
pub fn current_listeners() -> Result<BTreeSet<Listener>, String> {
use crate::connections::ConnectionMonitor;
let monitor = ConnectionMonitor::new().map_err(|e| e.to_string())?;
let connections = monitor.listening_sockets().map_err(|e| e.to_string())?;
let mut out = BTreeSet::new();
for c in connections {
let Some(local_port) = c.local_port else {
continue;
};
let externally_reachable = !c.local_ip.is_loopback();
out.insert(Listener {
protocol: format!("{:?}", c.protocol).to_lowercase(),
local_port,
externally_reachable,
process: c.process_name.clone(),
});
}
Ok(out)
}
pub fn record() -> Result<Baseline, String> {
Ok(Baseline {
recorded_at: now_secs(),
listeners: current_listeners()?,
})
}
pub fn scan(baseline: &Baseline) -> ScanStatus {
let current = match current_listeners() {
Ok(c) => c,
Err(reason) => {
return ScanStatus::Failed {
reason: format!("could not enumerate sockets: {reason}"),
}
}
};
if baseline.is_empty() {
return ScanStatus::NoBaseline {
recorded: current.len(),
reason: "no listener baseline existed, so nothing could be compared. \
A baseline taken now includes whatever is already listening, \
including anything that should not be."
.into(),
};
}
let checked = current.len();
let mut findings = compare(baseline, ¤t);
findings.extend(reputation_findings(¤t));
if findings.is_empty() {
ScanStatus::Clean { checked }
} else {
ScanStatus::Findings { checked, findings }
}
}
pub fn compare(baseline: &Baseline, current: &BTreeSet<Listener>) -> Vec<Finding> {
let mut findings = Vec::new();
for l in current.difference(&baseline.listeners) {
let severity = if l.externally_reachable {
Severity::Medium
} else {
Severity::Low
};
let mut evidence = vec![
Evidence::observed("net.protocol", &l.protocol),
Evidence::observed("net.local_port", l.local_port.to_string()),
Evidence::differs(
"net.in_baseline",
"false",
"true for every other listener on this machine",
),
Evidence::observed(
"net.reachable",
if l.externally_reachable {
"bound to a routable address"
} else {
"loopback only"
},
),
];
if let Some(p) = &l.process {
evidence.push(Evidence::observed("net.process", p));
}
if let Some(f) = Finding::new(
"net.new_listener",
"a port is listening that was not in the baseline",
severity,
Confidence::Certain,
subject_of(l),
evidence,
) {
findings.push(f);
}
}
for l in baseline.listeners.difference(current) {
if let Some(f) = Finding::new(
"net.listener_gone",
"a port in the baseline is no longer listening",
Severity::Info,
Confidence::Certain,
subject_of(l),
vec![
Evidence::observed("net.protocol", &l.protocol),
Evidence::observed("net.local_port", l.local_port.to_string()),
Evidence::differs("net.listening", "false", "true"),
],
) {
findings.push(f);
}
}
findings
}
pub fn reputation_findings(current: &BTreeSet<Listener>) -> Vec<Finding> {
let mut out = Vec::new();
for l in current {
let Some((_, why)) = NOTABLE_PORTS.iter().find(|(p, _)| *p == l.local_port) else {
continue;
};
let severity = if l.externally_reachable {
Severity::High
} else {
Severity::Low
};
let mut evidence = vec![
Evidence::observed("net.local_port", l.local_port.to_string()),
Evidence::observed("net.port_convention", *why),
Evidence::observed(
"net.reachable",
if l.externally_reachable {
"bound to a routable address"
} else {
"loopback only"
},
),
];
if let Some(p) = &l.process {
evidence.push(Evidence::observed("net.process", p));
}
if let Some(f) = Finding::new(
"net.notable_port",
"a port conventionally used by remote-access tooling is listening",
severity,
Confidence::Possible,
subject_of(l),
evidence,
) {
out.push(f);
}
}
out
}
fn subject_of(l: &Listener) -> Subject {
Subject::Network {
local_port: l.local_port,
remote: None,
process: l.process.clone(),
pid: None,
}
}
#[cfg(test)]
mod tests {
use super::*;
fn listener(port: u16, external: bool, process: Option<&str>) -> Listener {
Listener {
protocol: "tcp".into(),
local_port: port,
externally_reachable: external,
process: process.map(|s| s.to_string()),
}
}
fn baseline_of(ls: &[Listener]) -> Baseline {
Baseline {
recorded_at: 0,
listeners: ls.iter().cloned().collect(),
}
}
#[test]
fn a_new_listener_is_found_and_carries_what_was_seen() {
let base = baseline_of(&[listener(22, true, Some("sshd"))]);
let current: BTreeSet<Listener> = [
listener(22, true, Some("sshd")),
listener(8080, true, Some("node")),
]
.into_iter()
.collect();
let findings = compare(&base, ¤t);
assert_eq!(findings.len(), 1);
assert_eq!(findings[0].rule, "net.new_listener");
assert_eq!(findings[0].confidence, Confidence::Certain);
assert!(findings[0]
.evidence
.iter()
.any(|e| e.kind == "net.process" && e.observed == "node"));
}
#[test]
fn a_loopback_listener_is_ranked_below_a_routable_one() {
let base = baseline_of(&[listener(1, true, None)]);
let loopback: BTreeSet<Listener> = [listener(1, true, None), listener(9000, false, None)]
.into_iter()
.collect();
let routable: BTreeSet<Listener> = [listener(1, true, None), listener(9000, true, None)]
.into_iter()
.collect();
let lo = compare(&base, &loopback);
let ro = compare(&base, &routable);
assert_eq!(lo[0].severity, Severity::Low);
assert_eq!(ro[0].severity, Severity::Medium);
assert!(
ro[0].severity > lo[0].severity,
"a service reachable from off the machine is a different exposure \
from one bound to 127.0.0.1, and an alerting tool that shouts at \
`cargo run` is one nobody keeps running"
);
}
#[test]
fn a_vanished_listener_is_recorded_but_not_escalated() {
let base = baseline_of(&[listener(22, true, Some("sshd"))]);
let current: BTreeSet<Listener> = BTreeSet::new();
let findings = compare(&base, ¤t);
assert_eq!(findings.len(), 1);
assert_eq!(findings[0].rule, "net.listener_gone");
assert_eq!(findings[0].severity, Severity::Info);
}
#[test]
fn the_port_table_is_only_ever_possible() {
let current: BTreeSet<Listener> = [listener(4444, true, Some("nc"))].into_iter().collect();
let findings = reputation_findings(¤t);
assert_eq!(findings.len(), 1);
assert_eq!(findings[0].rule, "net.notable_port");
assert_eq!(
findings[0].confidence,
Confidence::Possible,
"4444 is also a port a developer picked for a test server; a table \
of conventions cannot produce a certainty"
);
assert_eq!(findings[0].severity, Severity::High);
assert!(findings[0]
.evidence
.iter()
.any(|e| e.kind == "net.port_convention"));
}
#[test]
fn an_ordinary_port_matches_no_convention() {
let current: BTreeSet<Listener> = [listener(8080, true, None)].into_iter().collect();
assert!(reputation_findings(¤t).is_empty());
}
#[test]
fn a_listener_with_no_readable_process_carries_none() {
let base = baseline_of(&[listener(1, true, None)]);
let current: BTreeSet<Listener> = [listener(1, true, None), listener(4711, true, None)]
.into_iter()
.collect();
let findings = compare(&base, ¤t);
assert!(
!findings[0].evidence.iter().any(|e| e.kind == "net.process"),
"no process evidence is emitted when none was readable, rather than \
an 'unknown' string that reads like an observation"
);
match &findings[0].subject {
Subject::Network { process, .. } => assert!(process.is_none()),
other => panic!("expected a network subject, got {other:?}"),
}
}
#[test]
fn an_identical_socket_table_produces_nothing() {
let ls = [
listener(22, true, Some("sshd")),
listener(80, true, Some("nginx")),
];
let base = baseline_of(&ls);
let current: BTreeSet<Listener> = ls.into_iter().collect();
assert!(compare(&base, ¤t).is_empty());
}
#[test]
fn a_baseline_round_trips_through_json() {
let base = baseline_of(&[listener(22, true, Some("sshd"))]);
let json = serde_json::to_string(&base).unwrap();
let back: Baseline = serde_json::from_str(&json).unwrap();
assert_eq!(back, base);
}
#[test]
fn enumerating_this_machine_either_works_or_says_why() {
match current_listeners() {
Ok(ls) => {
for l in &ls {
assert_ne!(
l.local_port, 0,
"current_listeners must filter unbound sockets: nothing can connect \n to them and they would churn every baseline",
);
assert!(
!l.protocol.is_empty(),
"a listener with no protocol is not a reading"
);
}
}
Err(reason) => assert!(
!reason.is_empty(),
"a failure must carry a reason, or a caller cannot tell it from a quiet machine"
),
}
}
}