Skip to main content

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}