use std::collections::{BTreeMap, BTreeSet};
use std::time::Duration;
use std::time::SystemTime;
use crate::diff::change::{Change, Coverage, Presence};
use crate::diff::host::Reassessment;
use crate::model::finding::{Finding, Standing};
use crate::model::port::security::CertificateInfo;
use crate::model::port::{Port, PortState, Protocol, Security, Service};
#[derive(Debug, Clone, PartialEq)]
pub struct PortDelta {
number: u16,
protocol: Protocol,
presence: Presence,
baseline: Option<Port>,
current: Option<Port>,
changes: Vec<PortChange>,
}
impl PortDelta {
pub fn number(&self) -> u16 {
self.number
}
pub fn protocol(&self) -> Protocol {
self.protocol
}
pub fn presence(&self) -> Presence {
self.presence
}
pub fn baseline(&self) -> Option<&Port> {
self.baseline.as_ref()
}
pub fn current(&self) -> Option<&Port> {
self.current.as_ref()
}
pub fn changes(&self) -> &[PortChange] {
&self.changes
}
pub fn is_empty(&self) -> bool {
self.presence.is_in_both() && self.changes.is_empty()
}
pub fn is_opened(&self) -> bool {
self.state_of(self.current.as_ref()) == Some(PortState::Open)
&& self.state_of(self.baseline.as_ref()) != Some(PortState::Open)
}
pub fn is_closed(&self) -> bool {
self.state_of(self.baseline.as_ref()) == Some(PortState::Open)
&& self.state_of(self.current.as_ref()) != Some(PortState::Open)
}
fn state_of(&self, port: Option<&Port>) -> Option<PortState> {
port.map(Port::state)
}
}
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq)]
pub enum PortChange {
State(Change<PortState>),
Service(ServiceChange),
Security(SecurityChange),
Findings {
appeared: Vec<Finding>,
resolved: Vec<Finding>,
unsettled: Vec<Finding>,
reassessed: Vec<Reassessment>,
},
}
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq)]
pub enum ServiceChange {
Identified(Service),
Unidentified(Service),
Name(Change<String>),
Product(Change<Option<String>>),
Vendor(Change<Option<String>>),
Version(Change<Option<String>>),
ExtraInfo(Change<Option<String>>),
Cpes {
gained: Vec<String>,
lost: Vec<String>,
},
}
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq)]
pub enum SecurityChange {
TlsVersion(Change<Option<String>>),
CipherSuite(Change<Option<String>>),
Alpn {
gained: Vec<String>,
lost: Vec<String>,
},
Certificate(CertificateChange),
}
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq)]
pub enum CertificateChange {
Presented(CertificateInfo),
Withdrawn(CertificateInfo),
Rotated {
before: Box<CertificateInfo>,
after: Box<CertificateInfo>,
},
Expiring {
certificate: Box<CertificateInfo>,
remaining: Duration,
},
Expired {
certificate: Box<CertificateInfo>,
since: Duration,
},
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Validity {
Absent,
NotYetValid,
Valid,
Expiring,
Expired,
}
pub(crate) struct Clocks {
pub(crate) baseline: SystemTime,
pub(crate) current: SystemTime,
pub(crate) expiry_threshold: Duration,
}
pub(crate) fn compare<'a>(
baseline: &[&'a Port],
current: &[&'a Port],
presence: PresenceFor<'_>,
clocks: &Clocks,
) -> Vec<PortDelta> {
let index = |ports: &[&'a Port]| -> BTreeMap<(u16, Protocol), &'a Port> {
ports
.iter()
.filter(|port| port.state() != PortState::Unasked)
.map(|port| ((port.number(), port.protocol()), *port))
.collect()
};
let unreached = |ports: &[&'a Port]| -> BTreeSet<(u16, Protocol)> {
ports
.iter()
.filter(|port| port.state() == PortState::Unasked)
.map(|port| (port.number(), port.protocol()))
.collect()
};
let baseline_unreached = unreached(baseline);
let current_unreached = unreached(current);
let baseline = index(baseline);
let current = index(current);
let keys: BTreeSet<(u16, Protocol)> = baseline.keys().chain(current.keys()).copied().collect();
let mut deltas = Vec::new();
for (number, protocol) in keys {
let before = baseline.get(&(number, protocol)).copied();
let after = current.get(&(number, protocol)).copied();
let (presence, changes) = match (before, after) {
(Some(_), Some(_)) => (Presence::Both, changes_between(before, after, clocks)),
(Some(_), None) => (
presence.removed(number, protocol, ¤t_unreached),
Vec::new(),
),
(None, Some(_)) => (
presence.added(number, protocol, &baseline_unreached),
Vec::new(),
),
(None, None) => unreachable!("a key comes from one side or the other"),
};
if presence.is_in_both() && changes.is_empty() {
continue;
}
deltas.push(PortDelta {
number,
protocol,
presence,
baseline: before.cloned(),
current: after.cloned(),
changes,
});
}
deltas
}
pub(crate) struct PresenceFor<'a> {
pub(crate) baseline: &'a dyn Fn(u16, Protocol) -> Coverage,
pub(crate) current: &'a dyn Fn(u16, Protocol) -> Coverage,
}
impl PresenceFor<'_> {
fn added(
&self,
number: u16,
protocol: Protocol,
unreached: &BTreeSet<(u16, Protocol)>,
) -> Presence {
Presence::Added {
before: Self::coverage(self.baseline, number, protocol, unreached),
}
}
fn removed(
&self,
number: u16,
protocol: Protocol,
unreached: &BTreeSet<(u16, Protocol)>,
) -> Presence {
Presence::Removed {
after: Self::coverage(self.current, number, protocol, unreached),
}
}
fn coverage(
scope: &dyn Fn(u16, Protocol) -> Coverage,
number: u16,
protocol: Protocol,
unreached: &BTreeSet<(u16, Protocol)>,
) -> Coverage {
if unreached.contains(&(number, protocol)) {
Coverage::Unreached
} else {
scope(number, protocol)
}
}
}
fn changes_between(
before: Option<&Port>,
after: Option<&Port>,
clocks: &Clocks,
) -> Vec<PortChange> {
let (Some(before), Some(after)) = (before, after) else {
return Vec::new();
};
let mut changes = Vec::new();
if let Some(state) = Change::between(before.state(), after.state()) {
changes.push(PortChange::State(state));
}
changes.extend(
service_changes(before.service(), after.service())
.into_iter()
.map(PortChange::Service),
);
changes.extend(
security_changes(before.security(), after.security(), clocks)
.into_iter()
.map(PortChange::Security),
);
let (appeared, gone, reassessed) =
super::host::findings_between(before.findings(), after.findings());
let (unsettled, resolved): (Vec<Finding>, Vec<Finding>) = gone
.into_iter()
.partition(|finding| standing(finding, before, after) == Some(Standing::Unsettled));
if !appeared.is_empty()
|| !resolved.is_empty()
|| !unsettled.is_empty()
|| !reassessed.is_empty()
{
changes.push(PortChange::Findings {
appeared,
resolved,
unsettled,
reassessed,
});
}
changes
}
fn standing(finding: &Finding, before: &Port, after: &Port) -> Option<Standing> {
if finding.is_correlation() {
return correlation_standing(finding, before.service()?, after.service());
}
let silent = Security::new();
let now = after.security().unwrap_or(&silent);
now.standing(finding, before.security()?)
}
fn correlation_standing(
finding: &Finding,
basis: &Service,
now: Option<&Service>,
) -> Option<Standing> {
let backs = |service: &Service| finding.cpes().any(|cpe| service.cpes().contains(cpe));
if !backs(basis) {
return None;
}
let Some(now) = now.filter(|service| !service.is_inferred()) else {
return Some(Standing::Unsettled);
};
if backs(now) {
return Some(Standing::Upheld);
}
let differs = |stated: Option<&str>, then: Option<&str>| {
stated.is_some_and(|stated| then.is_none_or(|then| stated != then))
};
let contradicts = now.name() != basis.name()
|| differs(now.product(), basis.product())
|| differs(now.version(), basis.version());
Some(if contradicts {
Standing::Overturned
} else {
Standing::Unsettled
})
}
fn service_changes(before: Option<&Service>, after: Option<&Service>) -> Vec<ServiceChange> {
let before = before.filter(|service| !service.is_inferred());
let after = after.filter(|service| !service.is_inferred());
match (before, after) {
(None, None) => Vec::new(),
(None, Some(after)) => vec![ServiceChange::Identified(after.clone())],
(Some(before), None) => vec![ServiceChange::Unidentified(before.clone())],
(Some(before), Some(after)) => {
let mut changes = Vec::new();
if let Some(name) = Change::between(before.name().to_owned(), after.name().to_owned()) {
changes.push(ServiceChange::Name(name));
}
if let Some(product) = optional(before.product(), after.product()) {
changes.push(ServiceChange::Product(product));
}
if let Some(vendor) = optional(before.vendor(), after.vendor()) {
changes.push(ServiceChange::Vendor(vendor));
}
if let Some(version) = optional(before.version(), after.version()) {
changes.push(ServiceChange::Version(version));
}
if let Some(extra) = optional(before.extrainfo(), after.extrainfo()) {
changes.push(ServiceChange::ExtraInfo(extra));
}
let (gained, lost) = set_change(
before.cpes().iter().map(|cpe| cpe.to_string()),
after.cpes().iter().map(|cpe| cpe.to_string()),
);
if !gained.is_empty() || !lost.is_empty() {
changes.push(ServiceChange::Cpes { gained, lost });
}
changes
}
}
}
fn security_changes(
before: Option<&Security>,
after: Option<&Security>,
clocks: &Clocks,
) -> Vec<SecurityChange> {
let mut changes = Vec::new();
let before_version = before.and_then(Security::tls_version);
let after_version = after.and_then(Security::tls_version);
if let Some(version) = optional(before_version, after_version) {
changes.push(SecurityChange::TlsVersion(version));
}
let before_cipher = before.and_then(Security::cipher_suite);
let after_cipher = after.and_then(Security::cipher_suite);
if let Some(cipher) = optional(before_cipher, after_cipher) {
changes.push(SecurityChange::CipherSuite(cipher));
}
let (gained, lost) = set_change(
before
.map(Security::alpn)
.unwrap_or_default()
.iter()
.map(|p| p.to_string()),
after
.map(Security::alpn)
.unwrap_or_default()
.iter()
.map(|p| p.to_string()),
);
if !gained.is_empty() || !lost.is_empty() {
changes.push(SecurityChange::Alpn { gained, lost });
}
changes.extend(
certificate_changes(before, after, clocks)
.into_iter()
.map(SecurityChange::Certificate),
);
changes
}
fn certificate_changes(
before: Option<&Security>,
after: Option<&Security>,
clocks: &Clocks,
) -> Vec<CertificateChange> {
let before_cert = before.and_then(Security::certificate);
let after_cert = after.and_then(Security::certificate);
let mut changes = Vec::new();
match (before_cert, after_cert) {
(None, None) => return changes,
(None, Some(after)) => changes.push(CertificateChange::Presented(after.clone())),
(Some(before), None) => {
changes.push(CertificateChange::Withdrawn(before.clone()));
return changes;
}
(Some(before), Some(after)) => {
if before.fingerprint_sha256() != after.fingerprint_sha256() {
changes.push(CertificateChange::Rotated {
before: Box::new(before.clone()),
after: Box::new(after.clone()),
});
}
}
}
let same_certificate = matches!(
(before_cert, after_cert),
(Some(before), Some(after))
if before.fingerprint_sha256() == after.fingerprint_sha256()
);
let was = if same_certificate {
validity(after, clocks.expiry_threshold, clocks.baseline)
} else {
Validity::Absent
};
let is = validity(after, clocks.expiry_threshold, clocks.current);
if let Some(certificate) = after_cert {
match is {
Validity::Expiring if was != Validity::Expiring => {
let remaining = certificate
.validity_end()
.duration_since(clocks.current)
.unwrap_or_default();
changes.push(CertificateChange::Expiring {
certificate: Box::new(certificate.clone()),
remaining,
});
}
Validity::Expired if was != Validity::Expired => {
let since = clocks
.current
.duration_since(certificate.validity_end())
.unwrap_or_default();
changes.push(CertificateChange::Expired {
certificate: Box::new(certificate.clone()),
since,
});
}
_ => {}
}
}
changes
}
fn validity(security: Option<&Security>, threshold: Duration, at: SystemTime) -> Validity {
let Some(security) = security else {
return Validity::Absent;
};
let Some(certificate) = security.certificate() else {
return Validity::Absent;
};
if at < certificate.validity_start() {
Validity::NotYetValid
} else if at > certificate.validity_end() {
Validity::Expired
} else if security.is_cert_expiring_at(threshold, at) {
Validity::Expiring
} else {
Validity::Valid
}
}
fn optional(before: Option<&str>, after: Option<&str>) -> Option<Change<Option<String>>> {
Change::between(before.map(str::to_owned), after.map(str::to_owned))
}
fn set_change(
before: impl Iterator<Item = String>,
after: impl Iterator<Item = String>,
) -> (Vec<String>, Vec<String>) {
let before: std::collections::BTreeSet<String> = before.collect();
let after: std::collections::BTreeSet<String> = after.collect();
let gained = after.difference(&before).cloned().collect();
let lost = before.difference(&after).cloned().collect();
(gained, lost)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::model::confidence::Confidence;
use crate::model::finding::{DetectionClass, DetectionId, Severity, Version};
use crate::model::tls::{
CipherSuite, Interruption, TlsSupport, TlsVersion, UnfinishedVersion, VersionSupport,
};
fn clocks() -> Clocks {
Clocks {
baseline: SystemTime::UNIX_EPOCH,
current: SystemTime::UNIX_EPOCH,
expiry_threshold: Duration::from_secs(30 * 24 * 60 * 60),
}
}
fn port(state: PortState) -> Port {
Port::new(443, Protocol::Tcp, state)
}
fn finding(title: &str) -> Finding {
Finding::new(
DetectionId::new("audit", Version::new(1, 0, 0), "hash").expect("a detection id"),
title,
Severity::High,
Confidence::Certain,
DetectionClass::Passive,
)
.expect("a titled finding")
}
type Moved<'a> = (
&'a [Finding],
&'a [Finding],
&'a [Finding],
&'a [Reassessment],
);
fn findings_change(changes: &[PortChange]) -> Option<Moved<'_>> {
changes.iter().find_map(|change| match change {
PortChange::Findings {
appeared,
resolved,
unsettled,
reassessed,
} => Some((
appeared.as_slice(),
resolved.as_slice(),
unsettled.as_slice(),
reassessed.as_slice(),
)),
_ => None,
})
}
#[test]
fn an_endpoint_that_did_not_move_reports_nothing() {
let before = port(PortState::Open);
let after = port(PortState::Open);
assert!(changes_between(Some(&before), Some(&after), &clocks()).is_empty());
}
#[test]
fn a_state_change_is_reported() {
let before = port(PortState::Open);
let after = port(PortState::Closed);
let changes = changes_between(Some(&before), Some(&after), &clocks());
assert!(changes.iter().any(|change| matches!(
change,
PortChange::State(state)
if state.before == PortState::Open && state.after == PortState::Closed
)));
}
#[test]
fn a_finding_that_appeared_on_the_endpoint_is_reported() {
let before = port(PortState::Open);
let mut after = port(PortState::Open);
after.add_finding(finding("Weak cipher"));
let changes = changes_between(Some(&before), Some(&after), &clocks());
let (appeared, resolved, _, _) = findings_change(&changes).expect("a findings change");
assert_eq!(appeared.len(), 1);
assert_eq!(appeared[0].title(), "Weak cipher");
assert!(resolved.is_empty());
}
#[test]
fn a_finding_that_went_away_from_the_endpoint_is_reported_as_resolved() {
let mut before = port(PortState::Open);
before.add_finding(finding("Weak cipher"));
let after = port(PortState::Open);
let changes = changes_between(Some(&before), Some(&after), &clocks());
let (appeared, resolved, _, _) = findings_change(&changes).expect("a findings change");
assert!(appeared.is_empty());
assert_eq!(resolved.len(), 1);
}
fn enumerated(support: TlsSupport) -> Port {
let findings = support.findings();
let mut port = port(PortState::Open).with_security(Security::new().with_support(support));
for finding in findings {
port.add_finding(finding);
}
port
}
fn ten_accepted() -> TlsSupport {
TlsSupport::new().accepting(VersionSupport::new(
TlsVersion::Tls10,
vec![CipherSuite::from_code(0x002F).expect("a registered suite")],
vec![],
))
}
fn titles(findings: &[Finding]) -> Vec<&str> {
findings.iter().map(Finding::title).collect()
}
#[test]
fn a_finding_a_cut_short_walk_did_not_get_back_to_is_not_resolved() {
let before = enumerated(ten_accepted());
let after = enumerated(TlsSupport::new().leaving_unfinished(UnfinishedVersion::new(
TlsVersion::Tls10,
Interruption::Stopped,
)));
assert!(
titles(&before.findings().cloned().collect::<Vec<_>>())
.contains(&"TLSv1.0 is still accepted"),
"the baseline's walk draws the claim this is about"
);
let changes = changes_between(Some(&before), Some(&after), &clocks());
let (_, resolved, unsettled, _) = findings_change(&changes).expect("a findings change");
assert!(
resolved.is_empty(),
"a walk that never finished reported {:?} resolved",
titles(resolved)
);
assert_eq!(
titles(unsettled),
titles(&before.findings().cloned().collect::<Vec<_>>()),
"every claim the baseline drew from TLS 1.0 is said to be unsettled"
);
}
#[test]
fn a_finding_a_finished_walk_refuted_is_resolved() {
let before = enumerated(ten_accepted());
let after = enumerated(TlsSupport::new().accepting(VersionSupport::new(
TlsVersion::Tls13,
vec![CipherSuite::from_code(0x1301).expect("a registered suite")],
vec![],
)));
let changes = changes_between(Some(&before), Some(&after), &clocks());
let (_, resolved, unsettled, _) = findings_change(&changes).expect("a findings change");
assert!(unsettled.is_empty(), "{:?}", titles(unsettled));
assert!(titles(resolved).contains(&"TLSv1.0 is still accepted"));
}
fn presenting(fingerprint: &str) -> Port {
let certificate = CertificateInfo::new(
"www.example.test",
"www.example.test",
SystemTime::UNIX_EPOCH,
SystemTime::UNIX_EPOCH + Duration::from_secs(365 * 24 * 60 * 60),
fingerprint,
)
.with_public_key("RSA", 2048);
let findings = certificate.findings(SystemTime::UNIX_EPOCH);
let mut port = port(PortState::Open).with_security(
Security::new()
.with_tls_version("TLSv1.3")
.with_certificate(certificate),
);
for finding in findings {
port.add_finding(finding);
}
port
}
#[test]
fn a_posture_finding_the_current_scan_saw_no_certificate_for_is_not_resolved() {
let before = presenting("aaaa");
let unparsed =
port(PortState::Open).with_security(Security::new().with_tls_version("TLSv1.3"));
assert_eq!(
titles(&before.findings().cloned().collect::<Vec<_>>()),
["TLS certificate is self-signed"],
"the baseline's certificate draws the claim this is about"
);
for after in [port(PortState::Open), unparsed] {
let changes = changes_between(Some(&before), Some(&after), &clocks());
assert!(
changes.iter().any(|change| matches!(
change,
PortChange::Security(SecurityChange::Certificate(
CertificateChange::Withdrawn(_)
))
)),
"the certificate's absence is still reported as such"
);
let (_, resolved, unsettled, _) = findings_change(&changes).expect("a findings change");
assert!(
resolved.is_empty(),
"a scan shown no certificate reported {:?} resolved",
titles(resolved)
);
assert_eq!(titles(unsettled), ["TLS certificate is self-signed"]);
}
}
#[test]
fn a_posture_finding_the_current_scan_was_shown_another_certificate_for_is_resolved() {
let before = presenting("aaaa");
let after = port(PortState::Open).with_security(
Security::new()
.with_tls_version("TLSv1.3")
.with_certificate(
CertificateInfo::new(
"www.example.test",
"Example CA",
SystemTime::UNIX_EPOCH,
SystemTime::UNIX_EPOCH + Duration::from_secs(365 * 24 * 60 * 60),
"bbbb",
)
.with_public_key("RSA", 2048),
),
);
let changes = changes_between(Some(&before), Some(&after), &clocks());
let (_, resolved, unsettled, _) = findings_change(&changes).expect("a findings change");
assert!(unsettled.is_empty(), "{:?}", titles(unsettled));
assert_eq!(titles(resolved), ["TLS certificate is self-signed"]);
}
fn correlated() -> Port {
const CPE: &str = "cpe:/a:apache:http_server:2.4.49";
let mut port = port(PortState::Open);
port.set_service(
Service::new("http", 90)
.with_product("Apache httpd")
.with_version("2.4.49")
.with_cpe(CPE),
);
port.add_finding(
finding("Apache httpd 2.4.49: path traversal")
.with_reference(crate::model::finding::Reference::Cve(
"CVE-2021-41773".into(),
))
.with_cpe(CPE),
);
port
}
#[test]
fn a_correlation_the_current_scan_identified_nothing_to_test_is_not_resolved() {
let before = correlated();
let mut labelled = port(PortState::Open);
labelled.set_service(Service::new("http", 0));
let mut unversioned = port(PortState::Open);
unversioned.set_service(Service::new("http", 90).with_product("Apache httpd"));
for (case, after) in [
("no service at all", port(PortState::Open)),
("a port-number label", labelled),
("the same software without a version", unversioned),
] {
let changes = changes_between(Some(&before), Some(&after), &clocks());
let (_, resolved, unsettled, _) = findings_change(&changes).expect("a findings change");
assert!(
resolved.is_empty(),
"{case}: reported {:?} resolved",
titles(resolved)
);
assert_eq!(
titles(unsettled),
["Apache httpd 2.4.49: path traversal"],
"{case}"
);
}
}
#[test]
fn a_correlation_a_newer_identification_no_longer_backs_is_resolved() {
let before = correlated();
let mut upgraded = port(PortState::Open);
upgraded.set_service(
Service::new("http", 90)
.with_product("Apache httpd")
.with_version("2.4.58")
.with_cpe("cpe:/a:apache:http_server:2.4.58"),
);
let mut replaced = port(PortState::Open);
replaced.set_service(Service::new("http", 90).with_product("nginx"));
for (case, after) in [("upgraded", upgraded), ("replaced", replaced)] {
let changes = changes_between(Some(&before), Some(&after), &clocks());
let (_, resolved, unsettled, _) = findings_change(&changes).expect("a findings change");
assert!(unsettled.is_empty(), "{case}: {:?}", titles(unsettled));
assert_eq!(
titles(resolved),
["Apache httpd 2.4.49: path traversal"],
"{case}"
);
}
}
#[test]
fn an_endpoint_present_on_one_side_only_reports_no_field_changes() {
let only = port(PortState::Open);
assert!(changes_between(Some(&only), None, &clocks()).is_empty());
assert!(changes_between(None, Some(&only), &clocks()).is_empty());
}
}