zond_engine/report.rs
1// Copyright (c) 2026 Erik Lening (hollowpointer) and Contributors
2//
3// This file is part of Zond Engine, licensed under the GNU Affero General
4// Public License, version 3 or later. See the LICENSE file for details, or
5// <https://www.gnu.org/licenses/agpl-3.0.html>.
6//
7// SPDX-License-Identifier: AGPL-3.0-or-later
8
9//! # Scan Reports
10//!
11//! The finished record of a scan: what was asked for, what came back, what went
12//! wrong on the way, and under which settings.
13//!
14//! During a scan a caller watches [`ScanSession`](crate::scanner::session::ScanSession),
15//! a live store and event stream that keep no history. A [`ScanReport`] is produced once
16//! the scan is over and answers the questions asked afterwards: how long the sweep
17//! took, whether a strategy failed part way, how many addresses were in scope, which
18//! retry budget produced these hosts.
19//!
20//! "Nine hosts on a /24" means one thing after a
21//! [`Thorough`](crate::config::ScanEffort::Thorough) privileged sweep and another after
22//! an unprivileged connect fallback that lost its routed scanner to a permissions
23//! error. Only the report tells them apart.
24//!
25//! ## Phases
26//!
27//! Discovery and port scanning are separate calls, but a caller running both describes
28//! one job. A report holds a list of [`ScanPhase`] records, and [`ScanReport::merge`]
29//! folds the second call into the first: hosts merge by [`Host::merge`] and phases
30//! append in the order they ran.
31//!
32//! ## Findings and instrumentation
33//!
34//! Hosts and ports are findings *about the network*. The [`ProbeStats`] a raw scanner
35//! files are measurements *about the scan* (probes sent, segments received, why the
36//! loop stopped) that bound how far the findings can be trusted. A sweep that stopped
37//! on [`StopReason::DeadlineExpired`] while replies were still arriving found fewer
38//! hosts than the network holds, and the host list cannot show it.
39//!
40//! ## Stored and derived
41//!
42//! Only measurements are stored. Counts such as hosts up, open ports and services
43//! identified are computed from the hosts by [`ScanReport::summary`], so they cannot
44//! drift.
45//!
46//! Hosts are held in a [`BTreeMap`] keyed by primary IP, so two scans of the
47//! same network serialize in the same order and their outputs can be diffed.
48
49use std::borrow::Cow;
50use std::collections::BTreeMap;
51use std::fmt;
52use std::net::IpAddr;
53use std::sync::Arc;
54use std::time::{Duration, SystemTime};
55
56use crate::config::DetectionEnvelope;
57use crate::config::RetryConfig;
58use crate::config::{IdleScan, OsDetection, ServiceDetection, ZondConfig};
59use crate::evasion::EvasionProfile;
60use crate::model::capture::CaptureCounts;
61use crate::model::exclusion::Exclusions;
62use crate::model::host::{Host, HostStatus};
63use crate::model::ip::range::{IpRange, Ipv4Range, Ipv6Range};
64use crate::model::ip::scoped::{ScopedIp, Zone};
65use crate::model::ip::set::IpSet;
66use crate::model::mac::MacAddr;
67use crate::model::port::{PortSet, PortState, Protocol};
68use crate::model::target::{TargetMap, TargetSet};
69use crate::model::technique::{SctpScanTechnique, TcpScanTechnique};
70use crate::system::privilege::Privilege;
71use crate::transport::probe::SendMode;
72
73/// The version of the engine that produced a report.
74pub const ENGINE_VERSION: &str = env!("CARGO_PKG_VERSION");
75
76// --------------------------------------------------------------------------
77// What a scan was asked to do
78// --------------------------------------------------------------------------
79//
80// The request as the report records it: range, ports, technique, patience.
81
82/// Which of the two scan phases a [`ScanPhase`] records.
83///
84/// The engine's entry points ([`discover`](crate::scanner::discover),
85/// [`scan`](crate::scanner::scan), and listening), not the strategies each spawns; see
86/// [`ScannerKind`] for those.
87#[non_exhaustive]
88#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
89pub enum ScanKind {
90 /// Establishing which hosts in a target range are alive.
91 Discovery,
92 /// Classifying the ports of a known set of hosts.
93 PortScan,
94 /// Reading what a link already carries, having sent nothing.
95 ///
96 /// Covers no address; see [`TargetScope::listening_on`]. It can raise a claim but
97 /// never lower one, since silence proves nothing when nothing was sent.
98 Listen,
99}
100
101impl ScanKind {
102 /// Every phase kind this build knows, in declaration order.
103 ///
104 /// The export conformance suite checks this against the published schema.
105 pub const ALL: &'static [Self] = &[Self::Discovery, Self::PortScan, Self::Listen];
106}
107
108impl fmt::Display for ScanKind {
109 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
110 match self {
111 ScanKind::Discovery => write!(f, "discovery"),
112 ScanKind::PortScan => write!(f, "port scan"),
113 ScanKind::Listen => write!(f, "listen"),
114 }
115 }
116}
117
118/// Why a port phase ran with no liveness pass in front of it.
119///
120/// A port scan ordinarily runs a liveness pass first, recorded as its own
121/// [`Discovery`](ScanKind::Discovery) phase. A phase carrying one of these ran without
122/// it. The first two probed every address on trust; the third read the probes' answers
123/// as the liveness answer, since asking first would have cost as much.
124#[non_exhaustive]
125#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
126pub enum LivenessSkip {
127 /// The caller declined the pass, and asked for every address to be probed
128 /// as a host that is there.
129 AssumeUp,
130 /// The scan was an [idle scan](ScanSettings::idle_scan), which forges every
131 /// probe from its zombie, and a liveness pass would have been this host
132 /// asking the target directly.
133 IdleScan,
134 /// The scan named no more ports per address than the pass would have asked. An
135 /// answer on any port found a host, and an address that answered on none is in the
136 /// phase's [`silent`](ScanPhase::silent) list.
137 PortsNoDearer,
138}
139
140impl LivenessSkip {
141 /// Every reason this build records, in declaration order. Checked against the
142 /// published schema, as [`ScanKind::ALL`] is.
143 pub const ALL: &'static [Self] = &[Self::AssumeUp, Self::IdleScan, Self::PortsNoDearer];
144}
145
146/// A pass a scan runs over what its probes found, named for what a stop can
147/// cut short.
148///
149/// The passes that run after a phase's probes, each asking something the caller chose:
150/// services, detections, TLS acceptance, operating system, route, filter, IP protocols.
151/// A scan stopped after its probes leaves unfinished passes with nothing to say, and the
152/// report names them so the ports do not read as having nothing more to tell. See
153/// [`ScanPhase::passes_cut`].
154///
155/// In the order a scan runs them.
156#[non_exhaustive]
157#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
158pub enum Pass {
159 /// Identifying what is listening behind each open port.
160 Services,
161 /// Running the detection corpus over the services identified.
162 Detections,
163 /// Asking each TLS port which versions and suites it accepts.
164 Tls,
165 /// Asking each host what it runs, beyond what its replies already said.
166 Os,
167 /// Tracing the path to each host.
168 Traceroute,
169 /// Characterising the filter in front of each host.
170 Filters,
171 /// Asking each host which IP protocols its stack takes.
172 IpProtocols,
173}
174
175impl Pass {
176 /// Every pass this build names, in the order a scan runs them. Checked against the
177 /// published schema, as [`ScanKind::ALL`] is.
178 pub const ALL: &'static [Self] = &[
179 Self::Services,
180 Self::Detections,
181 Self::Tls,
182 Self::Os,
183 Self::Traceroute,
184 Self::Filters,
185 Self::IpProtocols,
186 ];
187}
188
189impl fmt::Display for Pass {
190 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
191 f.write_str(match self {
192 Pass::Services => "service detection",
193 Pass::Detections => "detections",
194 Pass::Tls => "TLS enumeration",
195 Pass::Os => "OS detection",
196 Pass::Traceroute => "traceroute",
197 Pass::Filters => "filter characterisation",
198 Pass::IpProtocols => "IP protocol scan",
199 })
200 }
201}
202
203/// Which ports a phase walked, and whether it walked the same ones everywhere.
204///
205/// A scope records the addresses a phase covered; for a port scan, an address is
206/// covered *for some ports*, and this says which.
207///
208/// [`Every`](Self::Every) against [`Mixed`](Self::Mixed): `192.0.2.0/24:80,443`
209/// alongside `198.51.100.0/24:8080` has no single set true of every address, so the
210/// union is labelled as one, and a consumer will not conclude `192.0.2.5` was probed
211/// on 8080.
212///
213/// [`NoPorts`](Self::NoPorts) against [`Unstated`](Self::Unstated): a discovery sweep
214/// walked no ports, which is a fact; a record that does not say is an absence of one.
215/// This engine never builds `Unstated`; reports from other tools, or records without
216/// the field, read back as it.
217#[non_exhaustive]
218#[derive(Debug, Clone, PartialEq, Eq, Default)]
219pub enum PortScope {
220 /// The record does not say which ports were walked.
221 ///
222 /// Nothing may be concluded about any endpoint. The default, for a record that does
223 /// not carry this field.
224 #[default]
225 Unstated,
226 /// The phase paired no ports with its addresses, which is what a discovery
227 /// sweep does. Its probes are the strategy's choice rather than the
228 /// caller's, and no endpoint was probed.
229 NoPorts,
230 /// Every address the phase walked was walked for these ports.
231 ///
232 /// The ordinary case for a port scan, and the only variant from which a consumer
233 /// may conclude that an endpoint of a covered address was probed.
234 Every(PortSet),
235 /// Addresses were walked for differing sets of ports, and this is their
236 /// union.
237 ///
238 /// A port here was walked for at least one address, not necessarily any given one.
239 /// A port *not* here was walked for none.
240 Mixed(PortSet),
241}
242
243impl PortScope {
244 /// The ports the phase walked, over all of its addresses.
245 ///
246 /// `None` where there are none to report or none recorded. Read this to
247 /// describe what a scan reached; read [`covers`](Self::covers) to ask about
248 /// one endpoint.
249 pub fn ports(&self) -> Option<&PortSet> {
250 match self {
251 PortScope::Unstated | PortScope::NoPorts => None,
252 PortScope::Every(ports) | PortScope::Mixed(ports) => Some(ports),
253 }
254 }
255
256 /// Whether the phase walked `port` on `protocol`, for every address it
257 /// covered.
258 ///
259 /// `None` means the record cannot say (no ports recorded, or a mixed scope including
260 /// this port). `Some(false)` is a real negative.
261 pub fn covers(&self, port: u16, protocol: Protocol) -> Option<bool> {
262 match self {
263 PortScope::Unstated => None,
264 PortScope::NoPorts => Some(false),
265 PortScope::Every(ports) => Some(ports.contains(port, protocol)),
266 PortScope::Mixed(ports) => {
267 if ports.contains(port, protocol) {
268 None
269 } else {
270 Some(false)
271 }
272 }
273 }
274 }
275
276 /// The scope of a set of units, which is [`Every`](Self::Every) when they
277 /// agree and [`Mixed`](Self::Mixed) when they do not.
278 fn of<'a>(units: impl Iterator<Item = &'a PortSet>) -> Self {
279 let mut units = units;
280 let Some(first) = units.next().cloned() else {
281 return PortScope::NoPorts;
282 };
283
284 let mut united = first.clone();
285 let mut agreed = true;
286 for ports in units {
287 agreed &= *ports == first;
288 united = united.union(ports);
289 }
290
291 if united.is_empty() {
292 PortScope::NoPorts
293 } else if agreed {
294 PortScope::Every(united)
295 } else {
296 PortScope::Mixed(united)
297 }
298 }
299}
300
301/// What a phase was asked to cover, and what it was forbidden to.
302///
303/// The ranges are the merged form the engine iterated, so `addresses` counts distinct
304/// addresses and a report saying a sweep covered 254 hosts can be trusted.
305///
306/// [`ranges`](Self::ranges) is what was walked after the exclusion policy, and
307/// [`excluded`](Self::excluded) is the policy. Together they make the report evidence
308/// of scope: no host in it may fall inside the excluded ranges.
309#[derive(Debug, Clone, PartialEq, Eq)]
310pub struct TargetScope {
311 ranges: Vec<IpRange>,
312 links: Vec<Zone>,
313 /// Links whose traffic was read without anything being sent to them.
314 ///
315 /// Separate from [`links`](Self::links), which means *swept*: everything on the link
316 /// had to answer, so a missing host was not there. A machine that said nothing while
317 /// a listener ran may still be there.
318 ///
319 /// Recorded to show where the phase stood; never counted as coverage.
320 listened: Vec<Zone>,
321 addresses: u128,
322 probes: Option<u128>,
323 ports: PortScope,
324 protocols: Vec<Protocol>,
325 excluded: Vec<IpRange>,
326 withheld: u128,
327}
328
329impl TargetScope {
330 /// The scope of a discovery sweep, which has no port dimension.
331 ///
332 /// Canonicalizes the set, so the recorded ranges are the merged ones the sweep
333 /// iterates.
334 ///
335 /// `ips` comes back with everything `exclusions` forbids removed, and the scope
336 /// records what that cost. Applying and recording are one call (hence `&mut`) so
337 /// neither can happen without the other.
338 ///
339 /// Pass [`Exclusions::none`] where no policy is in force.
340 pub fn from_ip_set(ips: &mut IpSet, exclusions: &Exclusions) -> Self {
341 let withheld = exclusions.withhold(ips);
342 ips.canonicalize();
343
344 let ranges = ip_set_ranges(ips);
345 let addresses = ips.len();
346
347 Self {
348 listened: Vec::new(),
349 ranges,
350 links: Vec::new(),
351 addresses,
352 probes: None,
353 ports: PortScope::NoPorts,
354 protocols: Vec::new(),
355 excluded: exclusions.ranges(),
356 withheld,
357 }
358 }
359
360 /// The scope of a phase that sent nothing and read what `links` carried.
361 ///
362 /// Covers no address: a listener sent nothing, so it can report no address as empty,
363 /// and a comparison will not read a quiet host as one that disappeared. The links
364 /// are recorded as [`listened`](Self::listened), not [`links`](Self::links).
365 ///
366 /// `exclusions` is recorded to show the policy; it is enforced where findings are
367 /// recorded.
368 pub fn listening_on(links: Vec<Zone>, exclusions: &Exclusions) -> Self {
369 Self {
370 ranges: Vec::new(),
371 links: Vec::new(),
372 listened: links,
373 addresses: 0,
374 probes: None,
375 ports: PortScope::NoPorts,
376 protocols: Vec::new(),
377 excluded: exclusions.ranges(),
378 withheld: 0,
379 }
380 }
381
382 /// The scope of a port scan, which pairs addresses with ports.
383 ///
384 /// `probes` counts address, port and protocol combinations, or is `None` when the
385 /// count overflows.
386 ///
387 /// `targets` comes back narrowed, as in [`from_ip_set`](Self::from_ip_set); a unit
388 /// left with no address is dropped.
389 pub fn from_target_map(targets: &mut TargetMap, exclusions: &Exclusions) -> Self {
390 let withheld = exclusions.withhold_targets(targets);
391
392 let mut ranges = Vec::new();
393 let mut protocols = Vec::new();
394 for unit in &targets.units {
395 ranges.extend(ip_set_ranges(unit.ips()));
396 for (_, protocol) in unit.ports().iter() {
397 if !protocols.contains(&protocol) {
398 protocols.push(protocol);
399 }
400 }
401 }
402 ranges.sort_by_key(|range| (range.start_addr(), range.end_addr()));
403 ranges.dedup();
404 protocols.sort();
405
406 let addresses = targets.gross_ips().unwrap_or(0);
407 let probes = targets.gross_targets().ok();
408 let ports = PortScope::of(targets.units.iter().map(TargetSet::ports));
409
410 Self {
411 listened: Vec::new(),
412 ranges,
413 links: Vec::new(),
414 addresses,
415 probes,
416 ports,
417 protocols,
418 excluded: exclusions.ranges(),
419 withheld,
420 }
421 }
422
423 /// The address ranges covered, in ascending order.
424 pub fn ranges(&self) -> &[IpRange] {
425 &self.ranges
426 }
427
428 /// How many distinct addresses were in scope.
429 pub fn addresses(&self) -> u128 {
430 self.addresses
431 }
432
433 /// How many address/port/protocol combinations were in scope, or `None` for
434 /// a discovery sweep and for a target set too large to count.
435 pub fn probes(&self) -> Option<u128> {
436 self.probes
437 }
438
439 /// The links this phase swept whole, by the interface each is on.
440 ///
441 /// A sweep of a local segment covers more than [`ranges`](Self::ranges): every IPv6
442 /// neighbour must answer an all-nodes solicitation, including hosts nobody could
443 /// name in advance.
444 ///
445 /// Recorded by interface, since `fe80::/64` in `ranges` would make
446 /// [`addresses`](Self::addresses) read eighteen quintillion.
447 ///
448 /// Empty for every port scan and every sweep of a routed range.
449 pub fn links(&self) -> &[Zone] {
450 &self.links
451 }
452
453 /// The links this phase read traffic from without probing them.
454 ///
455 /// Never coverage. See [`listening_on`](Self::listening_on).
456 pub fn listened(&self) -> &[Zone] {
457 &self.listened
458 }
459
460 /// Whether this phase swept the link a host was found on.
461 ///
462 /// Asked of the link, not the address: a host answering an all-nodes solicitation is
463 /// often keyed under a global address.
464 ///
465 /// `zone` is the interface the host was found on. A host with no zone was not found
466 /// on a link and is not claimed.
467 pub fn swept(&self, zone: Option<&Zone>) -> bool {
468 let Some(zone) = zone else {
469 return false;
470 };
471
472 self.links.iter().any(|link| link.name() == zone.name())
473 }
474
475 /// Records that this phase swept a link whole.
476 ///
477 /// Called once a phase is over, since which links were reached is only known then.
478 /// See [`PhaseRecorder::finish`](crate::scanner::recorder::PhaseRecorder::finish).
479 pub(crate) fn record_sweeps(&mut self, links: Vec<Zone>) {
480 for link in links {
481 if !self.links.iter().any(|held| held.name() == link.name()) {
482 self.links.push(link);
483 }
484 }
485 }
486
487 /// Records what this phase's policy withheld beyond the targets it was
488 /// handed: `machines`, the other addresses of a machine it names, which
489 /// the neighbour tables tied to it or which answered from its hardware
490 /// during the phase; and `neighbours`, the neighbour-table addresses it
491 /// kept from a sweep that would have taken them as candidates. See
492 /// [`Exclusions::hardware_in`](crate::model::exclusion::Exclusions::hardware_in).
493 ///
494 /// Called once a phase is over, like [`record_sweeps`](Self::record_sweeps). Both
495 /// join [`excluded`](Self::excluded). [`withheld`](Self::withheld) gains each
496 /// address not already counted: every neighbour kept from the sweep, and every
497 /// address heard from an excluded machine's hardware during the phase. Addresses
498 /// tied before the phase began were counted with the targets.
499 pub(crate) fn record_withheld(&mut self, machines: Vec<IpAddr>, neighbours: Vec<IpAddr>) {
500 let mut excluded = IpSet::new();
501 for range in self.excluded.drain(..) {
502 excluded.insert_range(range);
503 }
504 excluded.canonicalize();
505 let mut beyond: std::collections::BTreeSet<IpAddr> = neighbours.iter().copied().collect();
506 beyond.extend(
507 machines
508 .iter()
509 .copied()
510 .filter(|address| !excluded.contains(address)),
511 );
512 self.withheld += beyond.len() as u128;
513 for address in machines.into_iter().chain(neighbours) {
514 excluded.insert(address);
515 }
516 excluded.canonicalize();
517 self.excluded = ip_set_ranges(&excluded);
518 }
519
520 /// Which ports the phase walked, and whether it walked the same ones for
521 /// every address.
522 ///
523 /// [`probes`](Self::probes) counts the combinations; this says which ports they
524 /// were.
525 pub fn ports(&self) -> &PortScope {
526 &self.ports
527 }
528
529 /// The transport protocols the phase was asked about, deduplicated and in
530 /// ascending [`Protocol`] order, which puts TCP before UDP.
531 ///
532 /// Empty for a discovery sweep, whose probes the strategy chooses.
533 pub fn protocols(&self) -> &[Protocol] {
534 &self.protocols
535 }
536
537 /// The address ranges the phase was forbidden to probe, in ascending order.
538 ///
539 /// The exclusion policy in force, merged. Empty means no policy was set; a policy
540 /// that withheld nothing shows as [`withheld`](Self::withheld) returning zero.
541 ///
542 /// No host in the report may fall inside these ranges, which a reader can check.
543 ///
544 /// Also holds other addresses of an excluded machine heard during the phase; see
545 /// [the machine an address names](crate::model::exclusion#an-address-names-a-machine).
546 pub fn excluded(&self) -> &[IpRange] {
547 &self.excluded
548 }
549
550 /// How many addresses the exclusion policy took out of this phase.
551 ///
552 /// The overlap between the policy and what this phase would have asked: targets the
553 /// policy names or ties to an excluded machine, neighbour-table candidates it kept
554 /// from a sweep, and addresses heard from an excluded machine's hardware. Each is
555 /// among the excluded or the targets, so the count and the list agree. Zero for a
556 /// policy naming ground the phase would never walk, or for input an earlier phase
557 /// already narrowed.
558 ///
559 /// Tells a policy that was applied from one merely configured.
560 pub fn withheld(&self) -> u128 {
561 self.withheld
562 }
563}
564
565/// Returns every range of a set as protocol-agnostic [`IpRange`] values.
566fn ip_set_ranges(ips: &IpSet) -> Vec<IpRange> {
567 let v4 = ips.v4().iter().copied().map(IpRange::V4);
568 let v6 = ips.v6().iter().copied().map(IpRange::V6);
569 v4.chain(v6).collect()
570}
571
572/// What a scan changed about the packets it sent, to read a finding against.
573///
574/// Each field holds the value the scan used for one evasion technique, or `None` where
575/// it kept the default. A port's state under a probe from source port 53 is a different
576/// fact from the same state under an ordinary probe.
577#[non_exhaustive]
578#[derive(Debug, Clone, PartialEq, Eq)]
579pub struct EvasionRecord {
580 /// The source port every probe left from, or `None` if the scan did not pin
581 /// one.
582 pub source_port: Option<u16>,
583 /// The hop limit (IPv4 TTL / IPv6 hop limit) every ordinary probe carried,
584 /// or `None` if the scan kept the default.
585 pub ttl: Option<u8>,
586 /// The number of random bytes appended to each probe's payload, or `None` if
587 /// the scan padded nothing.
588 pub padding: Option<u16>,
589 /// Whether TCP probes carried a deliberately wrong checksum.
590 pub bad_tcp_checksum: bool,
591 /// The hardware address every frame claimed to come from, or `None` if the
592 /// scan used the interface's own.
593 pub spoof_mac: Option<MacAddr>,
594 /// The largest each IP fragment a probe was split into, in bytes, or `None`
595 /// if the scan sent probes whole.
596 pub fragment: Option<u16>,
597 /// The addresses probes were also sent from as decoys, or empty if the scan
598 /// sent from this host alone.
599 pub decoys: Vec<IpAddr>,
600 /// The exact TCP flag byte every port probe carried in place of the
601 /// technique's own, or `None` if the scan sent the technique's. The bits are
602 /// those of [`crate::protocols::tcp::flags`].
603 pub flags: Option<u8>,
604}
605
606impl EvasionRecord {
607 /// The record of what an [`EvasionProfile`] changed, or `None` if it changed
608 /// nothing.
609 #[must_use]
610 pub fn from_profile(profile: &EvasionProfile) -> Option<Self> {
611 profile.is_active().then(|| Self {
612 source_port: profile.source_port,
613 ttl: profile.ttl,
614 padding: profile.padding,
615 bad_tcp_checksum: profile.bad_tcp_checksum,
616 spoof_mac: profile.spoof_mac,
617 fragment: profile.fragment,
618 decoys: profile.decoys.clone(),
619 flags: profile.flags,
620 })
621 }
622}
623
624/// The settings that shaped what a phase did.
625///
626/// The [`ZondConfig`] fields that change which packets went out and how long the engine
627/// waited, which are what is needed to interpret or reproduce a result. A separate type,
628/// so a new config field does not silently join every exported report.
629#[non_exhaustive]
630#[derive(Debug, Clone, PartialEq)]
631pub struct ScanSettings {
632 /// How raw probes were placed on the wire.
633 pub send_mode: SendMode,
634 /// Which segment each TCP port probe carried, and so what its answers mean.
635 ///
636 /// Two `Closed` ports differ by this: one refused a connection attempt, the other
637 /// reset a segment that was not one.
638 pub tcp_technique: TcpScanTechnique,
639 /// Which chunk each SCTP port probe carried, and so what its answers mean.
640 ///
641 /// An `OpenOrNoReply` SCTP port came from a COOKIE-ECHO scan, which cannot report
642 /// open; an INIT scan would have settled it.
643 pub sctp_technique: SctpScanTechnique,
644 /// The retransmission budget and patience in force.
645 pub retry: RetryConfig,
646 /// The probe-rate ceiling, or `None` if the scanner's own default applied.
647 pub max_probe_rate: Option<std::num::NonZeroU32>,
648 /// The probe-rate floor, or `None` if the scan was free to settle wherever
649 /// it liked.
650 ///
651 /// A scan that emitted more than its targets answered may have been told to finish;
652 /// compare floors before concluding a network got noisier.
653 pub min_probe_rate: Option<std::num::NonZeroU32>,
654 /// The shortest gap kept between two probes at one host, or `None` if none
655 /// was asked for.
656 ///
657 /// Bounds how long a phase took: a thousand addresses a tenth of a second apart take
658 /// at least a hundred seconds.
659 pub host_probe_interval: Option<Duration>,
660 /// The shortest gap kept between any two probes the scan sent, or `None`
661 /// if none was asked for.
662 ///
663 /// Like [`host_probe_interval`](Self::host_probe_interval): a thousand ports a second
664 /// apart take at least a quarter of an hour.
665 pub probe_interval: Option<Duration>,
666 /// The wall-clock budget each host was given, or `None` if none was set.
667 ///
668 /// Bounds what a host's entry can say; which hosts ran out is
669 /// [`ScanPhase::timed_out`].
670 pub host_timeout: Option<Duration>,
671 /// The wall-clock budget the whole phase was given, or `None` if none was
672 /// set.
673 ///
674 /// Like [`host_timeout`](Self::host_timeout), one level up: a phase stopped by it
675 /// covered less than asked.
676 pub scan_timeout: Option<Duration>,
677 /// Whether name resolution was permitted to generate traffic.
678 pub dns_enabled: bool,
679 /// Whether the caller asked for identifying detail to be masked.
680 pub redact: bool,
681 /// How far the phase went to identify the operating system behind each host.
682 ///
683 /// At [`OsDetection::Off`] nothing looked; at other levels something looked and
684 /// found nothing conclusive. Also bounds the traffic the engine originated; see
685 /// [`OsDetection::is_active`].
686 pub os_detection: OsDetection,
687 /// How far the phase went to identify what was listening behind each open
688 /// port.
689 ///
690 /// At [`ServiceDetection::Off`] nothing asked; at other levels something asked and
691 /// could not tell. Also says whether connections were completed, which a target's
692 /// application logs would record.
693 pub service_detection: ServiceDetection,
694
695 /// How intrusive a detection the phase was permitted to run over the services
696 /// it identified.
697 ///
698 /// Decides which findings could appear, so a clean port can be read as probed or
699 /// spared.
700 pub detection: DetectionEnvelope,
701
702 /// Whether the phase measured the route to each host that answered.
703 ///
704 /// Tells a host with no path because nobody looked from one where nothing came back.
705 pub traceroute: bool,
706
707 /// Whether the phase characterised the filter in front of each host that
708 /// answered.
709 ///
710 /// As with [`traceroute`](Self::traceroute), tells not looking from finding nothing.
711 pub characterise: bool,
712
713 /// Which IP protocols the phase asked each host that answered about,
714 /// ascending.
715 ///
716 /// Per protocol, so a host with no verdict for 47 can be read as never asked.
717 pub ip_protocols: Vec<u8>,
718
719 /// Whether the phase established what each TLS port accepts.
720 ///
721 /// Tells a port that was never enumerated from one that refused every offer.
722 pub tls_enumeration: bool,
723
724 /// The TCP ports the phase connected to and listened on and sent nothing,
725 /// ascending.
726 ///
727 /// An open port here with only its number's name was left unprobed on purpose. See
728 /// [`ZondConfig::listen_only_ports`] and [`listened_only_to`](Self::listened_only_to).
729 pub listen_only_ports: Vec<u16>,
730
731 /// The ports the phase sent nothing to on any target, empty where none
732 /// were excluded.
733 ///
734 /// Recorded as the policy, since the scope cannot tell a port never named from one
735 /// excluded, and it also covers ports a phase picked itself. See
736 /// [`ZondConfig::excluded_ports`].
737 pub excluded_ports: PortSet,
738
739 /// What the scan changed about the packets it sent, or `None` if nothing; see
740 /// [`EvasionRecord`].
741 pub evasion: Option<EvasionRecord>,
742
743 /// The zombie a TCP port scan read its verdicts through, or `None`. Its presence
744 /// means the ports were inferred from a third party's counter. See [`IdleScan`].
745 pub idle_scan: Option<IdleScan>,
746
747 /// Whether the capture kept ICMP errors for a technique that did not need
748 /// them for its verdict.
749 ///
750 /// Without it, a [`NoReply`](crate::model::port::PortState::NoReply) port may be one
751 /// a filter refused; with it, that port would read
752 /// [`Blocked`](crate::model::port::PortState::Blocked).
753 pub icmp_evidence: bool,
754}
755
756impl ScanSettings {
757 /// Whether the phase only listened on `number` over `protocol`, sending it
758 /// nothing, so that what the port reports is what it volunteered and no
759 /// more.
760 ///
761 /// ```
762 /// use zond_engine::ZondConfig;
763 /// use zond_engine::model::port::Protocol;
764 /// use zond_engine::report::ScanSettings;
765 ///
766 /// let settings = ScanSettings::from(&ZondConfig::default());
767 /// assert!(settings.listened_only_to(9100, Protocol::Tcp));
768 /// assert!(!settings.listened_only_to(9100, Protocol::Udp));
769 /// assert!(!settings.listened_only_to(80, Protocol::Tcp));
770 /// ```
771 #[must_use]
772 pub fn listened_only_to(&self, number: u16, protocol: Protocol) -> bool {
773 protocol == Protocol::Tcp && self.listen_only_ports.contains(&number)
774 }
775}
776
777impl From<&ZondConfig> for ScanSettings {
778 /// What a phase records about the request behind it.
779 ///
780 /// Destructured with every field named, as for
781 /// [`ProbeTuning`](crate::config::ProbeTuning), so a new [`ZondConfig`] field fails
782 /// to compile here until it is handled.
783 fn from(cfg: &ZondConfig) -> Self {
784 let ZondConfig {
785 send_mode,
786 tcp_technique,
787 sctp_technique,
788 retry,
789 max_probe_rate,
790 min_probe_rate,
791 host_probe_interval,
792 probe_interval,
793 host_timeout,
794 scan_timeout,
795 no_dns,
796 redact,
797 os_detection,
798 service_detection,
799 detection,
800 traceroute,
801 characterise,
802 ip_protocols,
803 tls_enumeration,
804 listen_only_ports,
805 excluded_ports,
806 evasion,
807 idle_scan,
808 icmp_evidence,
809
810 // Recorded elsewhere. The exclusion policy and segment sweep are
811 // coverage, `TargetScope`'s to say; `assume_up` shows as a missing
812 // discovery phase.
813 exclusions: _,
814 segment_sweep: _,
815 assume_up: _,
816 // The hosts' names record it; the journal keeps it with the options.
817 target_names: _,
818
819 // Not recorded: transport plumbing naming host-specific addresses.
820 send_source: _,
821 } = cfg;
822
823 Self {
824 send_mode: *send_mode,
825 tcp_technique: *tcp_technique,
826 sctp_technique: *sctp_technique,
827 retry: *retry,
828 max_probe_rate: *max_probe_rate,
829 min_probe_rate: *min_probe_rate,
830 host_probe_interval: *host_probe_interval,
831 probe_interval: *probe_interval,
832 host_timeout: *host_timeout,
833 scan_timeout: *scan_timeout,
834 dns_enabled: !no_dns,
835 redact: *redact,
836 os_detection: *os_detection,
837 service_detection: *service_detection,
838 detection: *detection,
839 traceroute: *traceroute,
840 characterise: *characterise,
841 ip_protocols: ip_protocols.iter().copied().collect(),
842 tls_enumeration: *tls_enumeration,
843 listen_only_ports: listen_only_ports.iter().copied().collect(),
844 excluded_ports: excluded_ports.clone(),
845 evasion: EvasionRecord::from_profile(evasion),
846 idle_scan: *idle_scan,
847 icmp_evidence: *icmp_evidence,
848 }
849 }
850}
851
852// --------------------------------------------------------------------------
853// What a scan measured about itself
854// --------------------------------------------------------------------------
855//
856// Instrumentation, not findings: these bound how far the host list can be trusted.
857
858/// Upper bounds, in milliseconds, of the discovery-time histogram buckets in
859/// [`ProbeStats::found_at`]. A final bucket catches everything later than the
860/// last bound.
861///
862/// These measure how far into the run a host was first credited, **not** its round
863/// trip: a host found at 700 ms because its third attempt went out at 690 ms has a
864/// 10 ms round trip. Round trips are reported per host.
865///
866/// Roughly logarithmic, spanning a same-segment reply under a millisecond, an internet
867/// round trip in the tens, and a late retry in the hundreds.
868pub const BUCKET_BOUNDS_MS: &[u64] = &[1, 2, 5, 10, 25, 50, 100, 250, 1_000];
869
870/// How many attempts [`ProbeStats::answered_on`] counts separately before the
871/// rest are lumped together.
872///
873/// Above the largest budget any path runs (five, under
874/// [`ScanEffort::Thorough`](crate::config::ScanEffort)), so a hand-raised budget still
875/// has somewhere to land.
876pub const ATTEMPTS_COUNTED: usize = 6;
877
878/// Why a scanner's receive loop stopped.
879///
880/// The most informative field in an audit: a run ending in
881/// [`AllResponded`](StopReason::AllResponded) was not cut short, and one ending in
882/// [`DeadlineExpired`](StopReason::DeadlineExpired) with replies still arriving almost
883/// certainly was.
884///
885/// A scan loop breaks with its reason, so every exit path names one.
886#[non_exhaustive]
887#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
888pub enum StopReason {
889 /// The caller aborted the scan through the scan handle.
890 Aborted,
891 /// Every target answered.
892 AllResponded,
893 /// Every target either answered or was asked as often as the retry budget allows.
894 /// Like [`AllResponded`](StopReason::AllResponded), the scan finished.
895 AttemptsSpent,
896 /// The adaptive deadline expired: either the hard budget ran out or the
897 /// silence tolerance did.
898 DeadlineExpired,
899 /// The capture stream closed underneath the scanner.
900 StreamClosed,
901 /// The wall-clock budget the caller set on the whole scan ran out, and
902 /// every strategy wound down where it stood. See
903 /// [`ZondConfig::scan_timeout`](crate::config::ZondConfig::scan_timeout).
904 ///
905 /// Unlike [`Aborted`](StopReason::Aborted), nobody stopped it: the scan was given
906 /// less time than the network needed. Unlike
907 /// [`DeadlineExpired`](StopReason::DeadlineExpired), which is one receive loop's
908 /// own pacing, this is about the whole run.
909 TimedOut,
910}
911
912impl StopReason {
913 /// Every reason a receive loop stops, in declaration order. Checked against the
914 /// published schema.
915 pub const ALL: &'static [Self] = &[
916 Self::Aborted,
917 Self::AllResponded,
918 Self::AttemptsSpent,
919 Self::DeadlineExpired,
920 Self::StreamClosed,
921 Self::TimedOut,
922 ];
923
924 /// Whether the loop stopped because it had nothing left to do, rather than
925 /// because something cut it short.
926 ///
927 /// A complete run found everything it was going to; waiting longer could not have
928 /// changed it.
929 pub fn is_complete(&self) -> bool {
930 matches!(self, StopReason::AllResponded | StopReason::AttemptsSpent)
931 }
932}
933
934impl fmt::Display for StopReason {
935 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
936 let text = match self {
937 StopReason::Aborted => "aborted by the caller",
938 StopReason::AllResponded => "every target answered",
939 StopReason::AttemptsSpent => "attempts spent",
940 StopReason::DeadlineExpired => "deadline expired",
941 StopReason::StreamClosed => "capture stream closed",
942 StopReason::TimedOut => "scan budget spent",
943 };
944 f.write_str(text)
945 }
946}
947
948/// `sends` over `elapsed`, per second, or `None` where no time passed.
949///
950/// Shared by [`achieved_send_rate`](ProbeStats::achieved_send_rate) and a scanner's
951/// audit line, so they agree.
952pub(crate) fn send_rate(sends: u64, elapsed: Duration) -> Option<f64> {
953 let seconds = elapsed.as_secs_f64();
954 (seconds > 0.0).then(|| sends as f64 / seconds)
955}
956
957/// What one raw scanner observed about its own run.
958///
959/// A short sweep has three possible causes with different fixes: probes or replies
960/// were lost (retransmission's job); replies arrived after the scan **stopped** (the
961/// deadline is wrong); or replies arrived and went **unrecognized** (more time or
962/// packets will not help).
963///
964/// These counters separate them. [`sends_attempted`](Self::sends_attempted)
965/// against [`segments_seen`](Self::segments_seen) bounds the first,
966/// [`stop_reason`](Self::stop_reason) against
967/// [`last_reply`](Self::last_reply) bounds the second, and
968/// [`segments_off_target`](Self::segments_off_target) with
969/// [`replies_without_rtt`](Self::replies_without_rtt) bounds the third.
970///
971/// A reply the kernel discards because the capture buffer was full reaches no counter
972/// here, so [`capture`](Self::capture) is carried to tell receive-path loss from
973/// network loss.
974///
975/// Instrumentation about the scan; nothing here changes what is reported about a host.
976#[derive(Debug, Clone, PartialEq, Eq)]
977pub struct ProbeStats {
978 // `pub(crate)` for `ProbeAudit` in another module; consumers read through the
979 // accessors and cannot edit a measurement.
980 pub(crate) scanner: ScannerKind,
981 pub(crate) targets: u128,
982 pub(crate) stop_reason: StopReason,
983 pub(crate) elapsed: Duration,
984 pub(crate) sends_attempted: u64,
985 pub(crate) sends_failed: u64,
986 pub(crate) sends_witnessed: u64,
987 pub(crate) segments_seen: u64,
988 pub(crate) segments_off_target: u64,
989 pub(crate) replies_without_rtt: u64,
990 pub(crate) refusals_unattributed: u64,
991 pub(crate) hosts_found: u64,
992 pub(crate) answered_on: [u64; ATTEMPTS_COUNTED],
993 pub(crate) answered_unattributed: u64,
994 pub(crate) first_reply: Option<Duration>,
995 pub(crate) last_reply: Option<Duration>,
996 pub(crate) found_at: [u64; BUCKET_BOUNDS_MS.len() + 1],
997 pub(crate) capture: Option<CaptureCounts>,
998 pub(crate) window: Option<WindowSummary>,
999}
1000
1001impl ProbeStats {
1002 /// The strategy these counters belong to.
1003 pub fn scanner(&self) -> ScannerKind {
1004 self.scanner
1005 }
1006
1007 /// How many targets this scanner owned: addresses for a discovery sweep,
1008 /// `(address, port)` probes for a port scan.
1009 pub fn targets(&self) -> u128 {
1010 self.targets
1011 }
1012
1013 /// Why the receive loop stopped.
1014 pub fn stop_reason(&self) -> StopReason {
1015 self.stop_reason
1016 }
1017
1018 /// How long the scanner ran.
1019 pub fn elapsed(&self) -> Duration {
1020 self.elapsed
1021 }
1022
1023 /// Probes the scanner tried to put on the wire.
1024 pub fn sends_attempted(&self) -> u64 {
1025 self.sends_attempted
1026 }
1027
1028 /// Probes per second the scanner put on the wire over its whole run:
1029 /// [`sends_attempted`](Self::sends_attempted) over
1030 /// [`elapsed`](Self::elapsed). `None` for a run with no time to divide by.
1031 ///
1032 /// Compare with the configured rate. The send timer never makes up a missed tick,
1033 /// since catching up would be a burst, so a busy run sends slower than asked.
1034 pub fn achieved_send_rate(&self) -> Option<f64> {
1035 send_rate(self.sends_attempted, self.elapsed)
1036 }
1037
1038 /// Of those, ones that never left this host: the sender refused them or could not
1039 /// reach their address. Unreachable addresses are in the phase's
1040 /// [`unroutable`](ScanPhase::unroutable) list.
1041 pub fn sends_failed(&self) -> u64 {
1042 self.sends_failed
1043 }
1044
1045 /// How many probes were watched leaving on the wire. Read against
1046 /// [`sends_attempted`](Self::sends_attempted), and only when non-zero: the
1047 /// gap is probes the OS took and dropped. Zero means no egress capture.
1048 pub fn sends_witnessed(&self) -> u64 {
1049 self.sends_witnessed
1050 }
1051
1052 /// Segments the capture handed up, before any of the scanner's own checks.
1053 pub fn segments_seen(&self) -> u64 {
1054 self.segments_seen
1055 }
1056
1057 /// What this run's congestion window did, for a scanner paced by one.
1058 ///
1059 /// Tells "these ports drop probes" from "this scan was outrun". A run whose window
1060 /// bottomed out with most probes unanswered could not ask, which says nothing about
1061 /// a firewall.
1062 ///
1063 /// `None` for a scanner that paces itself some other way.
1064 pub fn window(&self) -> Option<WindowSummary> {
1065 self.window
1066 }
1067
1068 /// Segments from an address outside this scan's target set. Expected to be
1069 /// small; a large count means the capture filter is admitting other traffic.
1070 pub fn segments_off_target(&self) -> u64 {
1071 self.segments_off_target
1072 }
1073
1074 /// In-set replies that answered no outstanding probe, so they proved a host
1075 /// alive but yielded no round-trip sample. Duplicates land here, and so does
1076 /// a correlation bug.
1077 pub fn replies_without_rtt(&self) -> u64 {
1078 self.replies_without_rtt
1079 }
1080
1081 /// ICMP refusals among [`replies_without_rtt`](Self::replies_without_rtt)
1082 /// that quoted too little of the probe to name its attempt.
1083 ///
1084 /// Anyone who knows the source port can forge a refusal naming the ports, so one
1085 /// that cannot name the attempt settles nothing, and the port keeps what its retries
1086 /// conclude. This counts them. A sender quoting only the eight bytes RFC 792
1087 /// guarantees omits an ACK, window or Maimon scan's nonce, and every INIT's.
1088 pub fn refusals_unattributed(&self) -> u64 {
1089 self.refusals_unattributed
1090 }
1091
1092 /// Targets a reply resolved, counted once each.
1093 ///
1094 /// In the unit of [`targets`](Self::targets): a host for a discovery sweep, an
1095 /// `(address, port)` probe for a port scan.
1096 ///
1097 /// Against `targets` it is coverage; against [`stop_reason`](Self::stop_reason) and
1098 /// [`last_reply`](Self::last_reply) it says whether the run was still finding things
1099 /// when it ended.
1100 pub fn hosts_found(&self) -> u64 {
1101 self.hosts_found
1102 }
1103
1104 /// Found hosts by the attempt whose reply revealed them.
1105 ///
1106 /// Index `i` counts hosts answered on attempt `i + 1`; the last slot counts
1107 /// attempt [`ATTEMPTS_COUNTED`] *or later*, so a hand-raised retry budget
1108 /// still has somewhere to land.
1109 ///
1110 /// Shows whether retransmission earns its traffic.
1111 pub fn answered_on(&self) -> &[u64] {
1112 &self.answered_on
1113 }
1114
1115 /// Found hosts whose reply named no attempt: it arrived after the probe had
1116 /// been written off, or carried nothing to match against.
1117 pub fn answered_unattributed(&self) -> u64 {
1118 self.answered_unattributed
1119 }
1120
1121 /// How far into the run the first host was credited.
1122 pub fn first_reply(&self) -> Option<Duration> {
1123 self.first_reply
1124 }
1125
1126 /// How far into the run the last host was credited. Close to
1127 /// [`elapsed`](Self::elapsed) on a run that stopped for
1128 /// [`DeadlineExpired`](StopReason::DeadlineExpired) means the scan was still
1129 /// finding hosts when it ran out of time.
1130 pub fn last_reply(&self) -> Option<Duration> {
1131 self.last_reply
1132 }
1133
1134 /// Hosts by how far into the run they were credited, bucketed by
1135 /// [`BUCKET_BOUNDS_MS`]. Index `i` counts hosts found at or under
1136 /// `BUCKET_BOUNDS_MS[i]` milliseconds; the final slot counts everything
1137 /// later than the last bound.
1138 pub fn found_at(&self) -> &[u64] {
1139 &self.found_at
1140 }
1141
1142 /// What the kernel capture reported. `None` for a synthetic receive stream.
1143 pub fn capture(&self) -> Option<CaptureCounts> {
1144 self.capture
1145 }
1146}
1147
1148// --------------------------------------------------------------------------
1149// What a scan did not cover
1150// --------------------------------------------------------------------------
1151//
1152// A strategy that could not run is a `ScannerFailure`; ground the engine declined
1153// before sending anything is a `Refusal`. Both narrow a result; only one is a fault.
1154
1155/// Ground a scan decided not to cover, and why.
1156///
1157/// Nothing broke: before sending anything, the engine found part of the request had no
1158/// strategy behind it. A raw socket that would not open is a [`ScannerFailure`]; an
1159/// SCTP port named by a scan with no way to probe one is this. A failure might clear
1160/// next time; a refusal will recur until the scan changes.
1161///
1162/// The recorded form of [`RefusedStep`](crate::scanner::plan::RefusedStep), as
1163/// [`ScannerFailure`] is of [`StrategyError`](crate::scanner::strategy::StrategyError).
1164#[must_use]
1165#[derive(Debug, Clone, PartialEq, Eq)]
1166pub struct Refusal {
1167 scanner: ScannerKind,
1168 reason: String,
1169}
1170
1171impl Refusal {
1172 /// Records that `scanner`'s work was declined, for `reason`.
1173 pub fn new(scanner: ScannerKind, reason: impl Into<String>) -> Self {
1174 Self {
1175 scanner,
1176 reason: reason.into(),
1177 }
1178 }
1179
1180 /// The strategy that would have taken this work.
1181 pub fn scanner(&self) -> ScannerKind {
1182 self.scanner
1183 }
1184
1185 /// What was not done, and what the caller could ask for instead.
1186 pub fn reason(&self) -> &str {
1187 &self.reason
1188 }
1189}
1190
1191/// A scanning strategy that did not run to completion.
1192///
1193/// A scan continues with the remaining strategies when one fails, so a report with
1194/// failures still has narrower results. This tells an empty network from a sweep whose
1195/// raw scanner never started.
1196///
1197/// [`is_cut_short`](Self::is_cut_short) tells two kinds apart. A failure met a fault
1198/// (a socket that would not open, a capture that closed, a panic). A cut-short strategy
1199/// stopped against a limit (a budget, the file limit, a pinned source port in use).
1200/// Both leave ground unanswered, so [`ScanReport::is_partial`] counts both, but the
1201/// remedies differ.
1202#[must_use]
1203#[derive(Debug, Clone, PartialEq, Eq)]
1204pub struct ScannerFailure {
1205 scanner: ScannerKind,
1206 reason: String,
1207 at: SystemTime,
1208 cut_short: bool,
1209}
1210
1211impl ScannerFailure {
1212 /// Records a failure as having happened now.
1213 pub fn new(scanner: ScannerKind, reason: impl Into<String>) -> Self {
1214 Self {
1215 scanner,
1216 reason: reason.into(),
1217 at: SystemTime::now(),
1218 cut_short: false,
1219 }
1220 }
1221
1222 /// Records, as having happened now, work `scanner` stopped short of because a limit
1223 /// was reached. `reason` names the limit.
1224 pub fn cut_short(scanner: ScannerKind, reason: impl Into<String>) -> Self {
1225 Self {
1226 cut_short: true,
1227 ..Self::new(scanner, reason)
1228 }
1229 }
1230
1231 /// Whether this is work a limit cut short rather than a fault stopped.
1232 ///
1233 /// False for a record from a document without the distinction, which reads every
1234 /// entry as a failure.
1235 pub fn is_cut_short(&self) -> bool {
1236 self.cut_short
1237 }
1238
1239 /// The strategy that failed.
1240 pub fn scanner(&self) -> ScannerKind {
1241 self.scanner
1242 }
1243
1244 /// A human-readable description of the failure.
1245 pub fn reason(&self) -> &str {
1246 &self.reason
1247 }
1248
1249 /// Restores the time this failure was recorded.
1250 ///
1251 /// For a failure restored from a journal; [`new`](Self::new) stamps the current
1252 /// time.
1253 pub fn recorded_at(mut self, at: SystemTime) -> Self {
1254 self.at = at;
1255 self
1256 }
1257
1258 /// When the failure was observed.
1259 pub fn at(&self) -> SystemTime {
1260 self.at
1261 }
1262
1263 /// Whether the failure cost the scan ground it set out to cover.
1264 ///
1265 /// Every strategy's does. A [`Journal`](ScannerKind::Journal) that could not be
1266 /// written did not: it probed nothing and costs only what a resume would ask again.
1267 /// Nor does a failed [`Resolver`](ScannerKind::Resolver), which costs only names.
1268 pub(crate) fn narrows_coverage(&self) -> bool {
1269 !matches!(self.scanner, ScannerKind::Journal | ScannerKind::Resolver)
1270 }
1271}
1272
1273impl fmt::Display for ScannerFailure {
1274 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1275 let outcome = if self.cut_short {
1276 "cut short"
1277 } else {
1278 "failed"
1279 };
1280 write!(f, "{:?} scanner {outcome}: {}", self.scanner, self.reason)
1281 }
1282}
1283
1284// --------------------------------------------------------------------------
1285// Rebuilding what was recorded
1286// --------------------------------------------------------------------------
1287//
1288// Each `*Parts` struct is followed by the `from_parts` that consumes it, so the path
1289// a report takes back off disk reads in one place. Hence `impl ScanPhase` before
1290// `struct ScanPhase`, and second impl blocks for `TargetScope` and `ProbeStats`.
1291
1292/// Everything a [`TargetScope`] holds, for rebuilding one that was recorded.
1293///
1294/// A struct, since two `u128` counts and two range lists are easy to swap.
1295#[derive(Debug, Clone, PartialEq, Eq)]
1296pub struct ScopeParts {
1297 /// The ranges that were walked, after exclusions.
1298 pub ranges: Vec<IpRange>,
1299 /// The links swept whole, by the interface each is on.
1300 pub links: Vec<Zone>,
1301 /// The links read from without being probed, which are never coverage.
1302 pub listened: Vec<Zone>,
1303 /// How many distinct addresses those ranges hold.
1304 pub addresses: u128,
1305 /// How many probes the scope implies, where ports were known.
1306 pub probes: Option<u128>,
1307 /// Which ports were walked, and whether uniformly.
1308 pub ports: PortScope,
1309 /// The transports the scope covered.
1310 pub protocols: Vec<Protocol>,
1311 /// The ranges the policy withheld.
1312 pub excluded: Vec<IpRange>,
1313 /// How many addresses that withheld.
1314 pub withheld: u128,
1315}
1316
1317impl TargetScope {
1318 /// Rebuilds a scope from what was recorded of it.
1319 ///
1320 /// Applies no policy, unlike [`from_ip_set`](Self::from_ip_set): the exclusions
1321 /// were applied when the scope was first computed.
1322 pub fn from_parts(parts: ScopeParts) -> Self {
1323 Self {
1324 listened: parts.listened,
1325 ranges: parts.ranges,
1326 links: parts.links,
1327 addresses: parts.addresses,
1328 probes: parts.probes,
1329 ports: parts.ports,
1330 protocols: parts.protocols,
1331 excluded: parts.excluded,
1332 withheld: parts.withheld,
1333 }
1334 }
1335}
1336
1337/// Everything a [`ProbeStats`] holds, for rebuilding one that was recorded.
1338///
1339/// The two distributions are lists, since their lengths ([`ATTEMPTS_COUNTED`] and one
1340/// more than [`BUCKET_BOUNDS_MS`]) may grow. [`ProbeStats::from_parts`] reads each for
1341/// the slots this build counts.
1342#[derive(Debug, Clone, PartialEq, Eq)]
1343pub struct ProbeStatsParts {
1344 /// Which strategy this describes.
1345 pub scanner: ScannerKind,
1346 /// How many targets it was given.
1347 pub targets: u128,
1348 /// Why its receive loop stopped.
1349 pub stop_reason: StopReason,
1350 /// How long it ran.
1351 pub elapsed: Duration,
1352 /// How many sends it attempted.
1353 pub sends_attempted: u64,
1354 /// How many of those never left this host, refused or unable to reach
1355 /// their address.
1356 pub sends_failed: u64,
1357 /// How many of those were seen leaving on the wire.
1358 pub sends_witnessed: u64,
1359 /// How many segments its capture handed it.
1360 pub segments_seen: u64,
1361 /// Where its congestion window ended up.
1362 pub window: Option<WindowSummary>,
1363 /// How many captured segments belonged to something else.
1364 pub segments_off_target: u64,
1365 /// How many replies could not be attributed to one attempt.
1366 pub replies_without_rtt: u64,
1367 /// How many of those were ICMP refusals too short to name an attempt.
1368 pub refusals_unattributed: u64,
1369 /// How many hosts it found.
1370 pub hosts_found: u64,
1371 /// How many answers arrived on each attempt, one slot per counted attempt,
1372 /// as [`ProbeStats::answered_on`] gives them.
1373 pub answered_on: Vec<u64>,
1374 /// How many answers named no attempt.
1375 pub answered_unattributed: u64,
1376 /// When the first reply arrived, from the start of the run.
1377 pub first_reply: Option<Duration>,
1378 /// When the last one did.
1379 pub last_reply: Option<Duration>,
1380 /// How many hosts were found in each time bucket, one slot per bound plus
1381 /// the tail, as [`ProbeStats::found_at`] gives them.
1382 pub found_at: Vec<u64>,
1383 /// What the capture reported about its own losses.
1384 pub capture: Option<CaptureCounts>,
1385}
1386
1387impl ProbeStats {
1388 /// Rebuilds probe statistics from what was recorded of them.
1389 ///
1390 /// Each distribution is read for the slots this build counts: extra slots are
1391 /// dropped and missing ones read as zero, so a record from a build with more slots
1392 /// still reads. A caller building these by hand sizes them from the two constants.
1393 pub fn from_parts(parts: ProbeStatsParts) -> Self {
1394 Self {
1395 scanner: parts.scanner,
1396 targets: parts.targets,
1397 stop_reason: parts.stop_reason,
1398 elapsed: parts.elapsed,
1399 sends_attempted: parts.sends_attempted,
1400 sends_failed: parts.sends_failed,
1401 sends_witnessed: parts.sends_witnessed,
1402 segments_seen: parts.segments_seen,
1403 window: parts.window,
1404 segments_off_target: parts.segments_off_target,
1405 replies_without_rtt: parts.replies_without_rtt,
1406 refusals_unattributed: parts.refusals_unattributed,
1407 hosts_found: parts.hosts_found,
1408 answered_on: fitted(&parts.answered_on),
1409 answered_unattributed: parts.answered_unattributed,
1410 first_reply: parts.first_reply,
1411 last_reply: parts.last_reply,
1412 found_at: fitted(&parts.found_at),
1413 capture: parts.capture,
1414 }
1415 }
1416}
1417
1418/// As much of `from` as `N` slots hold, the rest zero. See
1419/// [`ProbeStats::from_parts`].
1420fn fitted<const N: usize>(from: &[u64]) -> [u64; N] {
1421 let mut into = [0u64; N];
1422 for (slot, value) in into.iter_mut().zip(from) {
1423 *slot = *value;
1424 }
1425 into
1426}
1427
1428// --------------------------------------------------------------------------
1429// One phase of a scan
1430// --------------------------------------------------------------------------
1431//
1432// A phase is one engine call: a sweep, a port scan, a watch. A report holds a list
1433// of them, since discovery then a port scan is one job.
1434
1435/// Which switch port the machine running a phase was plugged into.
1436///
1437/// A relation between *this* machine and the equipment it is plugged into, learned
1438/// from an unprompted announcement (see [`crate::protocols::lldp`] and
1439/// [`crate::protocols::cdp`]). It answers **where, physically, this was run from.**
1440///
1441/// On the phase, like [`PhaseOrigin`], because a [`merge`](crate::merge) may fold
1442/// phases run from several vantage points, each with its own true answer.
1443///
1444/// A phase may carry several: one per link it captured on, and another whenever the
1445/// answer changed, as when someone moves a cable during a long listen.
1446#[must_use]
1447#[derive(Debug, Clone, PartialEq, Eq)]
1448pub struct Attachment {
1449 link: Zone,
1450 source: AttachmentSource,
1451 device_mac: Option<MacAddr>,
1452 device_name: Option<String>,
1453 port: Option<String>,
1454 native_vlan: Option<u16>,
1455 management: Option<IpAddr>,
1456 observed_at: SystemTime,
1457}
1458
1459/// Which protocol an [`Attachment`] was read from.
1460///
1461/// Cisco equipment runs CDP by default and LLDP only when enabled, so which one a
1462/// network answers on says something about it. The two also carry fields such as the
1463/// VLAN in different places.
1464#[non_exhaustive]
1465#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
1466pub enum AttachmentSource {
1467 /// IEEE 802.1AB, which anything may speak.
1468 Lldp,
1469 /// Cisco Discovery Protocol.
1470 Cdp,
1471}
1472
1473impl AttachmentSource {
1474 /// Every announcement protocol this build knows, in declaration order. Checked
1475 /// against the published schema.
1476 pub const ALL: &'static [Self] = &[Self::Lldp, Self::Cdp];
1477}
1478
1479impl Attachment {
1480 /// An attachment on `link`, read from `source`, with nothing established
1481 /// about it yet.
1482 pub fn new(link: Zone, source: AttachmentSource, observed_at: SystemTime) -> Self {
1483 Self {
1484 link,
1485 source,
1486 device_mac: None,
1487 device_name: None,
1488 port: None,
1489 native_vlan: None,
1490 management: None,
1491 observed_at,
1492 }
1493 }
1494
1495 /// Names the device by the hardware address it identified its chassis with.
1496 ///
1497 /// Ties this attachment to a [`Host`] in the same report, which a name may not.
1498 pub fn with_device_mac(mut self, mac: MacAddr) -> Self {
1499 self.device_mac = Some(mac);
1500 self
1501 }
1502
1503 /// Names the device as it names itself.
1504 pub fn with_device_name(mut self, name: impl Into<String>) -> Self {
1505 self.device_name = Some(name.into());
1506 self
1507 }
1508
1509 /// Names the port, as the device calls it in its own configuration.
1510 pub fn with_port(mut self, port: impl Into<String>) -> Self {
1511 self.port = Some(port.into());
1512 self
1513 }
1514
1515 /// Records the VLAN untagged traffic on this port lands in.
1516 pub fn with_native_vlan(mut self, vlan: u16) -> Self {
1517 self.native_vlan = Some(vlan);
1518 self
1519 }
1520
1521 /// Records an address the device is managed at.
1522 pub fn with_management_address(mut self, address: IpAddr) -> Self {
1523 self.management = Some(address);
1524 self
1525 }
1526
1527 /// Which of this machine's interfaces the announcement arrived on.
1528 pub fn link(&self) -> &Zone {
1529 &self.link
1530 }
1531
1532 /// Which protocol said so.
1533 pub fn source(&self) -> AttachmentSource {
1534 self.source
1535 }
1536
1537 /// The hardware address the device identified its chassis with.
1538 pub fn device_mac(&self) -> Option<MacAddr> {
1539 self.device_mac
1540 }
1541
1542 /// What the device calls itself, which on managed equipment is its
1543 /// hostname.
1544 pub fn device_name(&self) -> Option<&str> {
1545 self.device_name.as_deref()
1546 }
1547
1548 /// What the device calls the port this machine is plugged into.
1549 pub fn port(&self) -> Option<&str> {
1550 self.port.as_deref()
1551 }
1552
1553 /// The VLAN untagged traffic on this port lands in, where the device said.
1554 pub fn native_vlan(&self) -> Option<u16> {
1555 self.native_vlan
1556 }
1557
1558 /// An address the device is managed at, where it advertised one.
1559 pub fn management_address(&self) -> Option<IpAddr> {
1560 self.management
1561 }
1562
1563 /// When the announcement this was read from arrived.
1564 ///
1565 /// Separate from the phase's span, so changes during a long phase can be ordered.
1566 pub fn observed_at(&self) -> SystemTime {
1567 self.observed_at
1568 }
1569}
1570
1571/// Which document a phase came from, for a report folded out of several.
1572///
1573/// A report merged from an archived nmap file, last night's journal and a fresh scan
1574/// holds all their phases; this says which document each came from.
1575///
1576/// `None` on a phase this process measured.
1577///
1578/// The label is the caller's (a path, a record id, a bucket key), since the engine
1579/// opens no files. Only [`merge`](crate::merge) writes a `PhaseOrigin`, taking the
1580/// version from the source report's own attribution.
1581#[must_use]
1582#[derive(Debug, Clone, PartialEq, Eq)]
1583pub struct PhaseOrigin {
1584 label: Option<Arc<str>>,
1585 engine_version: Arc<str>,
1586}
1587
1588impl PhaseOrigin {
1589 /// An origin attributing a phase to `engine_version`, unnamed.
1590 pub fn new(engine_version: impl Into<Arc<str>>) -> Self {
1591 Self {
1592 label: None,
1593 engine_version: engine_version.into(),
1594 }
1595 }
1596
1597 /// Names the document the phase was read from.
1598 pub fn with_label(mut self, label: impl Into<Arc<str>>) -> Self {
1599 self.label = Some(label.into());
1600 self
1601 }
1602
1603 /// What the caller called the document, if it said.
1604 pub fn label(&self) -> Option<&str> {
1605 self.label.as_deref()
1606 }
1607
1608 /// What produced the phase, as that scanner attributed itself: `nmap 7.94` for a
1609 /// report read from nmap's XML.
1610 pub fn engine_version(&self) -> &str {
1611 &self.engine_version
1612 }
1613}
1614
1615/// Everything a [`ScanPhase`] holds, for rebuilding one that was recorded.
1616///
1617/// Mirrors the phase field for field, without a default, so a field added to
1618/// [`ScanPhase`] fails to compile everywhere one is built until it is handled.
1619#[derive(Debug, Clone)]
1620pub struct PhaseParts {
1621 /// Which entry point the phase recorded.
1622 pub kind: ScanKind,
1623 /// When it began.
1624 pub started_at: SystemTime,
1625 /// How long it ran.
1626 pub elapsed: Duration,
1627 /// Which sockets the phase had, or `None` where this engine did not measure
1628 /// it and cannot say.
1629 pub privilege: Option<Privilege>,
1630 /// What it was asked to cover, and what it was forbidden.
1631 pub targets: TargetScope,
1632 /// The settings it ran under.
1633 pub settings: ScanSettings,
1634 /// The strategies that could not do their job.
1635 pub failures: Vec<ScannerFailure>,
1636 /// Ground the phase declined before sending anything.
1637 pub refusals: Vec<Refusal>,
1638 /// Addresses this host could not reach, so no probe was sent to them.
1639 pub unroutable: Vec<IpAddr>,
1640 /// The addresses among `unroutable` that this host's routing table
1641 /// refuses. See [`ScanPhase::refused_by_route`].
1642 pub refused_by_route: Vec<IpAddr>,
1643 /// Addresses whose per-host budget ran out before the phase finished with
1644 /// them.
1645 pub timed_out: Vec<IpAddr>,
1646 /// Addresses whose ICMP errors the phase found rate-limited. See
1647 /// [`ScanPhase::icmp_rate_limited`].
1648 pub icmp_rate_limited: Vec<IpAddr>,
1649 /// Addresses a raw phase reached by TCP connect. See
1650 /// [`ScanPhase::reached_by_connect`].
1651 pub reached_by_connect: Vec<IpRange>,
1652 /// Addresses in scope the phase reached no verdict on. See
1653 /// [`ScanPhase::undecided`].
1654 pub undecided: Vec<IpRange>,
1655 /// Why a port phase ran with no liveness pass in front of it. See
1656 /// [`ScanPhase::liveness_skipped`].
1657 pub liveness_skipped: Option<LivenessSkip>,
1658 /// Addresses a port phase standing in for its liveness pass asked on every
1659 /// port and heard nothing from. See [`ScanPhase::silent`].
1660 pub silent: Vec<IpRange>,
1661 /// Why the scan was stopped while the phase was running, or `None`. See
1662 /// [`ScanPhase::stopped`].
1663 pub stopped: Option<StopReason>,
1664 /// The passes over what the probes found that a stop skipped or cut
1665 /// short. See [`ScanPhase::passes_cut`].
1666 pub passes_cut: Vec<Pass>,
1667 /// How many of a port phase's targets it never asked and holds on no
1668 /// host. See [`ScanPhase::unreached`].
1669 pub unreached: u128,
1670 /// How many of a port phase's targets it asked at the addresses it lists
1671 /// no host at. See [`ScanPhase::unheard_probes`].
1672 pub unheard_probes: u128,
1673 /// What each strategy recorded about its own run.
1674 pub probes: Vec<ProbeStats>,
1675 /// Which document the phase came from, for one folded in from elsewhere.
1676 pub origin: Option<PhaseOrigin>,
1677 /// Which switch ports the machine running the phase was plugged into.
1678 pub attachments: Vec<Attachment>,
1679 /// Whether this is the phase as it stood before it closed. See
1680 /// [`ScanPhase::is_open`].
1681 pub open: bool,
1682}
1683
1684impl ScanPhase {
1685 /// Rebuilds a phase from what was recorded of it.
1686 ///
1687 /// For restoring an earlier sitting of a resumed scan. A running phase comes from
1688 /// [`PhaseRecorder`](crate::scanner::recorder::PhaseRecorder).
1689 pub fn from_parts(parts: PhaseParts) -> Self {
1690 Self {
1691 kind: parts.kind,
1692 started_at: parts.started_at,
1693 elapsed: parts.elapsed,
1694 privilege: parts.privilege,
1695 targets: parts.targets,
1696 settings: parts.settings,
1697 failures: parts.failures,
1698 refusals: parts.refusals,
1699 unroutable: parts.unroutable,
1700 refused_by_route: parts.refused_by_route,
1701 timed_out: parts.timed_out,
1702 icmp_rate_limited: parts.icmp_rate_limited,
1703 reached_by_connect: parts.reached_by_connect,
1704 undecided: parts.undecided,
1705 liveness_skipped: parts.liveness_skipped,
1706 silent: parts.silent,
1707 stopped: parts.stopped,
1708 passes_cut: {
1709 let mut passes = parts.passes_cut;
1710 passes.sort_unstable();
1711 passes.dedup();
1712 passes
1713 },
1714 unreached: parts.unreached,
1715 unheard_probes: parts.unheard_probes,
1716 probes: parts.probes,
1717 origin: parts.origin,
1718 attachments: parts.attachments,
1719 open: parts.open,
1720 }
1721 }
1722
1723 /// Attributes this phase to the document it was read from.
1724 ///
1725 /// Used by [`merge`](crate::merge), which knows the document's name and producer.
1726 pub fn attribute(&mut self, origin: PhaseOrigin) {
1727 self.origin = Some(origin);
1728 }
1729}
1730
1731/// One completed call into the engine.
1732#[derive(Debug, Clone)]
1733pub struct ScanPhase {
1734 kind: ScanKind,
1735 started_at: SystemTime,
1736 elapsed: Duration,
1737 privilege: Option<Privilege>,
1738 targets: TargetScope,
1739 settings: ScanSettings,
1740 failures: Vec<ScannerFailure>,
1741 /// Addresses this host could not reach, so no probe was sent to them: no
1742 /// route or source address led to them, or they are neighbours on a local
1743 /// segment that never answered address resolution.
1744 ///
1745 /// Distinct from a host that answered nothing: scanning an unreachable address on
1746 /// trust cannot help.
1747 unroutable: Vec<IpAddr>,
1748 /// The addresses among `unroutable` that this host's routing table
1749 /// refuses. See [`refused_by_route`](Self::refused_by_route).
1750 refused_by_route: Vec<IpAddr>,
1751 /// Ground this phase declined before sending anything, and why.
1752 ///
1753 /// Not a failure; see [`Refusal`].
1754 refusals: Vec<Refusal>,
1755 /// Addresses the phase stopped working on because their own budget ran out.
1756 ///
1757 /// Not a failure. Without it, a host left early looks the same as one that stayed
1758 /// silent.
1759 timed_out: Vec<IpAddr>,
1760 /// Addresses whose ICMP errors the phase found rate-limited.
1761 ///
1762 /// See [`icmp_rate_limited`](Self::icmp_rate_limited).
1763 icmp_rate_limited: Vec<IpAddr>,
1764 /// Addresses this phase reached by TCP connect although it held the
1765 /// privilege its raw strategies need.
1766 ///
1767 /// See [`reached_by_connect`](Self::reached_by_connect).
1768 reached_by_connect: Vec<IpRange>,
1769 /// Addresses in scope whose presence the phase reached no verdict on.
1770 ///
1771 /// See [`undecided`](Self::undecided).
1772 undecided: Vec<IpRange>,
1773 /// Why this port phase ran with no liveness pass in front of it, or `None`.
1774 /// See [`liveness_skipped`](Self::liveness_skipped).
1775 liveness_skipped: Option<LivenessSkip>,
1776 /// Addresses asked on every port that answered none, and so no host. See
1777 /// [`silent`](Self::silent).
1778 silent: Vec<IpRange>,
1779 /// Why the scan was stopped while this phase ran. See
1780 /// [`stopped`](Self::stopped).
1781 stopped: Option<StopReason>,
1782 /// The passes a stop skipped or cut short, in the order a scan runs them.
1783 /// See [`passes_cut`](Self::passes_cut).
1784 passes_cut: Vec<Pass>,
1785 /// Targets it never asked and holds on no host. See
1786 /// [`unreached`](Self::unreached).
1787 unreached: u128,
1788 /// Targets asked at addresses the phase lists no host at. See
1789 /// [`unheard_probes`](Self::unheard_probes).
1790 unheard_probes: u128,
1791 probes: Vec<ProbeStats>,
1792 /// Which document this phase was folded in from, for a merged report.
1793 origin: Option<PhaseOrigin>,
1794 /// Which switch ports the machine running this phase was plugged into.
1795 attachments: Vec<Attachment>,
1796 /// Whether this is the phase as it stood before it closed. See
1797 /// [`is_open`](Self::is_open).
1798 open: bool,
1799}
1800
1801impl ScanPhase {
1802 /// Which document this phase came from, for one folded into a merged report
1803 /// from elsewhere. `None` for a phase this process measured.
1804 pub fn origin(&self) -> Option<&PhaseOrigin> {
1805 self.origin.as_ref()
1806 }
1807
1808 /// Where the machine running this phase was plugged in, as the equipment on
1809 /// the far end of the cable announced itself.
1810 ///
1811 /// Empty for a phase that heard no announcement, as on an unmanaged network.
1812 pub fn attachments(&self) -> &[Attachment] {
1813 &self.attachments
1814 }
1815
1816 /// Which entry point this phase records.
1817 pub fn kind(&self) -> ScanKind {
1818 self.kind
1819 }
1820
1821 /// When the phase began.
1822 pub fn started_at(&self) -> SystemTime {
1823 self.started_at
1824 }
1825
1826 /// How long the phase ran, measured monotonically.
1827 pub fn elapsed(&self) -> Duration {
1828 self.elapsed
1829 }
1830
1831 /// Whether the engine held the privileges its raw strategies need. An
1832 /// unprivileged phase reached its targets over plain TCP connect attempts,
1833 /// which see less and are more visible to the target.
1834 ///
1835 /// `None` for a phase this engine did not measure, such as one imported from
1836 /// another scanner's report.
1837 pub fn privilege(&self) -> Option<Privilege> {
1838 self.privilege
1839 }
1840
1841 /// What the phase was asked to cover.
1842 pub fn targets(&self) -> &TargetScope {
1843 &self.targets
1844 }
1845
1846 /// The settings the phase ran under.
1847 pub fn settings(&self) -> &ScanSettings {
1848 &self.settings
1849 }
1850
1851 /// Addresses this host could not reach, so no probe was sent to them,
1852 /// ascending: no route or source address led to them, or they are
1853 /// neighbours on a local segment that never answered address resolution.
1854 ///
1855 /// Not [`failures`](Self::failures), and not counted as partial. An address here was
1856 /// never probed.
1857 pub fn unroutable(&self) -> &[IpAddr] {
1858 &self.unroutable
1859 }
1860
1861 /// The addresses among [`unroutable`](Self::unroutable) that this host's
1862 /// own routing table refuses, ascending.
1863 ///
1864 /// A `prohibit`, `blackhole` or `unreachable` route, or a VPN kill switch's rules,
1865 /// is host policy that every program honours, so the engine sends such an address
1866 /// nothing. Named apart because the remedy is on this machine.
1867 ///
1868 /// Named where the engine can tell: a neighbour on one of this host's segments,
1869 /// whose connected route only a policy overrides; and any address the kernel
1870 /// refuses with an error only a policy produces (permission denied for `prohibit`,
1871 /// invalid argument for `blackhole`, on Linux). An `unreachable` route elsewhere
1872 /// looks like a missing route and is not named here.
1873 pub fn refused_by_route(&self) -> &[IpAddr] {
1874 &self.refused_by_route
1875 }
1876
1877 /// Addresses the phase left before it had finished with them, because the
1878 /// per-host budget in
1879 /// [`ScanSettings::host_timeout`](ScanSettings::host_timeout) ran out.
1880 ///
1881 /// A host named here still carries every port the phase managed to ask.
1882 pub fn timed_out(&self) -> &[IpAddr] {
1883 &self.timed_out
1884 }
1885
1886 /// Addresses whose ICMP errors this phase found rate-limited, ascending.
1887 ///
1888 /// A closed UDP port is known only by its host's ICMP port unreachable, which hosts
1889 /// ration (Linux: a burst, then about one a second). On a host here most closed ports
1890 /// read `OpenOrNoReply`, so its open-or-no-reply ports are mostly closed.
1891 ///
1892 /// Inferred from the host's answers: a port answered closed only when asked again,
1893 /// after others answered at once, while more ports stayed silent than answered,
1894 /// which a filter does not produce.
1895 ///
1896 /// Needs a port asked more than once, so only raw-socket scans name hosts here.
1897 pub fn icmp_rate_limited(&self) -> &[IpAddr] {
1898 &self.icmp_rate_limited
1899 }
1900
1901 /// Addresses this phase reached by TCP connect although it held the
1902 /// privilege its raw strategies need, ascending.
1903 ///
1904 /// Some addresses are beyond a raw probe whatever the privilege: loopback, and
1905 /// anything with no route. A process that can inject frames but holds no raw socket
1906 /// (an unprivileged macOS run with BPF access) also cannot reach this host's own
1907 /// addresses, anything routed through a tunnel, or, for port probes, an IPv6
1908 /// neighbour. Those were probed by connect, so their evidence is connect evidence
1909 /// although [`privilege`](Self::privilege) reads raw, and the configured technique
1910 /// was not used.
1911 ///
1912 /// An address no probe could leave for is [unroutable](Self::unroutable) instead.
1913 ///
1914 /// Empty for most phases, and for every [`Privilege::Connect`] phase.
1915 pub fn reached_by_connect(&self) -> &[IpRange] {
1916 &self.reached_by_connect
1917 }
1918
1919 /// Addresses in this phase's scope whose presence it reached no verdict on,
1920 /// ascending.
1921 ///
1922 /// A discovery phase settles an address when something answers or the retry budget
1923 /// is spent. An address here is neither: the phase stopped before or while asking,
1924 /// had no strategy that could ask, was refused the range, or ran out the address's
1925 /// time budget. None is a host found down; a port scan leaves their ports unsettled
1926 /// and a resumed job asks again. Without this list, an address never asked would
1927 /// look like one that stayed silent.
1928 ///
1929 /// Disjoint from [`unroutable`](Self::unroutable). An address can be here and in
1930 /// [`timed_out`](Self::timed_out), which says why.
1931 ///
1932 /// A port phase standing in for a dropped liveness pass (see
1933 /// [`LivenessSkip::PortsNoDearer`]) names here addresses it heard nothing from
1934 /// without finishing asking; the report lists no host for them and a resumed job
1935 /// asks their ports again. If such a phase never closed, it names every address it
1936 /// had not yet decided.
1937 ///
1938 /// Empty for other port scans, which settle ports rather than presence, and for
1939 /// listeners.
1940 pub fn undecided(&self) -> &[IpRange] {
1941 &self.undecided
1942 }
1943
1944 /// Why this port phase ran with no liveness pass in front of it.
1945 ///
1946 /// `None` when a liveness pass preceded it (recorded as its own
1947 /// [`Discovery`](ScanKind::Discovery) phase), and for every phase that is not a
1948 /// [`PortScan`](ScanKind::PortScan). The reasons differ in what the findings mean;
1949 /// see [`LivenessSkip`].
1950 pub fn liveness_skipped(&self) -> Option<LivenessSkip> {
1951 self.liveness_skipped
1952 }
1953
1954 /// Addresses this port phase asked on every port it named and heard
1955 /// nothing from at all, ascending.
1956 ///
1957 /// Filled only where the phase stood in for a dropped liveness pass; see
1958 /// [`LivenessSkip::PortsNoDearer`]. An address that drew no open port, closed port
1959 /// or ICMP error is named here, not listed as a host. Its ports were asked, so it is
1960 /// not [`undecided`](Self::undecided), and a comparison reads it as covered and
1961 /// quiet.
1962 ///
1963 /// Empty for every other phase. With [`ZondConfig::assume_up`] every address is a
1964 /// host.
1965 pub fn silent(&self) -> &[IpRange] {
1966 &self.silent
1967 }
1968
1969 /// Why the scan was stopped while this phase was running: the caller
1970 /// asked ([`Aborted`](StopReason::Aborted)), or the scan's own budget ran
1971 /// out ([`TimedOut`](StopReason::TimedOut)).
1972 ///
1973 /// `None` for a phase that ended on its own, and for every
1974 /// [`Listen`](ScanKind::Listen) phase, which always ends by being stopped.
1975 ///
1976 /// A marker, not a verdict: what a stop cut shows as [`unreached`](Self::unreached)
1977 /// targets, unasked ports, undecided addresses and
1978 /// [`passes_cut`](Self::passes_cut), which [`ScanReport::is_partial`] reads. This
1979 /// adds the reason.
1980 pub fn stopped(&self) -> Option<StopReason> {
1981 self.stopped
1982 }
1983
1984 /// The passes over what the probes found that a stop skipped or cut
1985 /// short, in the order a scan runs them. Empty for a phase no stop cut,
1986 /// and for one stopped before any pass had work to do.
1987 ///
1988 /// Only passes the scan was asked to run and had work for: with TLS enumeration
1989 /// off, or no TLS port found, no TLS pass is named. [`ScanReport::is_partial`]
1990 /// counts these.
1991 ///
1992 /// A pass cut short on some ports by a detection's budget or the file limit is a
1993 /// [failure](Self::failures) marked cut short, naming the port.
1994 pub fn passes_cut(&self) -> &[Pass] {
1995 &self.passes_cut
1996 }
1997
1998 /// Whether this is the phase as it stood before it closed: a record kept as it ran,
1999 /// for a sitting killed outright.
2000 ///
2001 /// From a journal, an open phase was killed or still running when read. It records
2002 /// what the phase opened with, how long it ran and what failed, but nothing only its
2003 /// close establishes (no [stop](Self::stopped), [unreached](Self::unreached) target
2004 /// or [pass cut](Self::passes_cut)), so [`ScanReport::is_partial`] counts it.
2005 ///
2006 /// Not a [`StopReason`]: nothing running names a kill.
2007 pub fn is_open(&self) -> bool {
2008 self.open
2009 }
2010
2011 /// How many of this port phase's targets it never asked and holds on no
2012 /// host: the ones its walk never reached because the scan was stopped
2013 /// first, the ones it passed for an address its liveness pass reached no
2014 /// verdict on, and the ones left unasked at an address it then listed no
2015 /// host at, being [`undecided`](Self::undecided).
2016 ///
2017 /// A count, since a permuted walk scatters what a stop leaves across every address,
2018 /// and a `/16` on every port stopped a minute in would list billions. Every target
2019 /// the phase was handed was probed (counted by its hosts and
2020 /// [`unheard_probes`](Self::unheard_probes)), is on its host
2021 /// [`Unasked`](crate::model::port::PortState::Unasked), is counted here, or was
2022 /// settled without a probe (silent, unreachable, or excluded).
2023 ///
2024 /// A resumed job asks every one of them. Zero for a phase that asked everything,
2025 /// and for every non-[`PortScan`](ScanKind::PortScan) phase. See
2026 /// [`ScanReport::unreached`] for several sittings.
2027 pub fn unreached(&self) -> u128 {
2028 self.unreached
2029 }
2030
2031 /// How many of this port phase's targets it asked at the addresses it
2032 /// lists no host at: every port of the ones it names
2033 /// [`silent`](Self::silent), and the ports it reached of the ones it names
2034 /// [`undecided`](Self::undecided).
2035 ///
2036 /// Those addresses' records are dropped, so a count of probed ports read off the
2037 /// hosts comes up short by exactly this. The scope cannot supply it, since a mixed
2038 /// scope records a union and an undecided address was asked only part of its ports.
2039 ///
2040 /// Each sitting of a resumed job counts its own, and the counts add up. A phase that
2041 /// never closed counts the probes of its silent addresses; the sitting that decides
2042 /// the undecided ones counts theirs. Zero for every phase that did not stand in for
2043 /// a liveness pass, and in a record without the count.
2044 pub fn unheard_probes(&self) -> u128 {
2045 self.unheard_probes
2046 }
2047
2048 /// The strategies in this phase that could not do their job.
2049 pub fn failures(&self) -> &[ScannerFailure] {
2050 &self.failures
2051 }
2052
2053 /// Ground this phase declined to cover, and why.
2054 ///
2055 /// With [`failures`](Self::failures), everything the phase did not answer. See
2056 /// [`Refusal`].
2057 pub fn refusals(&self) -> &[Refusal] {
2058 &self.refusals
2059 }
2060
2061 /// What each instrumented scanner observed about its own run.
2062 ///
2063 /// Empty where no strategy carries instrumentation; the TCP-connect fallback has no
2064 /// capture to audit.
2065 pub fn probe_stats(&self) -> &[ProbeStats] {
2066 &self.probes
2067 }
2068}
2069
2070// --------------------------------------------------------------------------
2071// The report itself
2072// --------------------------------------------------------------------------
2073//
2074// What the phases and hosts add up to. Counts are computed from the hosts on demand.
2075
2076/// Counts derived from a report's hosts.
2077///
2078/// Computed on demand by [`ScanReport::summary`].
2079///
2080/// `hosts_alive` and `ports_open` each come with a full distribution, since a blocked
2081/// port is evidence of a firewall and a closed one of a live host, and neither is
2082/// silence.
2083#[non_exhaustive]
2084#[derive(Debug, Clone, Default, PartialEq, Eq)]
2085pub struct ScanSummary {
2086 /// Hosts recorded, whatever their status.
2087 pub hosts_total: usize,
2088 /// Hosts confirmed to be on the network, either responding or blocked.
2089 pub hosts_alive: usize,
2090 /// How many hosts fell into each status.
2091 pub hosts_by_status: BTreeMap<HostStatus, usize>,
2092 /// Port records across all hosts.
2093 pub ports_total: usize,
2094 /// Ports found accepting connections.
2095 pub ports_open: usize,
2096 /// How many ports fell into each state.
2097 pub ports_by_state: BTreeMap<PortState, usize>,
2098 /// Ports whose service was identified by fingerprinting.
2099 ///
2100 /// A name read off the port number is not counted (see
2101 /// [`Service::is_inferred`](crate::model::port::Service::is_inferred)).
2102 pub services_identified: usize,
2103 /// How many hosts were reachable at an IPv4 address, at an IPv6 one, and at
2104 /// both.
2105 ///
2106 /// Per host. The three overlap and do not sum to
2107 /// [`hosts_total`](Self::hosts_total): a dual-stack host counts in all three.
2108 pub hosts_by_family: FamilyCounts,
2109}
2110
2111/// Hosts counted by the address families they answered at.
2112#[non_exhaustive]
2113#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
2114pub struct FamilyCounts {
2115 /// Hosts with at least one IPv4 address.
2116 pub ipv4: usize,
2117 /// Hosts with at least one IPv6 address.
2118 pub ipv6: usize,
2119 /// Hosts with both, counted again here.
2120 pub dual_stack: usize,
2121}
2122
2123/// Everything known about a completed scan.
2124///
2125/// Obtained from [`ScanTask::join`](crate::scanner::ScanTask::join) once a scan
2126/// finishes. See the [module documentation](self) for how it relates to the
2127/// live [`ScanSession`](crate::scanner::session::ScanSession).
2128#[derive(Debug, Clone)]
2129#[must_use = "a report is the record of the scan that just ran; dropping it discards it"]
2130pub struct ScanReport {
2131 /// Which build produced the findings. Borrowed for a scan this build ran, owned for
2132 /// one read back.
2133 engine_version: Cow<'static, str>,
2134 phases: Vec<ScanPhase>,
2135 /// Keyed by [`ScopedIp`], since `fe80::1` names a different machine on every segment.
2136 /// The zone is dropped from addresses that do not need one, so ordering is by
2137 /// address with the zone breaking ties. [`pairing`](crate::diff::pairing) draws the
2138 /// same distinction.
2139 hosts: BTreeMap<ScopedIp, Host>,
2140}
2141
2142impl ScanReport {
2143 /// Builds a single-phase report over the hosts a scan produced.
2144 ///
2145 /// Hosts are keyed by their reported address (with interface where needed), so a host
2146 /// with several addresses appears once and two link-locals on different segments stay
2147 /// two.
2148 pub fn new(phase: ScanPhase, hosts: impl IntoIterator<Item = Host>) -> Self {
2149 let mut report = Self {
2150 engine_version: Cow::Borrowed(ENGINE_VERSION),
2151 phases: vec![phase],
2152 hosts: index(hosts),
2153 };
2154 report.forget_the_silent();
2155 report
2156 }
2157
2158 /// A report over the phases of a job that ran in more than one sitting.
2159 ///
2160 /// For a resumed scan, whose earlier sittings are restored from a journal. `phases`
2161 /// is kept in the order given.
2162 ///
2163 /// Attributed to this build, which is continuing the job. Use
2164 /// [`recorded`](Self::recorded) to rebuild a report nothing is continuing.
2165 pub fn from_phases(phases: Vec<ScanPhase>, hosts: impl IntoIterator<Item = Host>) -> Self {
2166 Self::attributed(Cow::Borrowed(ENGINE_VERSION), phases, hosts)
2167 }
2168
2169 /// A report rebuilt from what an earlier scan wrote down, attributed to the
2170 /// engine that ran it.
2171 ///
2172 /// For reading a finished scan back from a journal or an exported report. The
2173 /// version comes from the record, so a scan run by 0.11 still says 0.11 when 0.12
2174 /// reads it.
2175 pub fn recorded(
2176 engine_version: impl Into<String>,
2177 phases: Vec<ScanPhase>,
2178 hosts: impl IntoIterator<Item = Host>,
2179 ) -> Self {
2180 Self::attributed(Cow::Owned(engine_version.into()), phases, hosts)
2181 }
2182
2183 fn attributed(
2184 engine_version: Cow<'static, str>,
2185 phases: Vec<ScanPhase>,
2186 hosts: impl IntoIterator<Item = Host>,
2187 ) -> Self {
2188 let mut report = Self {
2189 engine_version,
2190 phases,
2191 hosts: index(hosts),
2192 };
2193 report.forget_the_silent();
2194 report
2195 }
2196
2197 /// The engine version that produced this report.
2198 pub fn engine_version(&self) -> &str {
2199 &self.engine_version
2200 }
2201
2202 /// The phases that contributed to this report, in the order they ran.
2203 ///
2204 /// A report a scan produced has at least one. One rebuilt with
2205 /// [`recorded`](Self::recorded) can have none, if the scan stopped before writing
2206 /// a phase.
2207 pub fn phases(&self) -> &[ScanPhase] {
2208 &self.phases
2209 }
2210
2211 /// Whether this report was folded out of documents rather than measured by
2212 /// one run.
2213 ///
2214 /// True when any phase carries a [`PhaseOrigin`], which only
2215 /// [`merge`](crate::merge) writes.
2216 ///
2217 /// For a merged report [`elapsed`](Self::elapsed) sums several scanners' working
2218 /// time and is not the duration of anything; the span is
2219 /// [`finished_at`](Self::finished_at) less [`started_at`](Self::started_at).
2220 pub fn is_merged(&self) -> bool {
2221 self.phases.iter().any(|phase| phase.origin().is_some())
2222 }
2223
2224 /// Every host recorded, ordered by primary IP.
2225 pub fn hosts(&self) -> impl Iterator<Item = &Host> {
2226 self.hosts.values()
2227 }
2228
2229 /// Every host recorded, to be changed in place.
2230 ///
2231 /// Crate-private, since a report is a record. Used by
2232 /// [`cve::correlate_report`](crate::cve::correlate_report), which adds conclusions
2233 /// from what the scan already knew.
2234 pub(crate) fn hosts_mut(&mut self) -> impl Iterator<Item = &mut Host> {
2235 self.hosts.values_mut()
2236 }
2237
2238 /// The number of hosts recorded.
2239 pub fn host_count(&self) -> usize {
2240 self.hosts.len()
2241 }
2242
2243 /// Looks up a host by the address it is reported under.
2244 ///
2245 /// For two link-locals with the same number on different segments, this answers
2246 /// with the first; [`host_scoped`](Self::host_scoped) can tell them apart.
2247 pub fn host(&self, ip: &IpAddr) -> Option<&Host> {
2248 self.hosts
2249 .range(ScopedIp::unscoped(*ip)..)
2250 .next()
2251 .filter(|(key, _)| key.addr() == *ip)
2252 .map(|(_, host)| host)
2253 }
2254
2255 /// Looks up a host by the address it is reported under, together with the
2256 /// interface that address is valid on.
2257 ///
2258 /// The exact lookup, for a link-local: `fe80::1%en0` and `fe80::1%en1` are two
2259 /// hosts.
2260 pub fn host_scoped(&self, ip: &ScopedIp) -> Option<&Host> {
2261 self.hosts.get(ip)
2262 }
2263
2264 /// Takes this report's phases, consuming it.
2265 ///
2266 /// For assembling a new report out of several. Read the hosts through
2267 /// [`hosts`](Self::hosts) first.
2268 pub fn into_phases(self) -> Vec<ScanPhase> {
2269 self.phases
2270 }
2271
2272 /// When the earliest phase began.
2273 pub fn started_at(&self) -> SystemTime {
2274 self.phases
2275 .iter()
2276 .map(ScanPhase::started_at)
2277 .min()
2278 .unwrap_or_else(SystemTime::now)
2279 }
2280
2281 /// When the latest phase stopped looking.
2282 ///
2283 /// The moment the findings are *as of*, for judging them against a clock: a
2284 /// certificate's remaining validity, staleness, which report is later. Each phase
2285 /// ends at its own `started_at + elapsed`.
2286 ///
2287 /// A phase whose end cannot be represented is placed at its start. An imported
2288 /// document's `elapsed` (nmap's is unbounded decimal seconds) may exceed what a
2289 /// [`SystemTime`] holds, and the checked addition avoids a panic; the understatement
2290 /// is safe.
2291 pub fn finished_at(&self) -> SystemTime {
2292 self.phases
2293 .iter()
2294 .map(|phase| {
2295 phase
2296 .started_at()
2297 .checked_add(phase.elapsed())
2298 .unwrap_or_else(|| phase.started_at())
2299 })
2300 .max()
2301 .unwrap_or_else(SystemTime::now)
2302 }
2303
2304 /// The moment this report is judged to have happened.
2305 ///
2306 /// [`finished_at`](Self::finished_at) for a report with phases. For a merged report,
2307 /// taking the earliest start would judge tonight's certificates against last
2308 /// quarter.
2309 ///
2310 /// A report without phases is placed by the latest time any host was seen.
2311 ///
2312 /// The clock [`merge`](crate::merge) and [`diff`](crate::diff) order documents by;
2313 /// public so a caller can order them the same way.
2314 pub fn observed_at(&self) -> SystemTime {
2315 if !self.phases.is_empty() {
2316 return self.finished_at();
2317 }
2318
2319 self.hosts()
2320 .map(Host::last_seen)
2321 .max()
2322 .unwrap_or_else(SystemTime::now)
2323 }
2324
2325 /// How long the engine spent scanning, summed over the phases.
2326 ///
2327 /// Working time, excluding whatever the caller did between phases. For the
2328 /// wall-clock span, use [`finished_at`](Self::finished_at) less
2329 /// [`started_at`](Self::started_at).
2330 pub fn elapsed(&self) -> Duration {
2331 self.phases.iter().map(ScanPhase::elapsed).sum()
2332 }
2333
2334 /// Every strategy failure across all phases, in the order they were
2335 /// recorded.
2336 pub fn failures(&self) -> impl Iterator<Item = &ScannerFailure> {
2337 self.phases.iter().flat_map(ScanPhase::failures)
2338 }
2339
2340 /// Every refusal, across all phases.
2341 pub fn refusals(&self) -> impl Iterator<Item = &Refusal> {
2342 self.phases.iter().flat_map(ScanPhase::refusals)
2343 }
2344
2345 /// Every instrumented scanner's counters, across all phases.
2346 pub fn probe_stats(&self) -> impl Iterator<Item = &ProbeStats> {
2347 self.phases.iter().flat_map(ScanPhase::probe_stats)
2348 }
2349
2350 /// Whether the findings are narrower than the caller asked for.
2351 ///
2352 /// True wherever part of the request went unanswered: a strategy that did not
2353 /// complete, a [refusal](Self::refusals), a host its budget left early that no
2354 /// phase finished ([`timed_out`](Self::timed_out)), an address with no verdict
2355 /// ([`undecided`](Self::undecided)), a port recorded
2356 /// [`Unasked`](crate::model::port::PortState::Unasked), a target never asked that
2357 /// no host holds ([`unreached`](Self::unreached)), a pass a stop left
2358 /// ([`passes_cut`](Self::passes_cut)), or a phase killed before it closed
2359 /// ([`ScanPhase::is_open`]).
2360 ///
2361 /// Read over the whole report: what one phase left open and another (a resumed
2362 /// sitting, a merged source) closed is closed. Failures and refusals always count,
2363 /// since neither says which ground it cost.
2364 ///
2365 /// Not counted: unreachable addresses ([`ScanPhase::unroutable`]) and their unasked
2366 /// ports, addresses an exclusion withheld, and a journal that could not be written,
2367 /// none of which is coverage that fell short.
2368 pub fn is_partial(&self) -> bool {
2369 self.phases.iter().any(|phase| {
2370 phase.failures.iter().any(ScannerFailure::narrows_coverage)
2371 || !phase.refusals.is_empty()
2372 }) || !self.timed_out().is_empty()
2373 || !self.undecided().is_empty()
2374 || self.left_ports_unasked()
2375 || self.unreached() > 0
2376 || !self.passes_cut().is_empty()
2377 || self.left_open()
2378 }
2379
2380 /// Whether a phase here is [open](ScanPhase::is_open) and no later phase
2381 /// of its kind from the same account closed: the report of a job whose
2382 /// last sitting was killed, or is still running.
2383 ///
2384 /// On the terms [`passes_cut`](Self::passes_cut) gives.
2385 pub fn left_open(&self) -> bool {
2386 self.phases.iter().enumerate().any(|(at, phase)| {
2387 phase.open
2388 && !self.phases[at + 1..].iter().any(|later| {
2389 later.kind == phase.kind && later.origin == phase.origin && !later.open
2390 })
2391 })
2392 }
2393
2394 /// The passes a stop left that no later sitting of the same account ran,
2395 /// in the order a scan runs them.
2396 ///
2397 /// Stands until a later phase of the same kind from the same account, as with
2398 /// [`unreached`](Self::unreached): a resumed sitting runs the passes over every host
2399 /// the stopped one found. Across accounts a pass stands.
2400 pub fn passes_cut(&self) -> Vec<Pass> {
2401 let mut passes: Vec<Pass> = self
2402 .phases
2403 .iter()
2404 .enumerate()
2405 .filter(|(at, phase)| {
2406 !self.phases[at + 1..]
2407 .iter()
2408 .any(|later| later.kind == phase.kind && later.origin == phase.origin)
2409 })
2410 .flat_map(|(_, phase)| phase.passes_cut.iter().copied())
2411 .collect();
2412 passes.sort_unstable();
2413 passes.dedup();
2414 passes
2415 }
2416
2417 /// How many port targets this report's phases never asked and hold on no
2418 /// host, and no later sitting of the same account took up.
2419 ///
2420 /// A phase's [`unreached`](ScanPhase::unreached) count is replaced by a later phase
2421 /// of the same kind from the same account, since a resumed sitting walks what the
2422 /// earlier one left. The account is the document a phase came from, or this engine's
2423 /// own run for a phase with no [`origin`](ScanPhase::origin).
2424 ///
2425 /// Across accounts a count stands, since it names no targets.
2426 pub fn unreached(&self) -> u128 {
2427 self.phases
2428 .iter()
2429 .enumerate()
2430 .filter(|(at, phase)| {
2431 phase.unreached > 0
2432 && !self.phases[at + 1..]
2433 .iter()
2434 .any(|later| later.kind == phase.kind && later.origin == phase.origin)
2435 })
2436 .map(|(_, phase)| phase.unreached)
2437 .fold(0u128, u128::saturating_add)
2438 }
2439
2440 /// The addresses whose presence this report reached no verdict on,
2441 /// ascending: named [`undecided`](ScanPhase::undecided) by some phase, and
2442 /// decided by none.
2443 ///
2444 /// An address is decided by a phase that walked it without naming it undecided, by
2445 /// a live host at it, or by some phase finding it unreachable. So a resumed sitting
2446 /// or a later merged sweep closes what an earlier one left open. Read by
2447 /// [`is_partial`](Self::is_partial) and comparisons.
2448 pub fn undecided(&self) -> Vec<IpRange> {
2449 let mut open = IpSet::new();
2450 let mut decided = IpSet::new();
2451 for phase in &self.phases {
2452 let mut left = IpSet::new();
2453 for range in &phase.undecided {
2454 left.insert_range(*range);
2455 }
2456 let mut walked = IpSet::new();
2457 for range in phase.targets.ranges() {
2458 walked.insert_range(*range);
2459 }
2460 walked.subtract(&left);
2461 append(&mut open, &left);
2462 append(&mut decided, &walked);
2463 for address in &phase.unroutable {
2464 decided.insert(*address);
2465 }
2466 }
2467 if open.is_empty() {
2468 return Vec::new();
2469 }
2470 open.subtract(&decided);
2471 open.canonicalize();
2472
2473 // Last: only the live hosts' addresses still open can change the result.
2474 let alive = listed_within(self.hosts.values().filter(|host| host.is_alive()), &open);
2475 open.subtract(&alive);
2476 open.canonicalize();
2477 let v4 = open.v4().iter().copied().map(IpRange::V4);
2478 let v6 = open.v6().iter().copied().map(IpRange::V6);
2479 v4.chain(v6).collect()
2480 }
2481
2482 /// The addresses a phase's own time budget left early and no phase
2483 /// finished, ascending.
2484 ///
2485 /// A phase of the same kind that walked an address without running out of time
2486 /// finishes it; a sweep says nothing about ports a port scan left unasked. Each
2487 /// phase keeps its own [`timed_out`](ScanPhase::timed_out) list.
2488 pub fn timed_out(&self) -> Vec<IpAddr> {
2489 let walked: Vec<IpSet> = self
2490 .phases
2491 .iter()
2492 .map(|phase| {
2493 let mut walked = IpSet::new();
2494 for range in phase.targets.ranges() {
2495 walked.insert_range(*range);
2496 }
2497 walked.canonicalize();
2498 walked
2499 })
2500 .collect();
2501
2502 let mut left: Vec<IpAddr> = self
2503 .phases
2504 .iter()
2505 .flat_map(|phase| phase.timed_out.iter().map(move |ip| (phase.kind, *ip)))
2506 .filter(|(kind, ip)| {
2507 !self.phases.iter().zip(&walked).any(|(other, walked)| {
2508 other.kind == *kind && walked.contains(ip) && !other.timed_out.contains(ip)
2509 })
2510 })
2511 .map(|(_, ip)| ip)
2512 .collect();
2513 left.sort_unstable();
2514 left.dedup();
2515 left
2516 }
2517
2518 /// Whether any host this report could reach carries a port recorded
2519 /// [`Unasked`](crate::model::port::PortState::Unasked): named by the scan,
2520 /// and never probed.
2521 ///
2522 /// A host whose every address a phase names unroutable is left out, as
2523 /// [`is_partial`](Self::is_partial) does not count it.
2524 ///
2525 /// Ports are read first, so a report with nothing unasked reads no addresses.
2526 pub(crate) fn left_ports_unasked(&self) -> bool {
2527 let mut unasked = self
2528 .hosts
2529 .values()
2530 .filter(|host| {
2531 host.ports()
2532 .any(|port| port.state() == crate::model::port::PortState::Unasked)
2533 })
2534 .peekable();
2535 if unasked.peek().is_none() {
2536 return false;
2537 }
2538
2539 let unroutable: std::collections::BTreeSet<&IpAddr> = self
2540 .phases
2541 .iter()
2542 .flat_map(|phase| phase.unroutable.iter())
2543 .collect();
2544 unasked.any(|host| host.ips().iter().any(|ip| !unroutable.contains(ip)))
2545 }
2546
2547 /// Counts derived from the recorded hosts.
2548 pub fn summary(&self) -> ScanSummary {
2549 let mut summary = ScanSummary::default();
2550
2551 for host in self.hosts.values() {
2552 summary.hosts_total += 1;
2553 if host.is_alive() {
2554 summary.hosts_alive += 1;
2555 }
2556 *summary.hosts_by_status.entry(host.status()).or_default() += 1;
2557
2558 let v4 = host.ips().iter().any(IpAddr::is_ipv4);
2559 let v6 = host.ips().iter().any(IpAddr::is_ipv6);
2560 summary.hosts_by_family.ipv4 += usize::from(v4);
2561 summary.hosts_by_family.ipv6 += usize::from(v6);
2562 summary.hosts_by_family.dual_stack += usize::from(v4 && v6);
2563
2564 for port in host.ports() {
2565 summary.ports_total += 1;
2566 if port.state() == PortState::Open {
2567 summary.ports_open += 1;
2568 }
2569 *summary.ports_by_state.entry(port.state()).or_default() += 1;
2570 if port.service().is_some_and(|service| !service.is_inferred()) {
2571 summary.services_identified += 1;
2572 }
2573 }
2574 }
2575
2576 summary
2577 }
2578
2579 /// The hosts this report found alive, as targets for a port scan.
2580 ///
2581 /// The join between the two phases: sweep a range cheaply, then port-scan only what
2582 /// answered.
2583 ///
2584 /// ```no_run
2585 /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
2586 /// use zond_engine::{PortSet, ZondConfig, discover, scan};
2587 /// use zond_engine::detect::Detections;
2588 /// use zond_engine::model::parse::ip::to_set;
2589 ///
2590 /// let cfg = ZondConfig::default();
2591 /// let (_, sweep) = discover(to_set(&["192.0.2.0/24"], None, None)?, &cfg).await?;
2592 /// let mut report = sweep.join().await?;
2593 ///
2594 /// // The sweep established these hosts answer, so skip a second liveness pass.
2595 /// let mut scanning = cfg.clone();
2596 /// scanning.assume_up = true;
2597 /// let targets = report.alive_targets(PortSet::try_from("22,80,443")?);
2598 /// let (_, ports) = scan(targets, &scanning, Detections::embedded()).await?;
2599 /// report.merge(ports.join().await?);
2600 /// # Ok(())
2601 /// # }
2602 /// ```
2603 ///
2604 /// Only hosts for which [`Host::is_alive`] holds, so [`Down`](HostStatus::Down) and
2605 /// [`Unknown`](HostStatus::Unknown) hosts are left out.
2606 ///
2607 /// One address per host, [`Host::primary_ip`], so a dual-stack host is scanned
2608 /// once. Build the set from [`Host::ips`] to scan every address.
2609 ///
2610 /// A link-local address carries the interface it was found on.
2611 pub fn alive_targets(&self, ports: PortSet) -> TargetMap {
2612 let mut ips = IpSet::new();
2613
2614 for host in self.hosts.values().filter(|host| host.is_alive()) {
2615 match host.primary_ip() {
2616 IpAddr::V4(v4) => {
2617 if let Ok(range) = Ipv4Range::new(v4, v4) {
2618 ips.push_v4_range(range);
2619 }
2620 }
2621 IpAddr::V6(v6) => {
2622 // Kept only for addresses that need it, as `ScopedIp` does.
2623 let zone = v6
2624 .is_unicast_link_local()
2625 .then(|| host.zone().and_then(Zone::index))
2626 .flatten();
2627 if let Ok(range) = Ipv6Range::scoped(v6, v6, zone) {
2628 ips.push_v6_range(range);
2629 }
2630 }
2631 }
2632 }
2633
2634 ips.canonicalize();
2635
2636 let mut targets = TargetMap::new();
2637 // No empty unit, or `scan` would report a phase that covered nothing.
2638 if !ips.is_empty() {
2639 targets.add_unit(TargetSet::new(ips, ports));
2640 }
2641 targets
2642 }
2643
2644 /// Folds a later phase of the same job into this report.
2645 ///
2646 /// Hosts present in both are combined with [`Host::merge`], so a host
2647 /// discovered in the first phase keeps its MAC and telemetry when the second
2648 /// adds its ports. Phases and their failures are appended in call order.
2649 ///
2650 /// The engine version is left as this report's.
2651 pub fn merge(&mut self, other: ScanReport) {
2652 self.fold(other, Host::merge);
2653 }
2654
2655 /// Folds `later`, a report closed against the same live hosts as this one
2656 /// and after it, into this report.
2657 ///
2658 /// For a scan that closes one phase and continues with the same store: a host in
2659 /// both reports is one host copied twice, and its round trips would count twice. So
2660 /// the later's round trips replace these; see [`Host::merge_later_account`].
2661 /// Everything else folds as [`merge`](Self::merge) does.
2662 pub(crate) fn merge_later_copy(&mut self, later: ScanReport) {
2663 self.fold(later, Host::merge_later_account);
2664 }
2665
2666 /// Appends `other`'s phases and folds its hosts into these by `fold`.
2667 fn fold(&mut self, other: ScanReport, fold: fn(&mut Host, Host)) {
2668 self.phases.extend(other.phases);
2669
2670 for (key, host) in other.hosts {
2671 match self.hosts.get_mut(&key) {
2672 Some(existing) => fold(existing, host),
2673 None => {
2674 self.hosts.insert(key, host);
2675 }
2676 }
2677 }
2678 self.forget_the_silent();
2679 }
2680
2681 /// Drops every host nothing was heard from at an address a phase names
2682 /// [`silent`](ScanPhase::silent).
2683 ///
2684 /// Applied wherever a report is assembled (scan, journal, merge), since a journal
2685 /// may already hold a record of an address later found silent. See [`Unheard`].
2686 fn forget_the_silent(&mut self) {
2687 let unheard = Unheard::of(&self.phases);
2688 if unheard.is_empty() {
2689 return;
2690 }
2691 self.hosts.retain(|_, host| !unheard.drops(host));
2692 }
2693}
2694
2695/// The addresses a set of phases heard nothing from and lists no host at: what
2696/// a port phase standing in for a liveness pass named
2697/// [`silent`](ScanPhase::silent), and what it named
2698/// [`undecided`](ScanPhase::undecided).
2699///
2700/// Shared by every place such a record is dropped (report assembly, journal restore,
2701/// a journal's findings file at the end of a sitting), so they agree.
2702///
2703/// A discovery phase's undecided addresses are left alone.
2704pub(crate) struct Unheard(IpSet);
2705
2706impl Unheard {
2707 /// The addresses `phases` heard nothing from.
2708 pub(crate) fn of<'a>(phases: impl IntoIterator<Item = &'a ScanPhase>) -> Self {
2709 Self::reading(phases, true)
2710 }
2711
2712 /// The addresses `phases` heard nothing from, less those a phase that
2713 /// never closed has yet to decide: what a sitting continuing the job
2714 /// leaves out of what it restores.
2715 ///
2716 /// A killed port phase standing in for liveness names every undecided address; the
2717 /// next sitting restores those records and decides them. Silent addresses were
2718 /// decided and stay out.
2719 #[cfg(feature = "journal-format")]
2720 pub(crate) fn decided<'a>(phases: impl IntoIterator<Item = &'a ScanPhase>) -> Self {
2721 Self::reading(phases, false)
2722 }
2723
2724 /// [`of`](Self::of), or [`decided`](Self::decided) where `pending` is
2725 /// false.
2726 fn reading<'a>(phases: impl IntoIterator<Item = &'a ScanPhase>, pending: bool) -> Self {
2727 let mut unheard = IpSet::new();
2728 for phase in phases {
2729 for range in &phase.silent {
2730 unheard.insert_range(*range);
2731 }
2732 if phase.kind == ScanKind::PortScan && (pending || !phase.open) {
2733 for range in &phase.undecided {
2734 unheard.insert_range(*range);
2735 }
2736 }
2737 }
2738 unheard.canonicalize();
2739 Self(unheard)
2740 }
2741
2742 /// Whether no phase heard nothing from anything, so nothing is dropped.
2743 pub(crate) fn is_empty(&self) -> bool {
2744 self.0.is_empty()
2745 }
2746
2747 /// Whether `host` is a record to drop: one still
2748 /// [`Unknown`](HostStatus::Unknown) at an address heard nothing from.
2749 ///
2750 /// A host that answered in any phase or merged document stays.
2751 pub(crate) fn drops(&self, host: &Host) -> bool {
2752 host.status() == HostStatus::Unknown && host.ips().iter().any(|ip| self.0.contains(ip))
2753 }
2754}
2755
2756/// The addresses `hosts` are listed at that fall inside `within`.
2757///
2758/// Only these affect subtracting the hosts from `within`, and collecting every address
2759/// would copy the largest thing in the report. `within` should be merged.
2760fn listed_within<'h>(hosts: impl Iterator<Item = &'h Host>, within: &IpSet) -> IpSet {
2761 let mut listed = IpSet::new();
2762 if within.is_empty() {
2763 return listed;
2764 }
2765 for address in hosts.flat_map(Host::ips) {
2766 if within.contains(address) {
2767 listed.insert(*address);
2768 }
2769 }
2770 listed
2771}
2772
2773/// Adds every range of `from` to `into`, leaving the merge for later.
2774fn append(into: &mut IpSet, from: &IpSet) {
2775 for range in from.v4() {
2776 into.push_v4_range(*range);
2777 }
2778 for range in from.v6() {
2779 into.push_v6_range(*range);
2780 }
2781}
2782
2783/// Keys hosts by the address each is reported under.
2784///
2785/// Two records with the same key are folded, as the live store does.
2786fn index(hosts: impl IntoIterator<Item = Host>) -> BTreeMap<ScopedIp, Host> {
2787 let mut indexed: BTreeMap<ScopedIp, Host> = BTreeMap::new();
2788
2789 for host in hosts {
2790 match indexed.get_mut(&host.scoped_ip()) {
2791 Some(existing) => existing.merge(host),
2792 None => {
2793 indexed.insert(host.scoped_ip(), host);
2794 }
2795 }
2796 }
2797
2798 indexed
2799}
2800
2801// ╔════════════════════════════════════════════╗
2802// ║ ████████╗███████╗███████╗████████╗███████╗ ║
2803// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
2804// ║ ██║ █████╗ ███████╗ ██║ ███████╗ ║
2805// ║ ██║ ██╔══╝ ╚════██║ ██║ ╚════██║ ║
2806// ║ ██║ ███████╗███████║ ██║ ███████║ ║
2807// ║ ╚═╝ ╚══════╝╚══════╝ ╚═╝ ╚══════╝ ║
2808// ╚════════════════════════════════════════════╝
2809
2810// --------------------------------------------------------------------------
2811// Naming the strategies
2812// --------------------------------------------------------------------------
2813//
2814// Which strategy a failure, refusal or set of counters belongs to.
2815
2816/// Which scanning strategy a [`ScanEvent::ScannerFailed`](crate::scanner::session::ScanEvent::ScannerFailed) refers to.
2817#[non_exhaustive]
2818#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2819pub enum ScannerKind {
2820 /// Layer-2 discovery (ARP/NDP) on a local segment.
2821 Local,
2822 /// Reading a link's own traffic, having sent nothing.
2823 ///
2824 /// Sends nothing, so `sends_attempted` is always zero, and a quiet run means a quiet
2825 /// segment, not an absent host.
2826 Passive,
2827 /// Raw TCP SYN discovery for gateway-routed targets.
2828 Routed,
2829 /// The same sweep asking over SCTP: one INIT per address, for a scan whose
2830 /// ports name SCTP.
2831 ///
2832 /// Separate from [`Routed`](Self::Routed): a host behind a filter that passes SCTP
2833 /// and drops TCP answers only this.
2834 RoutedSctp,
2835 /// Raw TCP SYN port scanning (the port-scan phase, distinct from [`Routed`]
2836 /// host discovery).
2837 ///
2838 /// [`Routed`]: ScannerKind::Routed
2839 SynPort,
2840 /// Raw TCP port scanning with a probe that is not a SYN - a FIN, a flagless
2841 /// segment, a bare ACK.
2842 ///
2843 /// The same scanner as [`SynPort`], named apart because no half-open connection was
2844 /// attempted. The technique is in the phase's settings.
2845 ///
2846 /// [`SynPort`]: ScannerKind::SynPort
2847 TcpPort,
2848 /// Unprivileged TCP connect fallback, for both host discovery and port
2849 /// scanning.
2850 Connect,
2851 /// Unprivileged UDP fallback.
2852 ///
2853 /// Separate from [`Connect`], so a report says which half of an unprivileged scan
2854 /// failed.
2855 ///
2856 /// [`Connect`]: ScannerKind::Connect
2857 ConnectUdp,
2858 /// Privileged raw UDP port scanning.
2859 UdpPort,
2860 /// Privileged raw SCTP port scanning: an INIT chunk per port, classified by
2861 /// the chunk that answers it.
2862 ///
2863 /// No unprivileged fallback and no service pass, so its failure means the SCTP ports
2864 /// went unprobed.
2865 SctpPort,
2866 /// The active operating-system echo probe, sent at the hosts the passive
2867 /// sources could not name.
2868 ///
2869 /// Establishes no port state; it asks which stack answers the ping.
2870 OsEcho,
2871 /// The active operating-system series probe: one host asked the same
2872 /// question several times, so the policies behind its counters become
2873 /// visible.
2874 ///
2875 /// Sends the same segment as [`SynPort`] but revisits settled ports, and no reply
2876 /// changes a port's state.
2877 ///
2878 /// [`SynPort`]: ScannerKind::SynPort
2879 OsSeries,
2880 /// The active operating-system management probe: one SNMP `GetRequest` at a
2881 /// host whose kernel is not otherwise known.
2882 ///
2883 /// Establishes no port state; the answer is filed against the *host*.
2884 OsSnmp,
2885 /// The idle (zombie) TCP port scan: port states read off a third party's
2886 /// IP-ID counter rather than from any reply the target sent this scanner.
2887 ///
2888 /// Separate from [`SynPort`](Self::SynPort): verdicts are only `Open` or
2889 /// `ClosedOrNoReply`, and a run is refused without a suitable zombie or an Ethernet
2890 /// path.
2891 Idle,
2892 /// Composite scanner that delegates to protocol-specific scanners.
2893 Composite,
2894 /// The service-identification pass, which opens a connection to each open
2895 /// port a raw scan classified without ever holding one, and the same
2896 /// identification made inline over the connection a connect scan found a
2897 /// port open on, wherever what it left is about services rather than
2898 /// states.
2899 ///
2900 /// Separate from [`Connect`]: a connect failure loses port *states*; this losing
2901 /// work leaves states standing and services unidentified.
2902 ///
2903 /// [`Connect`]: ScannerKind::Connect
2904 Service,
2905 /// The detection pass, which runs the authored corpus over the services the
2906 /// scan identified.
2907 ///
2908 /// Separate from [`Service`], since it can fail alone and lose only findings.
2909 ///
2910 /// [`Service`]: ScannerKind::Service
2911 Detection,
2912 /// The journal a scan was writing itself into.
2913 ///
2914 /// Not a strategy; here because failures are the channel every consumer reads. A
2915 /// failed checkpoint costs only what a *resume* would have skipped.
2916 Journal,
2917 /// The hostname resolver a scan names its hosts with: the passive one
2918 /// that reads a link's DNS and mDNS, or the reverse lookups asked of the
2919 /// system's resolver.
2920 ///
2921 /// Loses only names; without this, missing hostnames would read as hosts that have
2922 /// none.
2923 Resolver,
2924}
2925
2926/// What a `CongestionWindow` did over one run.
2927///
2928/// Says whether pacing engaged and how hard, which tells "this host is firewalled" from
2929/// "this host was asked too fast".
2930#[non_exhaustive]
2931#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2932pub struct WindowSummary {
2933 /// The window at the end of the run.
2934 pub capacity: usize,
2935 /// The largest it reached.
2936 pub peak: usize,
2937 /// How many times it was cut.
2938 pub reductions: u32,
2939 /// Whether it was allowed to move at all.
2940 pub adaptive: bool,
2941 /// Whether it finished cut back as far as it is permitted to go.
2942 ///
2943 /// The scan was still being outrun when it stopped, so recorded silence may be loss.
2944 /// The remedy is a narrower scan.
2945 pub at_floor: bool,
2946}
2947
2948impl WindowSummary {
2949 /// A summary from what a window did: where it started, the widest it
2950 /// reached, how often it was cut, whether it could move at all, and
2951 /// whether it ended at its floor.
2952 pub const fn new(
2953 capacity: usize,
2954 peak: usize,
2955 reductions: u32,
2956 adaptive: bool,
2957 at_floor: bool,
2958 ) -> Self {
2959 Self {
2960 capacity,
2961 peak,
2962 reductions,
2963 adaptive,
2964 at_floor,
2965 }
2966 }
2967}
2968
2969impl ScannerKind {
2970 /// Every strategy this build knows, in declaration order. Checked against the
2971 /// published schema.
2972 pub const ALL: &'static [Self] = &[
2973 Self::Local,
2974 Self::Passive,
2975 Self::Routed,
2976 Self::RoutedSctp,
2977 Self::SynPort,
2978 Self::TcpPort,
2979 Self::Connect,
2980 Self::ConnectUdp,
2981 Self::UdpPort,
2982 Self::SctpPort,
2983 Self::OsEcho,
2984 Self::OsSeries,
2985 Self::OsSnmp,
2986 Self::Idle,
2987 Self::Composite,
2988 Self::Service,
2989 Self::Detection,
2990 Self::Journal,
2991 Self::Resolver,
2992 ];
2993
2994 /// What a raw TCP scan carrying `technique` reports itself as.
2995 ///
2996 /// Shared by the plan and the running scanner, so a strategy files its failures
2997 /// under one name.
2998 pub const fn for_raw_tcp(technique: TcpScanTechnique) -> Self {
2999 match technique {
3000 TcpScanTechnique::Syn => Self::SynPort,
3001 _ => Self::TcpPort,
3002 }
3003 }
3004}
3005
3006impl fmt::Display for WindowSummary {
3007 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3008 if !self.adaptive {
3009 return write!(f, "fixed {}", self.capacity);
3010 }
3011 write!(
3012 f,
3013 "{} (peak {}, cut {}x){}",
3014 self.capacity,
3015 self.peak,
3016 self.reductions,
3017 if self.at_floor { " at floor" } else { "" }
3018 )
3019 }
3020}
3021
3022#[cfg(test)]
3023mod tests {
3024
3025 /// A run with no elapsed time has no achieved rate.
3026 #[test]
3027 fn a_scanners_achieved_send_rate_is_its_sends_over_its_run() {
3028 let mut stats = crate::export::fixture::probe_stats();
3029 stats.sends_attempted = 500;
3030 stats.elapsed = Duration::from_millis(250);
3031 assert_eq!(stats.achieved_send_rate(), Some(2000.0));
3032
3033 stats.elapsed = Duration::ZERO;
3034 assert_eq!(stats.achieved_send_rate(), None);
3035 }
3036
3037 /// A phase counts every address its policy kept out, each once, including neighbours
3038 /// and addresses an excluded machine answered from.
3039 #[test]
3040 fn a_phase_counts_every_address_its_policy_withheld_once() {
3041 let address = |text: &str| -> IpAddr { text.parse().expect("literal") };
3042 let mut targets = IpSet::new();
3043 targets.insert_range("192.0.2.0/29".parse().expect("a valid range"));
3044 let mut named = IpSet::new();
3045 named.insert(address("192.0.2.5"));
3046 // The machine at .5, as the tables tied it before the phase began: its
3047 // global IPv6 address, which is no target of the phase.
3048 let policy = Exclusions::new(named).widened([address("2001:db8::5")]);
3049
3050 let mut scope = TargetScope::from_ip_set(&mut targets, &policy);
3051 assert_eq!(scope.withheld(), 1, "the one target the policy names");
3052
3053 scope.record_withheld(
3054 // Tied before the phase, and heard during it.
3055 vec![address("2001:db8::5"), address("fe80::5")],
3056 // Kept from the sweep's neighbour-table candidates.
3057 vec![address("2001:db8::5")],
3058 );
3059
3060 assert_eq!(
3061 scope.withheld(),
3062 3,
3063 "the target, the neighbour kept from the sweep and the address heard"
3064 );
3065 let excluded: Vec<IpAddr> = scope
3066 .excluded()
3067 .iter()
3068 .map(|range| range.start_addr())
3069 .collect();
3070 assert_eq!(
3071 excluded,
3072 vec![
3073 address("192.0.2.5"),
3074 address("2001:db8::5"),
3075 address("fe80::5")
3076 ]
3077 );
3078 }
3079
3080 /// A uniform port set can say an endpoint was probed; a mixed one cannot.
3081 #[test]
3082 fn a_scope_says_whether_its_addresses_agree_about_ports() {
3083 use crate::model::parse::ip::to_set;
3084 use crate::model::port::PortSet;
3085 use crate::model::target::TargetSet;
3086
3087 let unit = |cidr: &str, ports: &str| {
3088 TargetSet::new(
3089 to_set(&[cidr], None, None).expect("a range"),
3090 PortSet::try_from(ports).expect("a port specification"),
3091 )
3092 };
3093
3094 let mut same = TargetMap::new();
3095 same.add_unit(unit("192.0.2.0/30", "80,443"));
3096 same.add_unit(unit("198.51.100.0/30", "80,443"));
3097 let scope = TargetScope::from_target_map(&mut same, &Exclusions::none());
3098 assert_eq!(
3099 scope.ports().covers(443, Protocol::Tcp),
3100 Some(true),
3101 "every address was walked for it"
3102 );
3103 assert_eq!(scope.ports().covers(8080, Protocol::Tcp), Some(false));
3104
3105 let mut differing = TargetMap::new();
3106 differing.add_unit(unit("192.0.2.0/30", "80,443"));
3107 differing.add_unit(unit("198.51.100.0/30", "8080"));
3108 let scope = TargetScope::from_target_map(&mut differing, &Exclusions::none());
3109 assert_eq!(
3110 scope.ports().covers(8080, Protocol::Tcp),
3111 None,
3112 "walked for one unit and not the other, so the scope cannot say"
3113 );
3114 assert_eq!(
3115 scope.ports().covers(9999, Protocol::Tcp),
3116 Some(false),
3117 "absent from the union means walked for no address at all"
3118 );
3119 }
3120
3121 /// A sweep's scope is `NoPorts`, not `Unstated`.
3122 #[test]
3123 fn a_discovery_sweep_walked_no_ports_and_says_so() {
3124 let mut ips = crate::model::parse::ip::to_set(&["192.0.2.0/30"], None, None).unwrap();
3125 let scope = TargetScope::from_ip_set(&mut ips, &Exclusions::none());
3126
3127 assert_eq!(*scope.ports(), PortScope::NoPorts);
3128 assert_eq!(scope.ports().covers(80, Protocol::Tcp), Some(false));
3129 }
3130 use super::*;
3131 use crate::model::ip::range::Ipv4Range;
3132 use crate::model::port::{Port, PortSet, Service};
3133 use crate::model::target::TargetSet;
3134 use std::net::Ipv4Addr;
3135 use std::str::FromStr;
3136
3137 fn ip(last: u8) -> IpAddr {
3138 IpAddr::V4(Ipv4Addr::new(203, 0, 113, last))
3139 }
3140
3141 fn phase(kind: ScanKind) -> ScanPhase {
3142 ScanPhase {
3143 open: false,
3144 attachments: Vec::new(),
3145 kind,
3146 started_at: SystemTime::UNIX_EPOCH,
3147 elapsed: Duration::from_millis(500),
3148 privilege: Some(Privilege::Raw),
3149 targets: TargetScope::from_ip_set(&mut IpSet::new(), &Exclusions::none()),
3150 settings: ScanSettings::from(&ZondConfig::default()),
3151 failures: Vec::new(),
3152 refusals: Vec::new(),
3153 unroutable: Vec::new(),
3154 refused_by_route: Vec::new(),
3155 timed_out: Vec::new(),
3156 icmp_rate_limited: Vec::new(),
3157 reached_by_connect: Vec::new(),
3158 undecided: Vec::new(),
3159 liveness_skipped: None,
3160 silent: Vec::new(),
3161 stopped: None,
3162 passes_cut: Vec::new(),
3163 unreached: 0,
3164 unheard_probes: 0,
3165 probes: Vec::new(),
3166 origin: None,
3167 }
3168 }
3169
3170 /// A port phase that stood in for a dropped liveness pass, naming `silent`
3171 /// the addresses it asked and heard nothing from.
3172 fn standing_in(silent: &[u8]) -> ScanPhase {
3173 let mut phase = phase(ScanKind::PortScan);
3174 phase.liveness_skipped = Some(LivenessSkip::PortsNoDearer);
3175 phase.silent = silent
3176 .iter()
3177 .map(|&last| {
3178 let v4 = Ipv4Addr::new(203, 0, 113, last);
3179 IpRange::V4(Ipv4Range::new(v4, v4).expect("a range"))
3180 })
3181 .collect();
3182 phase
3183 }
3184
3185 /// A host the scanners filed at an address, and nothing heard from it.
3186 fn unheard(last: u8) -> Host {
3187 let mut host = Host::new(ip(last));
3188 host.add_port(Port::new(443, Protocol::Tcp, PortState::NoReply));
3189 host
3190 }
3191
3192 /// **A live host inside an undecided range closes it, and only hosts inside are
3193 /// gathered.**
3194 #[test]
3195 fn only_a_live_host_inside_what_was_left_open_is_gathered_to_close_it() {
3196 use crate::model::ip::set::ranges_added;
3197
3198 let mut sweep = phase(ScanKind::Discovery);
3199 let (first, last) = (Ipv4Addr::new(203, 0, 113, 0), Ipv4Addr::new(203, 0, 113, 9));
3200 sweep
3201 .undecided
3202 .push(IpRange::V4(Ipv4Range::new(first, last).expect("a range")));
3203
3204 let alive = |ip: IpAddr| {
3205 let mut host = Host::new(ip);
3206 host.set_status(HostStatus::Up);
3207 host
3208 };
3209 let outside: Vec<Host> = (0..=255)
3210 .map(|last| alive(IpAddr::V4(Ipv4Addr::new(198, 51, 100, last))))
3211 .collect();
3212 let inside = alive(ip(5));
3213
3214 let mut open = IpSet::new();
3215 open.insert_range(sweep.undecided[0]);
3216 open.canonicalize();
3217 let hosts = [&inside].into_iter().chain(&outside);
3218 assert_eq!(listed_within(hosts, &open).len(), 1);
3219
3220 let live_outside = outside.len();
3221 let report = ScanReport::new(sweep, outside.into_iter().chain([inside]));
3222 let v4 = |a, b| IpRange::V4(Ipv4Range::new(ip4(a), ip4(b)).expect("a range"));
3223 let before = ranges_added::so_far();
3224 assert_eq!(report.undecided(), [v4(0, 4), v4(6, 9)]);
3225 let added = ranges_added::so_far() - before;
3226 assert!(
3227 added < live_outside,
3228 "{added} ranges were gathered to close what was left open, beside \
3229 {live_outside} live hosts outside it"
3230 );
3231 }
3232
3233 fn ip4(last: u8) -> Ipv4Addr {
3234 Ipv4Addr::new(203, 0, 113, last)
3235 }
3236
3237 /// Unasked ports count only on hosts that some phase could route to.
3238 #[test]
3239 fn ports_left_unasked_count_only_on_a_host_the_scan_could_reach() {
3240 let unasked = |last| {
3241 let mut host = Host::new(ip(last));
3242 host.set_status(HostStatus::Up);
3243 host.add_port(Port::new(22, Protocol::Tcp, PortState::Unasked));
3244 host
3245 };
3246 let mut sweep = phase(ScanKind::Discovery);
3247 sweep.unroutable.push(ip(1));
3248
3249 assert!(!ScanReport::new(sweep.clone(), [unasked(1)]).left_ports_unasked());
3250 assert!(ScanReport::new(sweep.clone(), [unasked(1), unasked(2)]).left_ports_unasked());
3251
3252 let mut asked = Host::new(ip(3));
3253 asked.add_port(Port::new(22, Protocol::Tcp, PortState::Open));
3254 assert!(!ScanReport::new(sweep, [asked]).left_ports_unasked());
3255 }
3256
3257 /// **A report with no port unasked reads no host addresses; one with some reads only
3258 /// the hosts holding one.**
3259 #[test]
3260 fn ports_left_unasked_are_looked_for_without_reading_every_host() {
3261 use crate::model::host::address_reads;
3262
3263 let asked: Vec<Host> = (0..=255)
3264 .map(|last| {
3265 let mut host = Host::new(IpAddr::V4(Ipv4Addr::new(198, 51, 100, last)));
3266 host.set_status(HostStatus::Up);
3267 host.add_port(Port::new(22, Protocol::Tcp, PortState::Open));
3268 host
3269 })
3270 .collect();
3271 let mut unasked = Host::new(ip(1));
3272 unasked.set_status(HostStatus::Up);
3273 unasked.add_port(Port::new(22, Protocol::Tcp, PortState::Unasked));
3274
3275 let nothing_left = ScanReport::new(phase(ScanKind::PortScan), asked.clone());
3276 let before = address_reads::so_far();
3277 assert!(!nothing_left.left_ports_unasked());
3278 assert_eq!(
3279 address_reads::so_far() - before,
3280 0,
3281 "a report that left nothing unasked read its hosts' addresses"
3282 );
3283
3284 let one_left = ScanReport::new(
3285 phase(ScanKind::PortScan),
3286 asked.into_iter().chain([unasked]),
3287 );
3288 let before = address_reads::so_far();
3289 assert!(one_left.left_ports_unasked());
3290 assert_eq!(
3291 address_reads::so_far() - before,
3292 1,
3293 "addresses were read beyond the one host with a port unasked"
3294 );
3295 }
3296
3297 /// A silent or undecided address of a port phase standing in for liveness is not a
3298 /// host. A host that answered is kept, as is an unanswering one at an address the
3299 /// phase does not name, and a discovery phase's undecided addresses keep their
3300 /// records.
3301 #[test]
3302 fn a_host_nothing_answered_at_an_undecided_address_is_not_a_host() {
3303 let mut ports = standing_in(&[]);
3304 let mut sweep = phase(ScanKind::Discovery);
3305 for (phase, last) in [(&mut ports, 5), (&mut sweep, 9)] {
3306 let v4 = Ipv4Addr::new(203, 0, 113, last);
3307 phase
3308 .undecided
3309 .push(IpRange::V4(Ipv4Range::new(v4, v4).expect("a range")));
3310 }
3311
3312 let report = ScanReport::new(ports, [unheard(5)]);
3313 assert!(
3314 report.host(&ip(5)).is_none(),
3315 "an undecided address is no host"
3316 );
3317 let report = ScanReport::new(sweep, [unheard(9)]);
3318 assert!(report.host(&ip(9)).is_some());
3319 }
3320
3321 #[test]
3322 fn a_host_nothing_answered_at_a_silent_address_is_not_a_host() {
3323 let mut up = Host::new(ip(1));
3324 up.set_status(HostStatus::Up);
3325
3326 let report = ScanReport::new(standing_in(&[5]), [up, unheard(5), unheard(9)]);
3327
3328 assert!(report.host(&ip(5)).is_none(), "a silent address is no host");
3329 assert!(
3330 report.host(&ip(1)).is_some(),
3331 "a host that answered is kept"
3332 );
3333 assert!(
3334 report.host(&ip(9)).is_some(),
3335 "an address the phase does not name silent keeps its record"
3336 );
3337 }
3338
3339 /// A journal record written before its address was found silent is still dropped.
3340 #[test]
3341 fn a_journalled_record_at_a_silent_address_is_dropped_on_read_back() {
3342 let resumed = ScanReport::from_phases(vec![standing_in(&[5])], [unheard(5)]);
3343 assert!(resumed.host(&ip(5)).is_none());
3344
3345 let recorded = ScanReport::recorded("0.17.0", vec![standing_in(&[5])], [unheard(5)]);
3346 assert!(recorded.host(&ip(5)).is_none());
3347 }
3348
3349 /// A host heard from elsewhere stays a host after a merge with a phase that found
3350 /// its address silent.
3351 #[test]
3352 fn a_host_heard_elsewhere_survives_a_phase_that_found_it_silent() {
3353 let mut up = Host::new(ip(5));
3354 up.set_status(HostStatus::Up);
3355 let mut earlier = ScanReport::new(phase(ScanKind::Discovery), [up]);
3356
3357 earlier.merge(ScanReport::new(standing_in(&[5]), [unheard(5)]));
3358
3359 assert!(
3360 earlier
3361 .host(&ip(5))
3362 .is_some_and(|host| host.status() == HostStatus::Up),
3363 "the merge kept the host an earlier phase heard"
3364 );
3365 }
3366
3367 /// A phase whose end overflows `SystemTime` is placed at its start, without
3368 /// panicking. An nmap XML `elapsed="1222222222…"` is enough to reach it, through
3369 /// `ScanDiff::between`.
3370 #[test]
3371 fn a_phase_claiming_more_time_than_a_clock_holds_does_not_end_the_process() {
3372 let mut absurd = phase(ScanKind::PortScan);
3373 absurd.started_at = SystemTime::UNIX_EPOCH;
3374 absurd.elapsed = Duration::from_secs(u64::MAX);
3375
3376 let ordinary = phase(ScanKind::Discovery);
3377 let ends_at = ordinary.started_at + ordinary.elapsed;
3378
3379 let report = ScanReport::recorded("zond", vec![absurd, ordinary], Vec::new());
3380
3381 assert_eq!(
3382 report.finished_at(),
3383 ends_at,
3384 "the phase that could be placed is the one that should place the report"
3385 );
3386
3387 // The comparison that reads it.
3388 assert!(crate::diff::ScanDiff::between(&report, &report).is_empty());
3389 }
3390
3391 fn ip_set(spec: &str) -> IpSet {
3392 let mut set = IpSet::new();
3393 set.insert_range(IpRange::from_str(spec).expect("valid range"));
3394 set
3395 }
3396
3397 #[test]
3398 fn scope_merges_overlapping_ranges_before_counting() {
3399 let mut ips = ip_set("203.0.113.0/24");
3400 ips.insert_range(IpRange::from_str("203.0.113.128/25").expect("valid range"));
3401
3402 let scope = TargetScope::from_ip_set(&mut ips, &Exclusions::none());
3403
3404 // The second range is inside the first, so the scope is one /24.
3405 assert_eq!(scope.ranges().len(), 1);
3406 assert_eq!(scope.addresses(), 256);
3407 assert_eq!(scope.probes(), None);
3408 assert!(scope.protocols().is_empty());
3409 }
3410
3411 #[test]
3412 fn port_scan_scope_counts_probes_not_addresses() {
3413 let ports = PortSet::from_iter([
3414 (80, Protocol::Tcp),
3415 (443, Protocol::Tcp),
3416 (53, Protocol::Udp),
3417 ]);
3418
3419 let mut targets = TargetMap::new();
3420 targets.add_unit(TargetSet::new(ip_set("192.0.2.1-192.0.2.4"), ports));
3421
3422 let scope = TargetScope::from_target_map(&mut targets, &Exclusions::none());
3423
3424 assert_eq!(scope.addresses(), 4);
3425 assert_eq!(scope.probes(), Some(12));
3426 assert_eq!(scope.protocols(), &[Protocol::Tcp, Protocol::Udp]);
3427 }
3428
3429 /// A run that put something different on the wire records different settings.
3430 #[test]
3431 fn settings_record_what_changed_the_scan() {
3432 let scanning = ZondConfig {
3433 no_dns: true,
3434 ..Default::default()
3435 };
3436
3437 assert_ne!(
3438 ScanSettings::from(&scanning),
3439 ScanSettings::from(&ZondConfig::default())
3440 );
3441 }
3442
3443 #[test]
3444 fn summary_counts_states_and_services() {
3445 let mut up = Host::new(ip(1));
3446 up.set_status(HostStatus::Up);
3447 up.add_port(
3448 Port::new(22, Protocol::Tcp, PortState::Open).with_service(Service::new("ssh", 90)),
3449 );
3450 up.add_port(Port::new(80, Protocol::Tcp, PortState::Open));
3451 up.add_port(Port::new(81, Protocol::Tcp, PortState::NoReply));
3452
3453 let mut blocked = Host::new(ip(2));
3454 blocked.set_status(HostStatus::Blocked);
3455
3456 let mut down = Host::new(ip(3));
3457 down.set_status(HostStatus::Down);
3458
3459 let report = ScanReport::new(phase(ScanKind::PortScan), [up, blocked, down]);
3460 let summary = report.summary();
3461
3462 assert_eq!(summary.hosts_total, 3);
3463 assert_eq!(summary.hosts_alive, 2);
3464 assert_eq!(summary.hosts_by_status[&HostStatus::Up], 1);
3465 assert_eq!(summary.hosts_by_status[&HostStatus::Down], 1);
3466 assert_eq!(summary.ports_total, 3);
3467 assert_eq!(summary.ports_open, 2);
3468 assert_eq!(summary.ports_by_state[&PortState::NoReply], 1);
3469 assert_eq!(summary.services_identified, 1);
3470 }
3471
3472 /// Names inferred from port numbers are not counted as identified.
3473 #[test]
3474 fn summary_counts_no_name_read_off_a_port_number_as_identified() {
3475 let mut host = Host::new(ip(1));
3476 host.set_status(HostStatus::Up);
3477 host.add_port(
3478 Port::new(22, Protocol::Tcp, PortState::Open).with_service(Service::new("ssh", 90)),
3479 );
3480 host.add_port(
3481 Port::new(80, Protocol::Tcp, PortState::Open).with_service(Service::new("http", 0)),
3482 );
3483 host.add_port(
3484 Port::new(23, Protocol::Tcp, PortState::Closed).with_service(Service::new("telnet", 0)),
3485 );
3486
3487 let summary = ScanReport::new(phase(ScanKind::PortScan), [host]).summary();
3488
3489 assert_eq!(summary.services_identified, 1);
3490 }
3491
3492 /// Only alive hosts become port-scan targets.
3493 #[test]
3494 fn only_hosts_that_answered_become_port_scan_targets() {
3495 let mut up = Host::new(ip(1));
3496 up.set_status(HostStatus::Up);
3497 let mut blocked = Host::new(ip(2));
3498 blocked.set_status(HostStatus::Blocked);
3499 let mut down = Host::new(ip(3));
3500 down.set_status(HostStatus::Down);
3501 let unknown = Host::new(ip(4));
3502
3503 let report = ScanReport::new(phase(ScanKind::Discovery), [up, blocked, down, unknown]);
3504
3505 let targets = report.alive_targets(PortSet::from_iter([(80, Protocol::Tcp)]));
3506
3507 // Up and Blocked are alive; Down and Unknown are not.
3508 assert_eq!(targets.gross_ips().expect("countable"), 2);
3509 assert_eq!(targets.gross_targets().expect("countable"), 2);
3510 }
3511
3512 /// A dual-stack host is scanned once, at its primary address.
3513 #[test]
3514 fn a_dual_stack_host_is_scanned_once() {
3515 let mut dual = Host::new(ip(1));
3516 dual.set_status(HostStatus::Up);
3517 dual.add_ip(IpAddr::from_str("2001:db8::1").unwrap());
3518
3519 let report = ScanReport::new(phase(ScanKind::Discovery), [dual]);
3520 let targets = report.alive_targets(PortSet::from_iter([(80, Protocol::Tcp)]));
3521
3522 assert_eq!(targets.gross_ips().expect("countable"), 1);
3523 }
3524
3525 /// A link-local target carries the zone the sweep found it on.
3526 #[test]
3527 fn a_link_local_target_keeps_the_interface_it_was_found_on() {
3528 let lla: IpAddr = "fe80::10".parse().unwrap();
3529 let mut host = Host::new(lla);
3530 host.set_status(HostStatus::Up);
3531 host.set_zone(Zone::new(7, "en0"));
3532
3533 let report = ScanReport::new(phase(ScanKind::Discovery), [host]);
3534 let targets = report.alive_targets(PortSet::from_iter([(80, Protocol::Tcp)]));
3535
3536 let zones: Vec<Option<u32>> = targets
3537 .units
3538 .iter()
3539 .flat_map(|unit| unit.ips().v6().iter().map(|range| range.zone()))
3540 .collect();
3541 assert_eq!(zones, vec![Some(7)]);
3542 }
3543
3544 /// A sweep that found nothing yields no units.
3545 #[test]
3546 fn a_sweep_that_found_nothing_yields_no_targets() {
3547 let report = ScanReport::new(phase(ScanKind::Discovery), [Host::new(ip(1))]);
3548 let targets = report.alive_targets(PortSet::from_iter([(80, Protocol::Tcp)]));
3549
3550 assert!(targets.is_empty());
3551 assert!(targets.units.is_empty());
3552 }
3553
3554 #[test]
3555 fn hosts_are_ordered_by_ip_regardless_of_discovery_order() {
3556 let scrambled = [Host::new(ip(30)), Host::new(ip(2)), Host::new(ip(17))];
3557 let report = ScanReport::new(phase(ScanKind::Discovery), scrambled);
3558
3559 let order: Vec<IpAddr> = report.hosts().map(Host::primary_ip).collect();
3560 assert_eq!(order, vec![ip(2), ip(17), ip(30)]);
3561 }
3562
3563 #[test]
3564 fn merge_combines_hosts_and_keeps_phase_order() {
3565 let mut discovered = Host::new(ip(1));
3566 discovered.set_status(HostStatus::Up);
3567 discovered.add_rtt(Duration::from_millis(3));
3568 let mut first = ScanReport::new(phase(ScanKind::Discovery), [discovered]);
3569
3570 let mut scanned = Host::new(ip(1));
3571 scanned.add_port(Port::new(443, Protocol::Tcp, PortState::Open));
3572 let second = ScanReport::new(phase(ScanKind::PortScan), [scanned, Host::new(ip(9))]);
3573
3574 first.merge(second);
3575
3576 // The port scan's record of .1 has no status or telemetry; the merge keeps
3577 // discovery's.
3578 let host = first.host(&ip(1)).expect("host survives the merge");
3579 assert_eq!(host.status(), HostStatus::Up);
3580 assert_eq!(host.port_count(), 1);
3581 assert!(host.min_rtt().is_some());
3582
3583 assert_eq!(first.host_count(), 2);
3584 assert_eq!(
3585 first
3586 .phases()
3587 .iter()
3588 .map(ScanPhase::kind)
3589 .collect::<Vec<_>>(),
3590 vec![ScanKind::Discovery, ScanKind::PortScan]
3591 );
3592 assert_eq!(first.elapsed(), Duration::from_secs(1));
3593 }
3594
3595 #[test]
3596 fn failures_are_visible_across_phases() {
3597 let mut failed = phase(ScanKind::Discovery);
3598 failed.failures.push(ScannerFailure::new(
3599 ScannerKind::Routed,
3600 "raw socket unavailable",
3601 ));
3602
3603 let clean = ScanReport::new(phase(ScanKind::PortScan), []);
3604 let mut report = ScanReport::new(failed, []);
3605 report.merge(clean);
3606
3607 assert!(report.is_partial());
3608 assert_eq!(report.failures().count(), 1);
3609 }
3610
3611 /// Work cut short by a limit makes the report partial, like a failure.
3612 #[test]
3613 fn work_a_limit_cut_short_narrows_the_report_as_a_failure_does() {
3614 let mut phase = phase(ScanKind::PortScan);
3615 phase.failures.push(ScannerFailure::cut_short(
3616 ScannerKind::Connect,
3617 "1 port left unasked: source port 53 still closing",
3618 ));
3619 let report = ScanReport::new(phase, []);
3620
3621 assert!(report.is_partial());
3622 let failure = report.failures().next().expect("filed");
3623 assert!(failure.is_cut_short());
3624 assert!(!ScannerFailure::new(ScannerKind::Connect, "refused").is_cut_short());
3625 }
3626
3627 /// A cut pass makes the report partial until a later sitting of the same job runs
3628 /// it; another document's scan does not close it.
3629 #[test]
3630 fn a_pass_a_stop_cut_makes_a_scan_partial_until_a_later_sitting_runs_it() {
3631 let stopped = |passes: Vec<Pass>, origin: Option<PhaseOrigin>| {
3632 let recorded = phase(ScanKind::PortScan);
3633 ScanPhase {
3634 passes_cut: passes,
3635 origin,
3636 ..recorded
3637 }
3638 };
3639
3640 let cut = ScanReport::new(stopped(vec![Pass::Detections, Pass::Services], None), []);
3641 assert!(cut.is_partial());
3642 assert_eq!(cut.passes_cut(), [Pass::Services, Pass::Detections]);
3643
3644 let mut resumed = cut.clone();
3645 resumed.merge(ScanReport::new(stopped(Vec::new(), None), []));
3646 assert!(!resumed.is_partial(), "the next sitting ran them");
3647
3648 let mut merged = cut;
3649 merged.merge(ScanReport::new(
3650 stopped(
3651 Vec::new(),
3652 Some(PhaseOrigin::new("0.18").with_label("elsewhere")),
3653 ),
3654 [],
3655 ));
3656 assert!(merged.is_partial(), "another account says nothing of them");
3657 }
3658
3659 /// A journal that could not be written is kept in the report and does not
3660 /// make a scan that covered everything read as partial.
3661 #[test]
3662 fn a_journal_that_could_not_be_written_does_not_make_a_scan_partial() {
3663 let mut phase = phase(ScanKind::PortScan);
3664 phase.failures.push(ScannerFailure::new(
3665 ScannerKind::Journal,
3666 "checkpoint failed: no space left on device",
3667 ));
3668 let report = ScanReport::new(phase, []);
3669
3670 assert_eq!(report.failures().count(), 1, "the failure is kept");
3671 assert!(!report.is_partial());
3672 }
3673
3674 /// **A rebuild reads each distribution for the slots this build counts**, dropping
3675 /// extra slots and zeroing missing ones.
3676 #[test]
3677 fn a_rebuild_fits_each_distribution_to_the_slots_this_build_counts() {
3678 let parts = |answered_on: Vec<u64>, found_at: Vec<u64>| ProbeStatsParts {
3679 scanner: ScannerKind::Composite,
3680 targets: 1,
3681 stop_reason: StopReason::AllResponded,
3682 elapsed: Duration::from_secs(1),
3683 sends_attempted: 0,
3684 sends_failed: 0,
3685 sends_witnessed: 0,
3686 segments_seen: 0,
3687 window: None,
3688 segments_off_target: 0,
3689 replies_without_rtt: 0,
3690 refusals_unattributed: 0,
3691 hosts_found: 0,
3692 answered_on,
3693 answered_unattributed: 0,
3694 first_reply: None,
3695 last_reply: None,
3696 found_at,
3697 capture: None,
3698 };
3699
3700 let longer = ProbeStats::from_parts(parts(
3701 (1..=ATTEMPTS_COUNTED as u64 + 1).collect(),
3702 (1..=BUCKET_BOUNDS_MS.len() as u64 + 2).collect(),
3703 ));
3704 assert_eq!(
3705 longer.answered_on(),
3706 (1..=ATTEMPTS_COUNTED as u64).collect::<Vec<_>>()
3707 );
3708 assert_eq!(
3709 longer.found_at(),
3710 (1..=BUCKET_BOUNDS_MS.len() as u64 + 1).collect::<Vec<_>>()
3711 );
3712
3713 let shorter = ProbeStats::from_parts(parts(vec![7], vec![3, 4]));
3714 assert_eq!(shorter.answered_on().len(), ATTEMPTS_COUNTED);
3715 assert_eq!(shorter.answered_on()[..2], [7, 0]);
3716 assert_eq!(shorter.found_at().len(), BUCKET_BOUNDS_MS.len() + 1);
3717 assert_eq!(shorter.found_at()[..3], [3, 4, 0]);
3718 }
3719
3720 /// A phase without instrumentation reports no counters, not zeros.
3721 #[test]
3722 fn an_uninstrumented_phase_reports_no_probe_stats() {
3723 let report = ScanReport::new(phase(ScanKind::PortScan), []);
3724
3725 assert!(report.phases()[0].probe_stats().is_empty());
3726 assert_eq!(report.probe_stats().count(), 0);
3727 }
3728
3729 #[test]
3730 fn a_stop_reason_knows_whether_the_run_finished() {
3731 assert!(StopReason::AllResponded.is_complete());
3732 assert!(StopReason::AttemptsSpent.is_complete());
3733 assert!(!StopReason::DeadlineExpired.is_complete());
3734 assert!(!StopReason::Aborted.is_complete());
3735 assert!(!StopReason::StreamClosed.is_complete());
3736 assert!(!StopReason::TimedOut.is_complete());
3737 }
3738
3739 /// **A run whose only host a time budget left early is partial.**
3740 #[test]
3741 fn a_run_that_left_a_host_early_is_partial() {
3742 let mut left = phase(ScanKind::PortScan);
3743 left.timed_out.push(ip(1));
3744
3745 assert!(ScanReport::new(left, [Host::new(ip(1))]).is_partial());
3746 }
3747
3748 /// **A port phase whose walk a stop cut short leaves its report partial**, though
3749 /// the unreached targets are on no host.
3750 #[test]
3751 fn a_phase_that_never_reached_part_of_its_plan_is_partial() {
3752 let mut stopped = phase(ScanKind::PortScan);
3753 stopped.stopped = Some(StopReason::Aborted);
3754 stopped.unreached = 6_600;
3755
3756 let report = ScanReport::new(stopped, []);
3757
3758 assert!(report.is_partial());
3759 assert_eq!(report.unreached(), 6_600);
3760 }
3761
3762 /// A phase stopped after reaching everything is not partial.
3763 #[test]
3764 fn a_phase_stopped_with_nothing_left_unreached_is_not_partial() {
3765 let mut stopped = phase(ScanKind::PortScan);
3766 stopped.stopped = Some(StopReason::TimedOut);
3767
3768 assert!(!ScanReport::new(stopped, []).is_partial());
3769 }
3770
3771 /// **A later sitting of the same job replaces an earlier one's unreached count.**
3772 #[test]
3773 fn a_later_sitting_takes_up_what_an_earlier_one_never_reached() {
3774 let mut first = phase(ScanKind::PortScan);
3775 first.stopped = Some(StopReason::Aborted);
3776 first.unreached = 6_600;
3777
3778 let mut finished = ScanReport::new(first.clone(), []);
3779 finished.merge(ScanReport::new(phase(ScanKind::Discovery), []));
3780 finished.merge(ScanReport::new(phase(ScanKind::PortScan), []));
3781 assert_eq!(finished.unreached(), 0);
3782 assert!(!finished.is_partial());
3783
3784 let mut again = phase(ScanKind::PortScan);
3785 again.stopped = Some(StopReason::Aborted);
3786 again.unreached = 1_200;
3787 let mut stopped_twice = ScanReport::new(first, []);
3788 stopped_twice.merge(ScanReport::new(again, []));
3789 assert_eq!(stopped_twice.unreached(), 1_200);
3790 }
3791
3792 /// Across documents an unreached count stands.
3793 #[test]
3794 fn another_documents_scan_does_not_take_up_a_count() {
3795 let mut first = phase(ScanKind::PortScan);
3796 first.unreached = 6_600;
3797 first.origin = Some(PhaseOrigin::new("0.18.0").with_label("monday.json"));
3798 let mut later = phase(ScanKind::PortScan);
3799 later.origin = Some(PhaseOrigin::new("0.18.0").with_label("tuesday.json"));
3800
3801 let mut merged = ScanReport::new(first, []);
3802 merged.merge(ScanReport::new(later, []));
3803
3804 assert_eq!(merged.unreached(), 6_600);
3805 assert!(merged.is_partial());
3806 }
3807
3808 /// A port-scan phase that walked `walked` and left `left` early, begun
3809 /// `at` seconds into the epoch.
3810 fn walked(at: u64, walked: &str, left: &[IpAddr]) -> ScanPhase {
3811 let mut ips: IpSet = walked.parse().expect("a range");
3812 ScanPhase {
3813 started_at: SystemTime::UNIX_EPOCH + Duration::from_secs(at),
3814 targets: TargetScope::from_ip_set(&mut ips, &Exclusions::none()),
3815 timed_out: left.to_vec(),
3816 ..phase(ScanKind::PortScan)
3817 }
3818 }
3819
3820 /// **A host a later sitting finished is not left early**, though the first sitting
3821 /// still names it.
3822 #[test]
3823 fn a_host_a_later_sitting_finished_is_not_left_early() {
3824 let mut report = ScanReport::new(walked(1, "203.0.113.1", &[ip(1)]), []);
3825 report.merge(ScanReport::new(walked(2, "203.0.113.1", &[]), []));
3826 assert!(report.timed_out().is_empty());
3827 assert!(!report.is_partial());
3828
3829 let mut again = ScanReport::new(walked(1, "203.0.113.1", &[ip(1)]), []);
3830 again.merge(ScanReport::new(walked(2, "203.0.113.1", &[ip(1)]), []));
3831 assert_eq!(again.timed_out(), [ip(1)], "left early both times");
3832 assert!(again.is_partial());
3833 }
3834
3835 /// Every shortfall makes a report partial; uncoverable ground does not.
3836 #[test]
3837 fn every_recorded_shortfall_is_partial_and_an_unreachable_address_is_not() {
3838 let refused = {
3839 let mut phase = phase(ScanKind::Discovery);
3840 phase
3841 .refusals
3842 .push(Refusal::new(ScannerKind::Connect, "too large to sweep"));
3843 ScanReport::new(phase, [])
3844 };
3845 assert!(
3846 refused.is_partial(),
3847 "ground declined is ground not covered"
3848 );
3849
3850 let undecided = {
3851 let mut phase = phase(ScanKind::Discovery);
3852 phase.undecided.push(IpRange::V4(
3853 Ipv4Range::new(Ipv4Addr::new(192, 0, 2, 4), Ipv4Addr::new(192, 0, 2, 7))
3854 .expect("a range"),
3855 ));
3856 ScanReport::new(phase, [])
3857 };
3858 assert!(undecided.is_partial(), "an address nobody decided");
3859
3860 let mut unasked = Host::new(ip(1));
3861 unasked.add_port(Port::new(443, Protocol::Tcp, PortState::Unasked));
3862 let cut_short = ScanReport::new(phase(ScanKind::PortScan), [unasked.clone()]);
3863 assert!(cut_short.is_partial(), "a port named and never asked");
3864
3865 let mut no_route = phase(ScanKind::PortScan);
3866 no_route.unroutable.push(ip(1));
3867 let unreachable = ScanReport::new(no_route, [unasked]);
3868 assert!(
3869 !unreachable.is_partial(),
3870 "a port unasked because nothing could reach its address was never coverable"
3871 );
3872 }
3873
3874 #[test]
3875 fn a_clean_report_is_not_partial() {
3876 let report = ScanReport::new(phase(ScanKind::Discovery), []);
3877
3878 assert!(!report.is_partial());
3879 assert_eq!(report.failures().count(), 0);
3880 assert_eq!(report.engine_version(), ENGINE_VERSION);
3881 }
3882
3883 #[test]
3884 fn scope_ranges_cover_both_families() {
3885 let mut ips = ip_set("192.0.2.0/30");
3886 ips.insert_range(IpRange::from_str("fe80::/126").expect("valid range"));
3887
3888 let scope = TargetScope::from_ip_set(&mut ips, &Exclusions::none());
3889
3890 assert_eq!(scope.addresses(), 8);
3891 assert!(matches!(scope.ranges()[0], IpRange::V4(_)));
3892 assert!(matches!(scope.ranges()[1], IpRange::V6(_)));
3893 }
3894
3895 #[test]
3896 fn ipv4_range_scope_reports_its_own_bounds() {
3897 let mut ips = IpSet::new();
3898 ips.push_v4_range(
3899 Ipv4Range::new(Ipv4Addr::new(192, 0, 2, 5), Ipv4Addr::new(192, 0, 2, 9))
3900 .expect("valid range"),
3901 );
3902
3903 let scope = TargetScope::from_ip_set(&mut ips, &Exclusions::none());
3904
3905 assert_eq!(scope.addresses(), 5);
3906 assert_eq!(
3907 scope.ranges()[0].start_addr(),
3908 IpAddr::V4(Ipv4Addr::new(192, 0, 2, 5))
3909 );
3910 }
3911
3912 /// A dual-stack host is one host, counted under both families.
3913 ///
3914 /// The counts do not sum to `hosts_total`.
3915 #[test]
3916 fn family_counts_record_a_dual_stack_host_under_both() {
3917 let mut dual = Host::new(ip(1));
3918 dual.add_ip(IpAddr::from_str("2001:db8::1").unwrap());
3919 let v6_only = Host::new(IpAddr::from_str("2001:db8::2").unwrap());
3920
3921 let report = ScanReport::new(
3922 phase(ScanKind::Discovery),
3923 [dual, Host::new(ip(2)), v6_only],
3924 );
3925
3926 let summary = report.summary();
3927 assert_eq!(summary.hosts_total, 3);
3928 assert_eq!(summary.hosts_by_family.ipv4, 2);
3929 assert_eq!(summary.hosts_by_family.ipv6, 2);
3930 assert_eq!(summary.hosts_by_family.dual_stack, 1);
3931 }
3932}