use std::time::{Instant, SystemTime};
use crate::config::ZondConfig;
use crate::model::ip::range::IpRange;
use crate::model::ip::set::IpSet;
use crate::report::{
LivenessSkip, PhaseParts, ScanKind, ScanPhase, ScanReport, ScanSettings, TargetScope,
};
use crate::scanner::orchestrator::Liveness;
use crate::scanner::session::ScanContext;
use crate::system::privilege::Privilege;
pub struct PhaseRecorder {
kind: ScanKind,
started_at: SystemTime,
started: Instant,
privilege: Privilege,
targets: TargetScope,
settings: ScanSettings,
liveness_skipped: Option<LivenessSkip>,
}
impl PhaseRecorder {
pub fn start(
kind: ScanKind,
privilege: Privilege,
targets: TargetScope,
cfg: &ZondConfig,
) -> Self {
Self {
kind,
started_at: SystemTime::now(),
started: Instant::now(),
privilege,
targets,
settings: ScanSettings::from(cfg),
liveness_skipped: None,
}
}
#[must_use]
pub fn skipping_liveness(mut self, why: LivenessSkip) -> Self {
self.liveness_skipped = Some(why);
self
}
pub fn finish(self, ctx: &ScanContext) -> ScanReport {
self.close(ctx).0
}
pub(super) fn close(self, ctx: &ScanContext) -> (ScanReport, Option<Liveness>) {
let mut targets = self.targets;
targets.record_sweeps(ctx.take_swept_links());
let unroutable = ctx.take_unroutable();
let heard_nothing = ctx.take_silent();
let silent = match (self.kind, self.liveness_skipped) {
(ScanKind::PortScan, Some(LivenessSkip::PortsNoDearer)) => ranges_of(&heard_nothing),
_ => Vec::new(),
};
let unfinished = ctx.take_undecided();
let liveness =
(self.kind == ScanKind::Discovery).then(|| Liveness::found(ctx, heard_nothing));
let undecided = match (&liveness, self.kind, self.liveness_skipped) {
(Some(liveness), _, _) => liveness.undecided(&targets, &unroutable),
(None, ScanKind::PortScan, Some(LivenessSkip::PortsNoDearer)) => ranges_of(&unfinished),
_ => Vec::new(),
};
let phase = ScanPhase::from_parts(PhaseParts {
kind: self.kind,
started_at: self.started_at,
elapsed: self.started.elapsed(),
privilege: Some(self.privilege),
targets,
settings: self.settings,
failures: ctx.take_failures(),
refusals: ctx.take_refusals(),
unroutable,
timed_out: ctx.take_timed_out(),
icmp_rate_limited: ctx.take_icmp_rate_limited(),
reached_by_connect: match self.privilege {
Privilege::Raw => ctx.take_reached_by_connect(),
Privilege::Connect => {
let _ = ctx.take_reached_by_connect();
Vec::new()
}
},
undecided,
liveness_skipped: self.liveness_skipped,
silent,
probes: ctx.take_probe_stats(),
origin: None,
attachments: ctx.take_attachments(),
});
let hosts = ctx.store.iter().map(|entry| entry.value().clone());
(ScanReport::new(phase, hosts), liveness)
}
}
fn ranges_of(set: &IpSet) -> Vec<IpRange> {
let v4 = set.v4().iter().copied().map(IpRange::V4);
let v6 = set.v6().iter().copied().map(IpRange::V6);
v4.chain(v6).collect()
}
#[cfg(test)]
mod tests {
use super::*;
use crate::model::exclusion::Exclusions;
use crate::model::host::HostStatus;
use crate::model::ip::set::IpSet;
use crate::report::{BUCKET_BOUNDS_MS, ProbeStats, Refusal, ScannerKind, StopReason};
use crate::scanner::session::ScanSession;
fn scope() -> TargetScope {
let mut targets = IpSet::from_str("203.0.113.1-203.0.113.2").expect("a valid range");
TargetScope::from_ip_set(&mut targets, &Exclusions::none())
}
#[test]
fn a_refusal_reaches_the_report_as_a_refusal_and_not_as_a_failure() {
let cfg = ZondConfig::default();
let (_session, ctx) = ScanSession::new();
let recorder = PhaseRecorder::start(ScanKind::PortScan, Privilege::Connect, scope(), &cfg);
ctx.record_refusal(Refusal::new(
ScannerKind::SctpPort,
"no unprivileged init probe exists",
));
ctx.record_failure(ScannerKind::Local, "the capture would not open".to_string());
let report = recorder.finish(&ctx);
let phase = &report.phases()[0];
assert_eq!(phase.refusals().len(), 1, "the refusal is its own kind");
assert_eq!(phase.refusals()[0].scanner(), ScannerKind::SctpPort);
assert_eq!(
phase.failures().len(),
1,
"and the failure is still a failure"
);
assert_eq!(phase.failures()[0].scanner(), ScannerKind::Local);
}
#[test]
fn a_phase_takes_its_refusals_rather_than_copying_them() {
let cfg = ZondConfig::default();
let (_session, ctx) = ScanSession::new();
ctx.record_refusal(Refusal::new(ScannerKind::SctpPort, "no init probe"));
let first = PhaseRecorder::start(ScanKind::Discovery, Privilege::Connect, scope(), &cfg)
.finish(&ctx);
let second = PhaseRecorder::start(ScanKind::PortScan, Privilege::Connect, scope(), &cfg)
.finish(&ctx);
assert_eq!(first.phases()[0].refusals().len(), 1);
assert!(second.phases()[0].refusals().is_empty());
}
#[test]
fn the_same_refusal_filed_twice_is_recorded_once() {
let (_session, ctx) = ScanSession::new();
let refusal = Refusal::new(ScannerKind::Local, "too large to walk");
ctx.record_refusal(refusal.clone());
ctx.record_refusal(refusal);
assert_eq!(ctx.refusals_snapshot().len(), 1);
}
use std::net::{IpAddr, Ipv4Addr};
use std::str::FromStr;
use std::time::Duration;
fn ip(last: u8) -> IpAddr {
IpAddr::V4(Ipv4Addr::new(203, 0, 113, last))
}
#[test]
fn an_unroutable_address_is_recorded_without_making_the_scan_partial() {
let cfg = ZondConfig::default();
let (_session, ctx) = crate::scanner::session::ScanSession::new();
let mut targets = IpSet::from_str("203.0.113.1-203.0.113.2").expect("a valid range");
let scope = TargetScope::from_ip_set(&mut targets, &Exclusions::none());
let recorder = PhaseRecorder::start(ScanKind::Discovery, Privilege::Connect, scope, &cfg);
for address in [ip(1), ip(2)] {
ctx.settle_address(address, crate::journal::settle::Settled::Exhausted);
}
let unreachable: IpAddr = "2001:db8::1".parse().expect("literal");
ctx.record_unroutable(unreachable);
ctx.record_unroutable(unreachable);
let report = recorder.finish(&ctx);
assert_eq!(report.phases()[0].unroutable(), [unreachable]);
assert!(
!report.is_partial(),
"no strategy failed; that address is simply not reachable from here"
);
assert_eq!(report.failures().count(), 0);
}
#[test]
fn a_self_orchestrated_scan_can_close_its_own_phase() {
let cfg = ZondConfig::default();
let (_session, ctx) = crate::scanner::session::ScanSession::new();
let mut targets = IpSet::from_str("203.0.113.1-203.0.113.4").expect("a valid range");
let scope = TargetScope::from_ip_set(&mut targets, &Exclusions::none());
let recorder = PhaseRecorder::start(ScanKind::Discovery, Privilege::Connect, scope, &cfg);
ctx.update_host(ip(1), |host| host.set_status(HostStatus::Up));
ctx.record_failure(ScannerKind::Local, "eth0: no address".into());
let report = recorder.finish(&ctx);
assert_eq!(report.host_count(), 1);
assert_eq!(report.phases()[0].targets().addresses(), 4);
assert!(report.is_partial(), "the failure has to reach the record");
assert_eq!(report.failures().count(), 1);
}
#[test]
fn probe_stats_filed_during_a_scan_land_in_its_phase() {
let (_session, ctx) = crate::scanner::session::ScanSession::new();
let recorder = PhaseRecorder::start(
ScanKind::Discovery,
Privilege::Raw,
TargetScope::from_ip_set(&mut IpSet::new(), &Exclusions::none()),
&ZondConfig::default(),
);
ctx.record_probe_stats(ProbeStats {
window: None,
scanner: ScannerKind::Routed,
targets: 256,
stop_reason: StopReason::AllResponded,
elapsed: Duration::from_millis(40),
sends_attempted: 300,
sends_failed: 0,
sends_witnessed: 0,
segments_seen: 250,
segments_off_target: 1,
replies_without_rtt: 2,
hosts_found: 9,
answered_on: [7, 2, 0, 0, 0, 0],
answered_unattributed: 0,
first_reply: Some(Duration::from_millis(1)),
last_reply: Some(Duration::from_millis(30)),
found_at: [0; BUCKET_BOUNDS_MS.len() + 1],
capture: None,
});
let report = recorder.finish(&ctx);
let stats = report.phases()[0].probe_stats();
assert_eq!(stats.len(), 1);
assert_eq!(stats[0].scanner(), ScannerKind::Routed);
assert_eq!(stats[0].hosts_found(), 9);
assert_eq!(stats[0].answered_on()[1], 2);
assert_eq!(report.probe_stats().count(), 1);
assert!(ctx.take_probe_stats().is_empty());
}
#[test]
fn what_a_raw_phase_reached_by_connect_is_recorded_and_a_connect_phase_ignores_it() {
let cfg = ZondConfig::default();
let (_session, ctx) = ScanSession::new();
let addresses = |list: &[&str]| {
let mut set = IpSet::new();
for address in list {
set.insert(address.parse().expect("a literal"));
}
set
};
let raw = PhaseRecorder::start(ScanKind::PortScan, Privilege::Raw, scope(), &cfg);
ctx.record_reached_by_connect(&addresses(&["127.0.0.1", "192.0.2.8"]));
ctx.record_reached_by_connect(&addresses(&["127.0.0.1", "192.0.2.9"]));
let report = raw.finish(&ctx);
let reached: Vec<String> = report.phases()[0]
.reached_by_connect()
.iter()
.map(|range| format!("{}-{}", range.start_addr(), range.end_addr()))
.collect();
assert_eq!(
reached,
["127.0.0.1-127.0.0.1", "192.0.2.8-192.0.2.9"],
"merged, ascending, and each address once"
);
let connect = PhaseRecorder::start(ScanKind::PortScan, Privilege::Connect, scope(), &cfg);
ctx.record_reached_by_connect(&addresses(&["127.0.0.1"]));
let report = connect.finish(&ctx);
assert!(
report.phases()[0].reached_by_connect().is_empty(),
"a connect phase reached everything this way, and says so once"
);
let after = PhaseRecorder::start(ScanKind::PortScan, Privilege::Raw, scope(), &cfg);
assert!(
after.finish(&ctx).phases()[0]
.reached_by_connect()
.is_empty(),
"and what the connect phase was handed did not carry over"
);
}
#[test]
fn a_discovery_phase_names_the_addresses_it_reached_no_verdict_on() {
use crate::journal::settle::Settled;
let cfg = ZondConfig::default();
let (_session, ctx) = ScanSession::new();
let mut targets = IpSet::from_str("203.0.113.1-203.0.113.4").expect("a valid range");
let scope = TargetScope::from_ip_set(&mut targets, &Exclusions::none());
let recorder = PhaseRecorder::start(ScanKind::Discovery, Privilege::Connect, scope, &cfg);
ctx.update_host(ip(1), |host| host.set_status(HostStatus::Up));
ctx.settle_address(ip(2), Settled::Exhausted);
ctx.record_unroutable(ip(3));
let report = recorder.finish(&ctx);
let undecided: Vec<String> = report.phases()[0]
.undecided()
.iter()
.map(|range| format!("{}-{}", range.start_addr(), range.end_addr()))
.collect();
assert_eq!(undecided, ["203.0.113.4-203.0.113.4"]);
}
#[test]
fn a_port_phase_standing_in_for_liveness_names_what_was_filed_silent() {
use crate::model::ip::scoped::ScopedIp;
let cfg = ZondConfig::default();
let (session, ctx) = ScanSession::new();
let recorder = PhaseRecorder::start(ScanKind::PortScan, Privilege::Connect, scope(), &cfg)
.skipping_liveness(LivenessSkip::PortsNoDearer);
ctx.update_host(ip(1), |host| host.set_status(HostStatus::Up));
ctx.update_host(ip(2), |_| {});
ctx.forget_silent(vec![ScopedIp::from(ip(2))]);
let report = recorder.finish(&ctx);
let silent: Vec<String> = report.phases()[0]
.silent()
.iter()
.map(|range| format!("{}-{}", range.start_addr(), range.end_addr()))
.collect();
assert_eq!(silent, ["203.0.113.2-203.0.113.2"]);
assert!(report.host(&ip(2)).is_none(), "a silent address is no host");
assert!(
!session.hosts().contains(ip(2)),
"and the live store agrees with the report"
);
assert!(report.host(&ip(1)).is_some());
let (_session, ctx) = ScanSession::new();
let recorder = PhaseRecorder::start(ScanKind::PortScan, Privilege::Connect, scope(), &cfg)
.skipping_liveness(LivenessSkip::AssumeUp);
ctx.settle_address(ip(2), crate::journal::settle::Settled::Exhausted);
assert!(recorder.finish(&ctx).phases()[0].silent().is_empty());
}
#[test]
fn a_port_phase_standing_in_for_liveness_names_what_it_left_undecided() {
use crate::model::ip::scoped::ScopedIp;
let cfg = ZondConfig::default();
let (session, ctx) = ScanSession::new();
let recorder = PhaseRecorder::start(ScanKind::PortScan, Privilege::Connect, scope(), &cfg)
.skipping_liveness(LivenessSkip::PortsNoDearer);
ctx.update_host(ip(1), |host| host.set_status(HostStatus::Up));
ctx.update_host(ip(3), |_| {});
ctx.forget_undecided(vec![ScopedIp::from(ip(3))]);
let report = recorder.finish(&ctx);
let undecided: Vec<String> = report.phases()[0]
.undecided()
.iter()
.map(|range| format!("{}-{}", range.start_addr(), range.end_addr()))
.collect();
assert_eq!(undecided, ["203.0.113.3-203.0.113.3"]);
assert!(
report.host(&ip(3)).is_none(),
"an undecided address is no host"
);
assert!(!session.hosts().contains(ip(3)));
assert!(report.host(&ip(1)).is_some());
assert!(report.is_partial(), "and the report says it left one open");
let (_session, ctx) = ScanSession::new();
let ports = PhaseRecorder::start(ScanKind::PortScan, Privilege::Connect, scope(), &cfg)
.skipping_liveness(LivenessSkip::AssumeUp);
ctx.forget_undecided(vec![ScopedIp::from(ip(3))]);
assert!(ports.finish(&ctx).phases()[0].undecided().is_empty());
let next = PhaseRecorder::start(ScanKind::PortScan, Privilege::Connect, scope(), &cfg)
.skipping_liveness(LivenessSkip::PortsNoDearer);
assert!(next.finish(&ctx).phases()[0].undecided().is_empty());
}
#[test]
fn only_a_discovery_phase_names_undecided_addresses_and_silence_does_not_carry() {
use crate::journal::settle::Settled;
let cfg = ZondConfig::default();
let (_session, ctx) = ScanSession::new();
let ports = PhaseRecorder::start(ScanKind::PortScan, Privilege::Connect, scope(), &cfg);
ctx.settle_address(ip(1), Settled::Exhausted);
assert!(ports.finish(&ctx).phases()[0].undecided().is_empty());
let sweep = PhaseRecorder::start(ScanKind::Discovery, Privilege::Connect, scope(), &cfg);
assert_eq!(
sweep.finish(&ctx).phases()[0].undecided().len(),
1,
"the port phase took the silence it was handed, so the sweep decided nothing"
);
}
}