pub mod catalog;
pub mod discovery;
pub mod security;
pub mod service;
pub mod set;
pub use catalog::{TCP_BY_PREVALENCE, UDP_BY_PREVALENCE};
pub use discovery::{Discovery, ScanResponse};
pub use security::{CertificateInfo, Security};
pub use service::Service;
pub use set::{PortSet, PortSetParseError};
use std::collections::BTreeMap;
use crate::model::finding::{ClaimId, Finding, MAX_FINDINGS_PER_SUBJECT};
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum Protocol {
Tcp,
Udp,
Sctp,
}
impl Protocol {
pub const ALL: &'static [Self] = &[Self::Tcp, Self::Udp, Self::Sctp];
pub const fn spec_prefix(self) -> &'static str {
match self {
Self::Tcp => "",
Self::Udp => "u:",
Self::Sctp => "s:",
}
}
pub(crate) const fn qualifier(self) -> &'static str {
match self {
Self::Tcp => "t:",
Self::Udp | Self::Sctp => self.spec_prefix(),
}
}
}
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum PortState {
Unasked,
ClosedFiltered,
Filtered,
Unfiltered,
Closed,
OpenFiltered,
Open,
}
impl PortState {
pub const ALL: &'static [Self] = &[
Self::Unasked,
Self::ClosedFiltered,
Self::Filtered,
Self::Unfiltered,
Self::Closed,
Self::OpenFiltered,
Self::Open,
];
}
#[cfg(any(feature = "import-json", feature = "import-nmap"))]
pub(crate) fn fold(ports: &mut BTreeMap<(u16, Protocol), Port>, port: Port) {
match ports.entry((port.number, port.protocol)) {
std::collections::btree_map::Entry::Occupied(slot) => slot.into_mut().merge(port),
std::collections::btree_map::Entry::Vacant(slot) => {
slot.insert(port);
}
}
}
#[must_use]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Port {
number: u16,
protocol: Protocol,
state: PortState,
service: Option<Box<Service>>,
security: Option<Box<Security>>,
discovery: Option<Discovery>,
findings: BTreeMap<ClaimId, Finding>,
}
impl Port {
pub fn new(number: u16, protocol: Protocol, state: PortState) -> Self {
Self {
number,
protocol,
state,
service: None,
security: None,
discovery: None,
findings: BTreeMap::new(),
}
}
pub fn number(&self) -> u16 {
self.number
}
pub fn protocol(&self) -> Protocol {
self.protocol
}
pub fn state(&self) -> PortState {
self.state
}
pub fn set_state(&mut self, state: PortState) {
self.state = std::cmp::max(self.state, state);
}
pub fn service(&self) -> Option<&Service> {
self.service.as_deref()
}
pub fn service_name(&self) -> Option<&str> {
self.service.as_ref().map(|s| s.name())
}
pub fn set_service(&mut self, service: Service) {
self.service = Some(Box::new(service));
}
pub fn security(&self) -> Option<&Security> {
self.security.as_deref()
}
pub fn set_security(&mut self, security: Security) {
self.security = Some(Box::new(security));
}
pub fn discovery(&self) -> Option<&Discovery> {
self.discovery.as_ref()
}
pub fn with_service(mut self, service: Service) -> Self {
self.set_service(service);
self
}
pub fn with_security(mut self, security: Security) -> Self {
self.set_security(security);
self
}
pub fn with_discovery(mut self, discovery: Discovery) -> Self {
self.discovery = Some(discovery);
self
}
pub fn findings(&self) -> impl Iterator<Item = &Finding> {
self.findings.values()
}
pub fn add_finding(&mut self, finding: Finding) -> bool {
let claim = finding.claim_id();
let full = self.findings.len() >= MAX_FINDINGS_PER_SUBJECT;
match self.findings.get_mut(&claim) {
Some(existing) => existing.corroborate(finding),
None if full => false,
None => {
self.findings.insert(claim, finding);
true
}
}
}
pub fn merge(&mut self, other: Port) {
debug_assert_eq!(
(self.number, self.protocol),
(other.number, other.protocol),
"merging two different endpoints into one record"
);
let Port {
number: _,
protocol: _,
state,
service,
security,
discovery,
findings,
} = other;
let previous_state = self.state;
self.state = std::cmp::max(self.state, state);
if let Some(service) = service {
match &mut self.service {
Some(recorded) => recorded.merge(*service),
None => self.service = Some(service),
}
}
if let Some(security) = security {
match &mut self.security {
Some(recorded) => recorded.merge(*security),
None => self.security = Some(security),
}
}
if discovery.is_some() && (state > previous_state || self.discovery.is_none()) {
self.discovery = discovery;
}
for finding in findings.into_values() {
self.add_finding(finding);
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_probe_that_learned_more_raises_the_verdict() {
let mut p1 = Port::new(80, Protocol::Tcp, PortState::Filtered);
p1.merge(Port::new(80, Protocol::Tcp, PortState::Open));
assert_eq!(p1.state(), PortState::Open);
let mut p2 = Port::new(53, Protocol::Udp, PortState::OpenFiltered);
p2.merge(Port::new(53, Protocol::Udp, PortState::Open));
assert_eq!(p2.state(), PortState::Open);
let mut p3 = Port::new(443, Protocol::Tcp, PortState::Unfiltered);
p3.merge(Port::new(443, Protocol::Tcp, PortState::Closed));
assert_eq!(p3.state(), PortState::Closed);
}
#[test]
fn a_tie_keeps_the_telemetry_already_on_record() {
let mut first = Port::new(22, Protocol::Tcp, PortState::Open)
.with_discovery(Discovery::new(ScanResponse::TcpSynAck).with_ttl(64));
let second = Port::new(22, Protocol::Tcp, PortState::Open)
.with_discovery(Discovery::new(ScanResponse::TcpSynAck).with_ttl(128));
first.merge(second);
assert_eq!(
first.discovery().expect("telemetry survives").ttl(),
Some(64)
);
}
#[test]
fn a_port_with_no_telemetry_adopts_a_weaker_probes() {
let mut open = Port::new(22, Protocol::Tcp, PortState::Open);
let filtered = Port::new(22, Protocol::Tcp, PortState::Filtered)
.with_discovery(Discovery::new(ScanResponse::NoResponse));
open.merge(filtered);
assert_eq!(open.state(), PortState::Open, "the weaker state loses");
assert_eq!(
open.discovery().expect("adopted").reason(),
&ScanResponse::NoResponse,
"but its account of itself is better than none"
);
}
#[test]
fn an_unasked_port_loses_to_every_verdict() {
for &verdict in PortState::ALL {
if verdict == PortState::Unasked {
continue;
}
assert!(
PortState::Unasked < verdict,
"{verdict:?} does not outrank a port nobody probed"
);
}
let mut probed = Port::new(22, Protocol::Tcp, PortState::Closed);
probed.merge(Port::new(22, Protocol::Tcp, PortState::Unasked));
assert_eq!(
probed.state(),
PortState::Closed,
"a later sitting that never asked unlearned the first one's answer"
);
let mut unasked = Port::new(22, Protocol::Tcp, PortState::Unasked);
unasked.merge(Port::new(22, Protocol::Tcp, PortState::Closed));
assert_eq!(unasked.state(), PortState::Closed);
}
#[test]
fn telemetry_follows_the_verdict_it_explains() {
let disc_filtered = Discovery::new(ScanResponse::NoResponse);
let mut p_filtered =
Port::new(22, Protocol::Tcp, PortState::Filtered).with_discovery(disc_filtered.clone());
let disc_open = Discovery::new(ScanResponse::TcpSynAck);
let p_open =
Port::new(22, Protocol::Tcp, PortState::Open).with_discovery(disc_open.clone());
p_filtered.merge(p_open);
assert_eq!(p_filtered.state(), PortState::Open);
assert_eq!(
p_filtered.discovery().unwrap().reason(),
&ScanResponse::TcpSynAck
);
}
#[test]
fn an_unanswered_port_pays_a_pointer_for_what_it_did_not_learn() {
use std::mem::size_of;
let carried = size_of::<(u16, Protocol, PortState)>()
+ size_of::<Option<Discovery>>()
+ size_of::<BTreeMap<ClaimId, Finding>>();
let absent = 2 * size_of::<usize>();
let padding = std::mem::align_of::<Port>();
assert!(
size_of::<Port>() <= carried + absent + padding,
"a port record is {} bytes where what an unanswered port holds is {carried}",
size_of::<Port>(),
);
}
fn a_finding(detection_id: &str) -> Finding {
use crate::model::confidence::Confidence;
use crate::model::finding::{DetectionClass, DetectionId, Severity, Version};
Finding::new(
DetectionId::new(detection_id, Version::new(1, 0, 0), "hash").unwrap(),
"A port finding",
Severity::High,
Confidence::Certain,
DetectionClass::ActiveBenign,
)
.unwrap()
}
#[test]
fn a_merge_keeps_both_ports_findings() {
let mut base = Port::new(443, Protocol::Tcp, PortState::Open);
base.add_finding(a_finding("det-a"));
let mut other = Port::new(443, Protocol::Tcp, PortState::Open);
other.add_finding(a_finding("det-b"));
base.merge(other);
assert_eq!(
base.findings().count(),
2,
"a merge must not drop the other's findings"
);
}
}