Skip to main content

zond_engine/scanner/
session.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//! # A scan while it is running
10//!
11//! The live half of what a scan produces. [`ScanReport`](crate::report) is the
12//! record afterwards; everything here describes the present moment and keeps no
13//! history.
14//!
15//! [`ScanSession::new`] hands out two halves that share one store:
16//!
17//! - [`ScanSession`] is the reading half, for whoever asked for the scan: the
18//!   hosts found so far ([`HostStore`]), the stream saying when that changed
19//!   ([`ScanEvents`]), and the means to stop ([`ScanHandle`]).
20//! - [`ScanContext`] is the writing half, for the strategies. Every scanner is
21//!   built with one, and findings, failures and probe counters enter the scan
22//!   through it.
23//!
24//! ## The writing half
25//!
26//! Every host finding goes through [`ScanContext::write_host`]. It takes the
27//! store's guard, runs the caller's edit under it, drops the guard, and only then
28//! announces the change, so the map is never locked across a channel send. The
29//! map itself stays private, which also keeps a third-party concurrency crate out
30//! of this crate's semver.
31//!
32//! ## What a host is keyed by
33//!
34//! A [`ScopedIp`]: the address it is reported under, plus the interface it was
35//! read on where it needs one. Every IPv4 address and every routable IPv6 one is
36//! the bare address, since a machine at a global address is the same machine
37//! through whichever interface answered.
38//!
39//! An IPv6 link-local is why the key exists. `fe80::1` names a different machine
40//! on every segment, so a host watching two segments can find two neighbours
41//! under one number. Keyed by the bare address, one machine's hardware address,
42//! roles and round trips would be folded into the other's record.
43//!
44//! Three rules follow:
45//!
46//! - **A host takes its link from its key.** [`ScanContext::write_host`] records
47//!   the zone when it creates a host.
48//! - **A key read from the store writes back to the store.**
49//!   [`ScanContext::host_addresses`] hands out keys, and a strategy that reads a
50//!   host and writes a finding back carries the key. A bare address written back
51//!   would create a second entry, splitting one host in two.
52//! - **A bare link-local finds nothing.** [`HostStore::get`] answers `None` for
53//!   one, since it is ambiguous. Consumers get the whole key from
54//!   [`ScanEvent::HostUpdated`], which is meant to be handed straight back to the
55//!   store.
56//!
57//! ## Failures are written down twice
58//!
59//! Once to the event stream for a consumer watching, and once to a log the
60//! report drains at the end, so a caller that only awaits the scan can still
61//! tell an empty network from a strategy that never started.
62
63use dashmap::DashMap;
64use std::collections::{BTreeMap, BTreeSet, HashSet};
65use std::net::IpAddr;
66use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU64, AtomicUsize, Ordering};
67use std::sync::{Arc, Mutex, OnceLock};
68use std::time::{Duration, Instant};
69use tokio::sync::broadcast;
70use tokio::sync::broadcast::error::{RecvError, TryRecvError};
71use tracing::error;
72
73use crate::config::ServiceDetection;
74use crate::detect::compute::DetectionRunRecord;
75use crate::info;
76use crate::journal::settle::{Outcome, Settled, Settlements};
77use crate::model::exclusion::Exclusions;
78use crate::model::host::Host;
79use crate::model::ip::range::IpRange;
80use crate::model::ip::scoped::{ScopedIp, Zone, ZoneMap};
81use crate::model::ip::set::{IpSet, Positions};
82use crate::model::mac::MacAddr;
83use crate::model::port::{PortState, Protocol};
84use crate::report::ScannerKind;
85use crate::report::{Attachment, AttachmentSource, Pass, ProbeStats, Refusal, ScannerFailure};
86use crate::scanner::handle::ScanHandle;
87
88/// What a scan is working on.
89///
90/// After the sweep settles its plan, a tail of different jobs runs over what it
91/// found: identifying services, running detections, reading a stack for an
92/// operating system, tracing a path. The tail often takes several times as long
93/// as the sweep, so progress measured on the plan alone would show a finished
94/// bar for most of a run.
95///
96/// Each stage announces itself as it begins, through [`ScanEvent::StageChanged`],
97/// and [`Progress::stage`] answers which one is current. Some know their size
98/// when they start; the rest report only that they are running.
99#[non_exhaustive]
100#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash)]
101pub enum Stage {
102    /// Establishing which addresses are alive. Where every scan starts.
103    #[default]
104    Discovery,
105    /// Classifying the ports of the hosts that answered.
106    Ports,
107    /// Identifying what is listening behind each open port.
108    Services,
109    /// Running the detection corpus over the services just identified.
110    Detections,
111    /// Asking what each TLS port accepts.
112    Tls,
113    /// Reading a stack, and asking what a host says about itself.
114    Os,
115    /// Tracing the path to each host.
116    Traceroute,
117    /// Characterising the filter in front of each host that answered.
118    Filters,
119    /// Asking each host that answered which IP protocols its stack takes.
120    IpProtocols,
121    /// Reading a link, which ends when the caller says so.
122    Listening,
123    /// The correlating and record keeping left once the probing is over.
124    Finishing,
125}
126
127impl Stage {
128    /// Every stage this build knows, in the order a scan runs them.
129    ///
130    /// As with [`ScanKind::ALL`](crate::report::ScanKind::ALL), the enum is
131    /// `#[non_exhaustive]`, so a front end that maps stages onto a protocol of
132    /// its own uses this to check that it covered them all.
133    pub const ALL: &'static [Self] = &[
134        Self::Discovery,
135        Self::Ports,
136        Self::Services,
137        Self::Detections,
138        Self::Tls,
139        Self::Os,
140        Self::Traceroute,
141        Self::Filters,
142        Self::IpProtocols,
143        Self::Listening,
144        Self::Finishing,
145    ];
146
147    /// Its place in the atomic the tracker keeps.
148    const fn code(self) -> u8 {
149        match self {
150            Stage::Discovery => 0,
151            Stage::Ports => 1,
152            Stage::Services => 2,
153            Stage::Detections => 3,
154            Stage::Tls => 4,
155            Stage::Os => 5,
156            Stage::Traceroute => 6,
157            Stage::Filters => 7,
158            Stage::IpProtocols => 8,
159            Stage::Listening => 9,
160            Stage::Finishing => 10,
161        }
162    }
163
164    /// The stage `code` stands for, and [`Discovery`](Stage::Discovery) for a
165    /// number no stage claims, which is where a scan begins.
166    const fn from_code(code: u8) -> Self {
167        match code {
168            1 => Stage::Ports,
169            2 => Stage::Services,
170            3 => Stage::Detections,
171            4 => Stage::Tls,
172            5 => Stage::Os,
173            6 => Stage::Traceroute,
174            7 => Stage::Filters,
175            8 => Stage::IpProtocols,
176            9 => Stage::Listening,
177            10 => Stage::Finishing,
178            _ => Stage::Discovery,
179        }
180    }
181}
182
183impl std::fmt::Display for Stage {
184    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
185        let name = match self {
186            Stage::Discovery => "discovery",
187            Stage::Ports => "ports",
188            Stage::Services => "services",
189            Stage::Detections => "detections",
190            Stage::Tls => "tls",
191            Stage::Os => "os",
192            Stage::Traceroute => "traceroute",
193            Stage::Filters => "filters",
194            Stage::IpProtocols => "ip protocols",
195            Stage::Listening => "listening",
196            Stage::Finishing => "finishing",
197        };
198
199        f.write_str(name)
200    }
201}
202
203/// Which stage a scan is in and how far through it.
204///
205/// Atomics, because this is written from every probing task and read eight
206/// times a second by whatever is drawing. They are not updated as a group, so a
207/// reader can catch a new stage against a count that has not caught up. That
208/// costs one frame of a progress line, and is why reports are not built from
209/// this.
210#[derive(Debug, Default)]
211pub(crate) struct Stages {
212    current: AtomicU8,
213    done: AtomicU64,
214    total: AtomicU64,
215    /// The stages this scan expects to run, in the order it runs them.
216    planned: Vec<Stage>,
217    /// How many of those are behind it, which only ever grows.
218    reached: AtomicUsize,
219    /// The furthest [`overall`](Self::overall) has reported, as the position
220    /// and total it reported it in.
221    ///
222    /// A stage's size is not always known when it begins: service detection
223    /// learns the size of its second protocol's run only when that run starts,
224    /// so a later reading can be lower than an earlier one. What a caller was
225    /// shown stands until the work catches up with it, so the bar never steps
226    /// back. Behind a lock, since only the readers touch it.
227    shown: Mutex<(u64, u64)>,
228}
229
230impl Stages {
231    fn new(planned: Vec<Stage>) -> Self {
232        Self {
233            planned,
234            ..Self::default()
235        }
236    }
237
238    /// Where the scan stands across every stage it expects to run, as a
239    /// position over a total.
240    ///
241    /// `within` is how far through the current stage it is. The pair comes back
242    /// scaled to whole numbers, so a caller dividing in integers gets cells and a
243    /// percentage that agree.
244    fn overall(&self, within: Option<(u64, u64)>) -> Option<(u64, u64)> {
245        let stages = u64::try_from(self.planned.len()).ok().filter(|n| *n > 0)?;
246        let reached = u64::try_from(self.reached.load(Ordering::Relaxed)).unwrap_or(0);
247
248        // In a stage the scan did not plan, every counted stage is behind it.
249        let reading = match within.filter(|_| self.planned.contains(&self.stage())) {
250            Some((done, total)) => (reached * total + done.min(total), stages * total),
251            None => (reached.min(stages), stages),
252        };
253
254        let mut shown = self.shown.lock().unwrap_or_else(|held| held.into_inner());
255        let behind = u128::from(reading.0) * u128::from(shown.1)
256            < u128::from(shown.0) * u128::from(reading.1);
257        if shown.1 == 0 || !behind {
258            *shown = reading;
259        }
260        Some(*shown)
261    }
262
263    /// Moves to `stage`, answering whether that was a change worth announcing.
264    ///
265    /// Entering the stage already current adds to its total, for service
266    /// detection, which runs once per protocol.
267    fn enter(&self, stage: Stage, total: Option<u64>) -> bool {
268        let total = total.unwrap_or(0);
269
270        // How many planned stages this one comes after, by declaration order,
271        // which is run order. A planned stage with no work is stepped over.
272        let reached = self
273            .planned
274            .iter()
275            .filter(|planned| planned.code() < stage.code())
276            .count();
277        self.reached.fetch_max(reached, Ordering::Relaxed);
278
279        if self.current.swap(stage.code(), Ordering::Relaxed) == stage.code() {
280            self.total.fetch_add(total, Ordering::Relaxed);
281            return false;
282        }
283
284        self.done.store(0, Ordering::Relaxed);
285        self.total.store(total, Ordering::Relaxed);
286        true
287    }
288
289    fn advance(&self) {
290        self.done.fetch_add(1, Ordering::Relaxed);
291    }
292
293    fn stage(&self) -> Stage {
294        Stage::from_code(self.current.load(Ordering::Relaxed))
295    }
296
297    fn done(&self) -> u64 {
298        self.done.load(Ordering::Relaxed)
299    }
300
301    fn total(&self) -> Option<u64> {
302        match self.total.load(Ordering::Relaxed) {
303            0 => None,
304            total => Some(total),
305        }
306    }
307}
308
309/// Lightweight notifications for the status of an ongoing scan.
310#[derive(Debug, Clone)]
311#[non_exhaustive]
312pub enum ScanEvent {
313    /// Something was learned about the host at this address.
314    ///
315    /// The event carries only the address, since a scan can emit thousands.
316    /// Read the current state back from [`ScanSession::hosts`], a single lookup
317    /// that is always up to date.
318    HostUpdated(ScopedIp),
319
320    /// A scanning strategy failed to start or terminated abnormally. The scan
321    /// continues with the strategies that remain, so results may be incomplete.
322    ScannerFailed {
323        /// The strategy that failed.
324        scanner: ScannerKind,
325        /// A human-readable description of the failure.
326        reason: String,
327    },
328
329    /// The scan has moved on to another [`Stage`].
330    ///
331    /// Read [`ScanSession::progress`] for how far through the stage it is; that
332    /// figure moves far faster than stages change.
333    StageChanged {
334        /// What the scan is working on now.
335        stage: Stage,
336    },
337
338    /// The stream ran ahead of this consumer, and `count` events were dropped
339    /// to make room for newer ones.
340    ///
341    /// Delivered in the position the missing events would have had, so a
342    /// consumer knows where its picture went incomplete. [`ScanEvents`] says
343    /// what the gap costs and what to do about it.
344    EventsDropped {
345        /// How many events were dropped.
346        count: u64,
347    },
348}
349
350/// What a scan has found so far, readable while it is still running.
351///
352/// A cheap, cloneable view of one shared store. Every clone reads the same live
353/// data, so a consumer can hand one to a rendering task and keep another.
354///
355/// Reads return owned snapshots: [`get`](Self::get) clones the host, so no
356/// guard is held while scanners keep writing to the same key.
357/// [`read`](Self::read) borrows under the guard for cheap lookups.
358#[derive(Debug, Clone, Default)]
359pub struct HostStore {
360    inner: Arc<DashMap<ScopedIp, Host>>,
361}
362
363impl HostStore {
364    fn new(inner: Arc<DashMap<ScopedIp, Host>>) -> Self {
365        Self { inner }
366    }
367
368    /// The host recorded at `ip`, as it stands right now.
369    ///
370    /// Keyed by the address a scanner wrote it under, which for a host found at
371    /// several addresses is whichever one it was first credited to. To look a
372    /// host up by any of its addresses, search
373    /// [`snapshot`](Self::snapshot) on [`Host::ips`].
374    ///
375    /// An IPv6 link-local needs the interface it was read on: `fe80::1` names a
376    /// different machine on every segment, so a bare one answers `None`. Pass
377    /// the [`ScopedIp`] the event carried. Any other address is a whole key on
378    /// its own, so a plain [`IpAddr`] works.
379    pub fn get(&self, ip: impl Into<ScopedIp>) -> Option<Host> {
380        self.inner
381            .get(&ip.into())
382            .map(|entry| entry.value().clone())
383    }
384
385    /// Reads the host at `ip` without cloning it, if there is one.
386    ///
387    /// Use this inside an event loop. A port scan fires
388    /// [`HostUpdated`](ScanEvent::HostUpdated) once per port, so answering each
389    /// event with [`get`](Self::get) clones a growing port map every time, which
390    /// is quadratic in the size of the scan. Read what the event needs here, and
391    /// clone only a host worth rendering.
392    ///
393    /// `read` runs under the store's guard. It must not touch the store again,
394    /// which deadlocks, and should not block, since a scanner writing to the
395    /// same host waits behind it.
396    pub fn read<R>(&self, ip: impl Into<ScopedIp>, read: impl FnOnce(&Host) -> R) -> Option<R> {
397        self.inner.get(&ip.into()).map(|entry| read(entry.value()))
398    }
399
400    /// Whether anything has been recorded at `ip`.
401    ///
402    /// Cheaper than [`get`](Self::get) when the host itself is not wanted, since
403    /// nothing is cloned.
404    pub fn contains(&self, ip: impl Into<ScopedIp>) -> bool {
405        self.inner.contains_key(&ip.into())
406    }
407
408    /// How many hosts have been recorded.
409    pub fn len(&self) -> usize {
410        self.inner.len()
411    }
412
413    /// Whether nothing has been recorded yet.
414    pub fn is_empty(&self) -> bool {
415        self.inner.is_empty()
416    }
417
418    /// Every host recorded so far, ordered by the address each is keyed under.
419    ///
420    /// A point-in-time copy. Ordered so two reads of the same data compare
421    /// equal, as [`ScanReport`](crate::report::ScanReport) orders its hosts.
422    pub fn snapshot(&self) -> Vec<Host> {
423        let mut hosts: Vec<Host> = self
424            .inner
425            .iter()
426            .map(|entry| entry.value().clone())
427            .collect();
428        hosts.sort_by_cached_key(Host::scoped_ip);
429        hosts
430    }
431
432    /// Puts a host in the store directly, replacing anything at that address.
433    ///
434    /// For tests that need a store already holding a host. A scan records
435    /// findings through [`ScanContext::write_host`], which merges and announces.
436    #[cfg(test)]
437    pub(crate) fn insert(&self, ip: impl Into<ScopedIp>, host: Host) {
438        self.inner.insert(ip.into(), host);
439    }
440}
441
442/// The live event stream of a scan.
443///
444/// Each event says that something changed; the detail is read back from the
445/// [`HostStore`]. See [`ScanEvent`].
446///
447/// The stream holds [`CAPACITY`](Self::CAPACITY) events, and a scan that fills
448/// it overwrites the oldest. A caller who never reads it costs the scan one
449/// fixed buffer, and a slow reader never holds the scan up.
450///
451/// The read after a gap answers [`ScanEvent::EventsDropped`] with how many
452/// events went missing.
453///
454/// A gap loses notices, not findings. A dropped
455/// [`HostUpdated`](ScanEvent::HostUpdated) named a host whose current state is
456/// in the [`HostStore`], so after a gap, re-read the store. A dropped
457/// [`ScannerFailed`](ScanEvent::ScannerFailed) still reaches the
458/// [`ScanReport`](crate::report::ScanReport), which carries every failure.
459#[derive(Debug)]
460pub struct ScanEvents {
461    rx: broadcast::Receiver<ScanEvent>,
462}
463
464impl ScanEvents {
465    /// How many events the stream holds for a consumer that has not caught up.
466    ///
467    /// The buffer is allocated when the scan starts.
468    pub const CAPACITY: usize = 1024;
469
470    /// Waits for the next event. `None` once the scan has ended and every event
471    /// it emitted has been taken.
472    ///
473    /// Falling behind arrives as [`ScanEvent::EventsDropped`], in the position
474    /// the missing events would have had, and the stream carries on with the
475    /// oldest event it still holds.
476    pub async fn recv(&mut self) -> Option<ScanEvent> {
477        match self.rx.recv().await {
478            Ok(event) => Some(event),
479            Err(RecvError::Lagged(count)) => Some(ScanEvent::EventsDropped { count }),
480            Err(RecvError::Closed) => None,
481        }
482    }
483
484    /// The next event if one is already queued, without waiting.
485    ///
486    /// `None` covers both "nothing queued right now" and "the scan is over", so
487    /// it drains a finished scan but cannot detect the end of a running one. Use
488    /// [`recv`](Self::recv) for that. A gap reads the same way it does through
489    /// [`recv`](Self::recv), as [`ScanEvent::EventsDropped`].
490    pub fn try_recv(&mut self) -> Option<ScanEvent> {
491        match self.rx.try_recv() {
492            Ok(event) => Some(event),
493            Err(TryRecvError::Lagged(count)) => Some(ScanEvent::EventsDropped { count }),
494            Err(TryRecvError::Empty | TryRecvError::Closed) => None,
495        }
496    }
497}
498
499/// How far a scan has got through its plan.
500///
501/// A cheap, cloneable view of the counters the strategies settle their targets
502/// against, cheap enough to read on every frame: a read is a pair of atomic
503/// loads and one short lock.
504///
505/// [`settled`](Self::settled) counts what the strategies have finished with, on
506/// every scan, journalled or not. [`planned`](Self::planned) is the size of the
507/// plan, known only where the targets can be numbered: an IPv6 range of a `/64`
508/// or wider cannot be, and a [`listen`](crate::listen) session has no plan.
509/// Where the plan cannot be counted, [`fraction`](Self::fraction) answers
510/// `None`, and a front end can show a running count.
511///
512/// A scan that runs to the end settles every target in its plan and the
513/// fraction reaches 1.0. One stopped early leaves it short.
514///
515/// ```no_run
516/// # fn example(session: &zond_engine::ScanSession) {
517/// let progress = session.progress();
518/// match progress.planned() {
519///     Some(planned) => println!("{} of {planned} targets", progress.settled()),
520///     None => println!("{} targets settled", progress.settled()),
521/// }
522/// # }
523/// ```
524#[derive(Debug, Clone)]
525pub struct Progress {
526    settlements: Arc<Settlements>,
527    planned: Option<u64>,
528    plan_stage: Stage,
529    stages: Arc<Stages>,
530}
531
532impl Progress {
533    fn new(
534        settlements: Arc<Settlements>,
535        planned: Option<u64>,
536        plan_stage: Stage,
537        stages: Arc<Stages>,
538    ) -> Self {
539        Self {
540            settlements,
541            planned,
542            plan_stage,
543            stages,
544        }
545    }
546
547    /// What the scan is working on right now.
548    pub fn stage(&self) -> Stage {
549        self.stages.stage()
550    }
551
552    /// How many units of the current stage are finished.
553    ///
554    /// The unit is the stage's own: ports for [`Stage::Services`], detection
555    /// runs for [`Stage::Detections`], TLS ports for [`Stage::Tls`]. Zero for a
556    /// stage that does not count itself.
557    ///
558    /// A unit is counted once the stage is done with it, whatever the result.
559    /// One passed over because its host had spent its budget or the scan was
560    /// stopped is not, so a stage can end short of its total.
561    pub fn stage_done(&self) -> u64 {
562        self.stages.done()
563    }
564
565    /// How many units the current stage holds, for one that knew its size when
566    /// it began.
567    pub fn stage_total(&self) -> Option<u64> {
568        self.stages.total()
569    }
570
571    /// How many of the plan's targets the scan has finished with, counting
572    /// those an earlier sitting settled and this one resumed past.
573    ///
574    /// A target is settled once no further probing could change its verdict: it
575    /// answered, its retry budget was spent on silence, or its host was found
576    /// down and no probe was owed. A target the scan stopped before reaching is
577    /// not counted.
578    pub fn settled(&self) -> u64 {
579        self.settlements.settled_count()
580    }
581
582    /// How many targets the plan holds, or `None` for a plan whose targets
583    /// cannot all be numbered.
584    ///
585    /// Fixed for the life of the scan. A resumed sitting reports the size of the
586    /// whole job, matching [`settled`](Self::settled).
587    pub const fn planned(&self) -> Option<u64> {
588        self.planned
589    }
590
591    /// How many targets are still to settle, or `None` where the plan cannot be
592    /// counted.
593    pub fn remaining(&self) -> Option<u64> {
594        self.planned
595            .map(|planned| planned.saturating_sub(self.settled()))
596    }
597
598    /// How far through the current stage the scan is, from 0.0 to 1.0.
599    ///
600    /// A stage that counted itself answers for itself. The stage the plan was
601    /// drawn for answers with what the plan has settled, including a resumed
602    /// sitting's earlier work. Any other stage that never learned its size
603    /// answers `None`. That includes a port scan's liveness pass, which settles
604    /// none of the plan's address-and-port pairs.
605    ///
606    /// The plan's figure counts the work of probing, so a target settled without
607    /// a probe counts on neither side: one whose host the liveness pass found
608    /// silent, one the exclusions withhold, one no route leads to, and one on a
609    /// host with no verdict, left for a later sitting. Those settle as fast as
610    /// the walk passes them; counted as work, a range with five live hosts
611    /// behind a thousand ports would read nearly finished within a second.
612    ///
613    /// An empty stage is complete, and the result is capped at 1.0.
614    pub fn fraction(&self) -> Option<f64> {
615        let (done, total) = self.counted()?;
616
617        Some(ratio(done, total))
618    }
619
620    /// Where the scan stands across every stage it expects to run, as a position
621    /// over a total.
622    ///
623    /// One figure for a whole run, so a bar drawn from it fills once. It only
624    /// moves forward: an expected stage with nothing to do is stepped over, so
625    /// the figure can jump, and a stage that grows after it began, as service
626    /// detection does when its second protocol's run starts, holds the figure
627    /// until the work catches up. It reads whole only once the last expected
628    /// stage is behind the scan.
629    ///
630    /// The expected stages are a superset: whether services, detections and TLS
631    /// have anything to do depends on the ports found.
632    ///
633    /// `None` for a session that was never told which stages to expect. See
634    /// [`SessionBuilder::staging`].
635    pub fn overall(&self) -> Option<(u64, u64)> {
636        self.stages.overall(self.counted())
637    }
638
639    /// The two figures [`fraction`](Self::fraction) divides.
640    ///
641    /// For a bar of a fixed number of cells: dividing in integers keeps the cells
642    /// and the percentage agreeing, where one `f64` can round a bar full beside
643    /// a figure that reads 99%.
644    pub fn counted(&self) -> Option<(u64, u64)> {
645        match self.stage_total() {
646            Some(total) => Some((self.stage_done(), total)),
647            None if self.stage() == self.plan_stage => {
648                let planned = self.planned?;
649                let settlements = &self.settlements;
650                let unprobed = settlements.count(Outcome::Skipped { position: 0 })
651                    + settlements.count(Outcome::Withheld { position: 0 })
652                    + settlements.count(Outcome::Unreachable { position: 0 });
653                let undecided = settlements.count(Outcome::Undecided);
654                Some((
655                    self.settled().saturating_sub(unprobed),
656                    planned.saturating_sub(unprobed + undecided),
657                ))
658            }
659            None => None,
660        }
661    }
662}
663
664/// `done` out of `total`, held between 0.0 and 1.0. Nothing to do is done.
665fn ratio(done: u64, total: u64) -> f64 {
666    if total == 0 {
667        return 1.0;
668    }
669
670    (done as f64 / total as f64).min(1.0)
671}
672
673/// A handle to an active network scan: what it has found, what it is doing, and
674/// the means to stop it.
675///
676/// Returned by [`discover`](crate::scanner::discover) and
677/// [`scan`](crate::scanner::scan) alongside the
678/// [`ScanTask`](crate::scanner::ScanTask) that resolves to the final report.
679/// This describes the present moment and keeps no history.
680///
681/// Dropping it stops nothing. Dropping the task stops the scan; see
682/// [`ScanTask`](crate::scanner::ScanTask#dropping-it-stops-the-scan).
683///
684/// ```no_run
685/// # async fn example(mut session: zond_engine::ScanSession) {
686/// use zond_engine::ScanEvent;
687///
688/// while let Some(event) = session.events().recv().await {
689///     if let ScanEvent::HostUpdated(ip) = event
690///         && let Some(host) = session.hosts().get(&ip)
691///     {
692///         println!("{host}");
693///     }
694/// }
695/// # }
696/// ```
697pub struct ScanSession {
698    store: HostStore,
699    events: ScanEvents,
700    handle: ScanHandle,
701    progress: Progress,
702}
703
704impl ScanSession {
705    /// What the scan has found so far.
706    ///
707    /// Once the scan is over this holds the hosts its report lists. While it
708    /// runs it can hold more: a port scan with no liveness pass files a record
709    /// at every address it asks and drops the silent ones when its ports are
710    /// done, so an event naming such an address may find no host. See
711    /// [`ScanPhase::silent`](crate::report::ScanPhase::silent).
712    pub fn hosts(&self) -> &HostStore {
713        &self.store
714    }
715
716    /// The live event stream.
717    ///
718    /// Bounded: a consumer that reads it slowly, or not at all, loses the
719    /// oldest events. See [`ScanEvents`].
720    pub fn events(&mut self) -> &mut ScanEvents {
721        &mut self.events
722    }
723
724    /// The control handle, which is how a scan is stopped early.
725    pub fn handle(&self) -> &ScanHandle {
726        &self.handle
727    }
728
729    /// How far the scan has got through its plan.
730    ///
731    /// Cloneable, so a caller rendering a scan elsewhere can take a copy. See
732    /// [`Progress`].
733    pub fn progress(&self) -> &Progress {
734        &self.progress
735    }
736
737    /// Takes the session apart, for a caller that wants to watch the events from
738    /// one task and read the hosts from another.
739    ///
740    /// [`HostStore`], [`ScanHandle`] and [`Progress`] are cloneable, so this is
741    /// only needed to move the event stream, of which there is one.
742    pub fn into_parts(self) -> (HostStore, ScanEvents, ScanHandle, Progress) {
743        (self.store, self.events, self.handle, self.progress)
744    }
745}
746
747/// Where an instrumented scanner leaves its counters for the final
748/// [`ScanReport`](crate::report::ScanReport).
749///
750/// A scanner reports its audit as its receive loop exits, well before the scan
751/// is over and after the strategy is consumed, so the counters wait here.
752#[derive(Debug, Default)]
753pub(crate) struct ProbeStatsLog {
754    entries: Mutex<Vec<ProbeStats>>,
755}
756
757impl ProbeStatsLog {
758    fn push(&self, stats: ProbeStats) {
759        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
760        entries.push(stats);
761    }
762
763    fn drain(&self) -> Vec<ProbeStats> {
764        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
765        std::mem::take(&mut *entries)
766    }
767
768    fn snapshot(&self) -> Vec<ProbeStats> {
769        self.entries
770            .lock()
771            .unwrap_or_else(|e| e.into_inner())
772            .clone()
773    }
774}
775
776/// Each open port's gathered responses, held from the service phase to the
777/// detection phase for a passive [detection](crate::detect) to read.
778///
779/// The service phase draws a first-contact banner and any probe replies to name
780/// the service. They are kept here, keyed by port, and *taken* by the detection
781/// phase, so a response body is held only across the two adjacent phases.
782///
783/// # A port a sitting inherits
784///
785/// Responses live in memory only and end with their sitting, while the port
786/// comes back to the next sitting settled and is not probed again. Such a port
787/// is [`lost`](Self::lost) here until this sitting identifies it again; a
788/// passive detection run over it before then concludes nothing. A strategy that
789/// identifies ports over the connection that finds them has no second pass, so
790/// it asks the inherited ones in one; see
791/// [`service::detect_inherited`](crate::scanner::service::detect_inherited).
792///
793/// Response bodies stay out of the journal, which records findings. A raw
794/// scan's second pass identifies every open port of a host a resume owes its
795/// passes anyway. Holding back the port's settlement until its detections ran
796/// would make a sitting killed during its passes probe its whole plan again.
797#[derive(Default)]
798pub(crate) struct Responses {
799    inner: DashMap<(ScopedIp, u16, Protocol), Vec<String>>,
800    /// The open ports an earlier sitting identified that this one has not.
801    lost: DashMap<(ScopedIp, u16, Protocol), ()>,
802}
803
804impl Responses {
805    /// Records what the service phase gathered for one port. An empty set is not
806    /// stored. Either way the port is identified in this sitting, and so no
807    /// longer [`lost`](Self::lost).
808    fn record(&self, ip: ScopedIp, number: u16, protocol: Protocol, banners: Vec<String>) {
809        let key = (ip, number, protocol);
810        self.lost.remove(&key);
811        if !banners.is_empty() {
812            self.inner.insert(key, banners);
813        }
814    }
815
816    /// Notes that an earlier sitting drew this port's responses and they
817    /// ended with it.
818    fn inherit(&self, ip: ScopedIp, number: u16, protocol: Protocol) {
819        self.lost.insert((ip, number, protocol), ());
820    }
821
822    /// Whether this port's responses ended with an earlier sitting and this
823    /// one has drawn none since.
824    fn lost(&self, ip: &ScopedIp, number: u16, protocol: Protocol) -> bool {
825        self.lost.contains_key(&(ip.clone(), number, protocol))
826    }
827
828    /// Takes one port's gathered responses, removing them so the memory is freed
829    /// as the detection phase reads it. Empty if the port drew nothing.
830    fn take(&self, ip: &ScopedIp, number: u16, protocol: Protocol) -> Vec<String> {
831        self.inner
832            .remove(&(ip.clone(), number, protocol))
833            .map(|(_, banners)| banners)
834            .unwrap_or_default()
835    }
836}
837
838/// The hosts an earlier sitting finished every pass over, and what this one
839/// still asks. See [`ScanContext::owes_passes`].
840#[derive(Debug, Default)]
841struct Finished {
842    /// Each host as [`ScopedIp`]'s text names it, address and link.
843    hosts: HashSet<String>,
844    /// The addresses this sitting has a target at.
845    asked: IpSet,
846}
847
848/// The tapes of detection runs, captured as the detection phase produces them and
849/// drained into the journal by the checkpoint task. A plain queue: a tape is
850/// appended once and taken in a batch.
851///
852/// Kept only once something will take them, which is whatever holds the scan's
853/// [`ScanProgress`]. Otherwise every port's responses would be held for each
854/// detection that read them until the scan ended.
855#[derive(Debug, Default)]
856pub(crate) struct Tapes {
857    inner: Mutex<Vec<DetectionRunRecord>>,
858    kept: AtomicBool,
859}
860
861impl Tapes {
862    /// Records the tape `run` builds, where tapes are kept, and builds
863    /// nothing where they are not.
864    pub(crate) fn record(&self, run: impl FnOnce() -> DetectionRunRecord) {
865        if !self.kept.load(Ordering::Acquire) {
866            return;
867        }
868        let run = run();
869        self.inner
870            .lock()
871            .unwrap_or_else(std::sync::PoisonError::into_inner)
872            .push(run);
873    }
874
875    /// Keeps every tape recorded from here on, for a reader that will take
876    /// them.
877    fn keep(&self) {
878        self.kept.store(true, Ordering::Release);
879    }
880
881    /// Takes every tape captured since the last call, freeing them as the journal
882    /// writes them down.
883    pub(crate) fn take(&self) -> Vec<DetectionRunRecord> {
884        std::mem::take(
885            &mut self
886                .inner
887                .lock()
888                .unwrap_or_else(std::sync::PoisonError::into_inner),
889        )
890    }
891
892    /// Puts back `runs` a journal took and could not write, ahead of any
893    /// captured since, so the next take hands them over again in the order
894    /// they ran.
895    #[cfg(feature = "journal-format")]
896    fn hand_back(&self, mut runs: Vec<DetectionRunRecord>) {
897        if runs.is_empty() {
898            return;
899        }
900        let mut inner = self
901            .inner
902            .lock()
903            .unwrap_or_else(std::sync::PoisonError::into_inner);
904        runs.append(&mut inner);
905        *inner = runs;
906    }
907}
908
909/// Ground a phase declined to cover, gathered as it is decided.
910///
911/// Kept apart from [`FailureLog`]: a failure is a fault, while a refusal means
912/// the scan as written cannot answer part of what it was asked. See
913/// [`Refusal`].
914///
915/// Kept in insertion order, which is the order the plan works through the
916/// targets.
917#[derive(Debug, Default)]
918pub(crate) struct RefusalLog {
919    entries: Mutex<Vec<Refusal>>,
920}
921
922impl RefusalLog {
923    fn push(&self, refusal: Refusal) {
924        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
925        if !entries.contains(&refusal) {
926            entries.push(refusal);
927        }
928    }
929
930    fn drain(&self) -> Vec<Refusal> {
931        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
932        std::mem::take(&mut *entries)
933    }
934
935    fn snapshot(&self) -> Vec<Refusal> {
936        self.entries
937            .lock()
938            .unwrap_or_else(|e| e.into_inner())
939            .clone()
940    }
941}
942
943/// Addresses this host could not reach, gathered across a phase.
944///
945/// A set, so a target probed several times is named once, and ordered so two
946/// runs of the same scan report them the same way.
947///
948/// Kept apart from [`FailureLog`]: a failed strategy makes the result partial,
949/// while an unreachable address is an ordinary fact, such as a dual-stack name
950/// on a single-stack network, and says nothing about the rest of the scan.
951#[derive(Debug, Default)]
952pub(crate) struct UnroutableLog {
953    entries: Mutex<std::collections::BTreeSet<IpAddr>>,
954}
955
956impl UnroutableLog {
957    fn insert(&self, address: IpAddr) {
958        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
959        entries.insert(address);
960    }
961
962    fn contains(&self, address: IpAddr) -> bool {
963        let entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
964        entries.contains(&address)
965    }
966
967    fn drain(&self) -> Vec<IpAddr> {
968        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
969        std::mem::take(&mut *entries).into_iter().collect()
970    }
971}
972
973/// Addresses whose ICMP errors a phase found rate-limited, gathered across
974/// it.
975///
976/// Like [`TimedOutLog`], it qualifies what the phase covered. A set, so a host
977/// two scanners flag is named once.
978#[derive(Debug, Default)]
979pub(crate) struct RateLimitedLog {
980    entries: Mutex<std::collections::BTreeSet<IpAddr>>,
981}
982
983impl RateLimitedLog {
984    fn insert(&self, address: IpAddr) {
985        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
986        entries.insert(address);
987    }
988
989    fn drain(&self) -> Vec<IpAddr> {
990        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
991        std::mem::take(&mut *entries).into_iter().collect()
992    }
993}
994
995/// The passes a stop skipped or cut short, gathered across a phase.
996///
997/// A set, since several strategies run the same pass: the OS pass is three
998/// separate probes, and a stop that cuts all three cut one pass.
999#[derive(Debug, Default)]
1000pub(crate) struct PassLog {
1001    entries: Mutex<std::collections::BTreeSet<Pass>>,
1002}
1003
1004impl PassLog {
1005    fn insert(&self, pass: Pass) {
1006        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1007        entries.insert(pass);
1008    }
1009
1010    fn drain(&self) -> Vec<Pass> {
1011        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1012        std::mem::take(&mut *entries).into_iter().collect()
1013    }
1014}
1015
1016/// Addresses whose own budget ran out, gathered across a phase.
1017///
1018/// Like [`UnroutableLog`], it records what the phase did not finish covering
1019/// and is not a fault. A set, so a host left early by three passes is named
1020/// once.
1021#[derive(Debug, Default)]
1022pub(crate) struct TimedOutLog {
1023    entries: Mutex<std::collections::BTreeSet<IpAddr>>,
1024}
1025
1026impl TimedOutLog {
1027    fn insert(&self, address: IpAddr) {
1028        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1029        entries.insert(address);
1030    }
1031
1032    fn contains(&self, address: IpAddr) -> bool {
1033        let entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1034        entries.contains(&address)
1035    }
1036
1037    fn drain(&self) -> Vec<IpAddr> {
1038        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1039        std::mem::take(&mut *entries).into_iter().collect()
1040    }
1041}
1042
1043/// Addresses a discovery pass asked as many times as its policy allows and
1044/// heard nothing from.
1045///
1046/// Tells a host found down from one the pass reached no verdict on. A port
1047/// scan's port phase settles only the first as
1048/// [`Skipped`](crate::journal::settle::Outcome::Skipped), and every discovery
1049/// phase names the second in
1050/// [`ScanPhase::undecided`](crate::report::ScanPhase::undecided). A host
1051/// missing from the live set proves neither, since a pass that stopped early,
1052/// had no strategy for a range or was refused it also leaves hosts out.
1053///
1054/// It records positive evidence, so any unrecorded way of failing to ask
1055/// fails safe: the host is asked again on a resume.
1056///
1057/// One range per address until merged, so it is merged whenever the additions
1058/// since the last merge outgrow what that merge left. A pass walking a
1059/// permutation merges little until nearly done, which bounds this at one range
1060/// per silent address.
1061#[derive(Debug, Default)]
1062pub(crate) struct SilenceLog {
1063    entries: Mutex<Silence>,
1064}
1065
1066/// The set behind [`SilenceLog`], and what decides when it is next merged.
1067#[derive(Debug, Default)]
1068struct Silence {
1069    set: IpSet,
1070    /// How many ranges the last merge left; the next merge waits for the
1071    /// additions to outgrow it.
1072    merged: usize,
1073    added: usize,
1074}
1075
1076impl SilenceLog {
1077    /// The fewest additions worth a merge, so a small pass is merged once, on
1078    /// the way out.
1079    const MERGE_AFTER: usize = 4096;
1080
1081    fn insert(&self, address: IpAddr) {
1082        let mut silence = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1083        silence.set.insert(address);
1084        silence.added += 1;
1085        if silence.added >= Self::MERGE_AFTER.max(silence.merged) {
1086            silence.set.canonicalize();
1087            silence.merged = silence.set.v4().len() + silence.set.v6().len();
1088            silence.added = 0;
1089        }
1090    }
1091
1092    fn drain(&self) -> IpSet {
1093        let mut silence = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1094        let mut taken = std::mem::take(&mut *silence).set;
1095        taken.canonicalize();
1096        taken
1097    }
1098}
1099
1100/// Addresses a raw phase reached by TCP connect, gathered across it.
1101///
1102/// Held as ranges, because it is filled with whole groups a strategy was
1103/// handed, and a tunnel's own subnet can be a `/23`. Merged on the way out, so
1104/// a range two strategies both reported is named once.
1105#[derive(Debug, Default)]
1106pub(crate) struct ConnectLog {
1107    entries: Mutex<IpSet>,
1108}
1109
1110impl ConnectLog {
1111    fn extend(&self, targets: &IpSet) {
1112        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1113        for range in targets.v4() {
1114            entries.push_v4_range(*range);
1115        }
1116        for range in targets.v6() {
1117            entries.push_v6_range(*range);
1118        }
1119    }
1120
1121    fn drain(&self, unreached: &[IpAddr]) -> Vec<IpRange> {
1122        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1123        let mut taken = std::mem::take(&mut *entries);
1124        taken.canonicalize();
1125        if !unreached.is_empty() {
1126            let mut unreached_set = IpSet::new();
1127            for address in unreached {
1128                unreached_set.insert(*address);
1129            }
1130            unreached_set.canonicalize();
1131            taken.subtract(&unreached_set);
1132        }
1133        let v4 = taken.v4().iter().copied().map(IpRange::V4);
1134        let v6 = taken.v6().iter().copied().map(IpRange::V6);
1135        v4.chain(v6).collect()
1136    }
1137}
1138
1139/// When each host's wall-clock budget started, for a scan given one.
1140///
1141/// A host's clock starts on the first probe aimed at it, since a shuffled scan
1142/// of a wide range may reach an address late, and a budget counted from the
1143/// start of the run would leave the last address no time.
1144///
1145/// `budget` is `None` for a scan that set no per-host bound, the usual case;
1146/// the map is then never written to.
1147///
1148/// ## What it costs
1149///
1150/// One instant per address the scan probes, a fraction of the [`Host`] the
1151/// store already keeps for that address.
1152#[derive(Debug, Default)]
1153pub(crate) struct HostClocks {
1154    budget: Option<Duration>,
1155    started: DashMap<IpAddr, Instant>,
1156}
1157
1158/// The gaps the scan keeps between the probes it sends: between two aimed at
1159/// one host, and between any two at all.
1160///
1161/// Like [`HostClocks`], it lives on the context every pass holds, because a
1162/// bound on the scan's traffic belongs to the scan: with a copy per strategy,
1163/// two passes probing at once would each allow the whole gap.
1164///
1165/// Both gaps are `None` for a scan that set neither, the usual case; nothing is
1166/// then locked or stored.
1167///
1168/// ## Claiming
1169///
1170/// [`claim`](Self::claim) decides whether a probe may leave and records that it
1171/// did in one operation, under the locks both gaps are kept behind. A separate
1172/// check and record would let two concurrent senders (two port scanners on one
1173/// host, or a connect scan's probe tasks) both find the slot free and both send.
1174///
1175/// The clock is read after the locks are taken, so an instant recorded here is
1176/// never earlier than one recorded before it.
1177///
1178/// The gap is kept between the moments probes are released to the kernel. A
1179/// probe released late can land nearer the next one than the gap by the send's
1180/// own latency, which this gate cannot see.
1181///
1182/// ## Refunds
1183///
1184/// A probe the kernel refused reached nobody and must not spend a slot, as
1185/// `RawProbeScan::record_send` keeps it out of the congestion window.
1186/// [`refund`](Self::refund) puts back the slot a claim took, unless a later
1187/// claim has been recorded over it; then the only cost is a gap longer than
1188/// asked for.
1189///
1190/// ## What it costs
1191///
1192/// One instant pair per address the scan probes, as for [`HostClocks`]. The two
1193/// are separate types because a budget starts a clock once per target, while a
1194/// gap moves one on every probe.
1195#[derive(Debug, Default)]
1196pub(crate) struct ProbeSpacing {
1197    per_host: Option<Duration>,
1198    scan_wide: Option<Duration>,
1199    last_at_host: DashMap<IpAddr, Slot>,
1200    last_anywhere: Mutex<Option<Slot>>,
1201}
1202
1203/// The last slot taken on one of [`ProbeSpacing`]'s clocks, and the one before
1204/// it, which is what a refund restores.
1205#[derive(Debug, Clone, Copy)]
1206struct Slot {
1207    at: Instant,
1208    before: Option<Instant>,
1209}
1210
1211impl Slot {
1212    /// The slot taken at `at`, over whatever `previous` held.
1213    fn after(previous: Option<Slot>, at: Instant) -> Self {
1214        Self {
1215            at,
1216            before: previous.map(|slot| slot.at),
1217        }
1218    }
1219
1220    /// When a probe may next leave under `gap`, or `None` if it may now.
1221    fn ready_at(slot: Option<Slot>, gap: Option<Duration>, now: Instant) -> Option<Instant> {
1222        let ready = crate::scanner::pacing::timer::later(slot?.at, gap?);
1223        (ready > now).then_some(ready)
1224    }
1225
1226    /// What is left on the clock once the slot taken at `at` is given back:
1227    /// the one before it, or nothing. `None` for a slot recorded over since,
1228    /// which is kept.
1229    fn refunded(self, at: Instant) -> Option<Option<Slot>> {
1230        (self.at == at).then(|| {
1231            self.before.map(|before| Slot {
1232                at: before,
1233                before: None,
1234            })
1235        })
1236    }
1237}
1238
1239/// A slot [`ScanContext::claim_probe`] or [`ScanContext::claim_group_probe`]
1240/// handed out: the address a probe may now be sent to, and the instant it was
1241/// allowed to leave.
1242///
1243/// A caller whose send the kernel refuses gives the slot back with
1244/// [`ScanContext::refund_probe`]. Dropping it spends the slot.
1245#[must_use = "a claim is a slot the scan has spent; a refused send gives it back with refund_probe"]
1246#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1247pub struct ProbeClaim {
1248    address: IpAddr,
1249    at: Instant,
1250    /// Whether the slot was taken on `address`'s own clock as well as the
1251    /// scan's. False for a frame sent to a group, which has no host clock.
1252    at_host: bool,
1253}
1254
1255impl ProbeClaim {
1256    /// The address the claimed probe is aimed at: one host's, or for a
1257    /// [group probe](ScanContext::claim_group_probe) the group's.
1258    pub fn address(&self) -> IpAddr {
1259        self.address
1260    }
1261}
1262
1263/// The scan's own gate, as the connections and datagrams it opens through
1264/// [`Egress`](crate::transport::dial::Egress) ask it; see
1265/// [`dial::pacing`](crate::transport::dial::pacing).
1266impl crate::transport::dial::pacing::Pacer for ScanContext {
1267    fn claim(&self, peer: IpAddr) -> Result<crate::transport::dial::pacing::Claim, Instant> {
1268        self.claim_probe(peer)
1269            .map(|claim| crate::transport::dial::pacing::Claim {
1270                address: claim.address,
1271                at: claim.at,
1272            })
1273    }
1274
1275    fn refund(&self, claim: crate::transport::dial::pacing::Claim) {
1276        // A connection or datagram is aimed at one host, so its slot was taken
1277        // on that host's clock too.
1278        self.refund_probe(ProbeClaim {
1279            address: claim.address,
1280            at: claim.at,
1281            at_host: true,
1282        });
1283    }
1284
1285    fn host_expired(&self, peer: IpAddr) -> bool {
1286        ScanContext::host_expired(self, peer)
1287    }
1288
1289    fn should_stop(&self) -> bool {
1290        self.handle.should_stop()
1291    }
1292
1293    fn stopping(&self) -> std::pin::Pin<Box<dyn std::future::Future<Output = ()> + Send + '_>> {
1294        Box::pin(self.handle.stopping())
1295    }
1296}
1297
1298impl ProbeSpacing {
1299    /// Whether this scan keeps any gap at all. A scan that keeps none never
1300    /// locks or stores anything here.
1301    fn is_spaced(&self) -> bool {
1302        self.per_host.is_some() || self.scan_wide.is_some()
1303    }
1304
1305    /// The longer of the two gaps, for a caller sizing a deadline: every probe
1306    /// at one host waits out the first, and every probe at all the second.
1307    fn longest(&self) -> Option<Duration> {
1308        self.per_host.max(self.scan_wide)
1309    }
1310
1311    /// When a probe to `address` may next leave, or `None` if it may now.
1312    ///
1313    /// Reads only, so a concurrent pass may take the slot first. Use it to
1314    /// choose which probe to try; a claim decides.
1315    fn ready_at(&self, address: IpAddr, now: Instant) -> Option<Instant> {
1316        if !self.is_spaced() {
1317            return None;
1318        }
1319        let anywhere = self.scan_wide.and_then(|gap| {
1320            let slot = *self
1321                .last_anywhere
1322                .lock()
1323                .unwrap_or_else(|held| held.into_inner());
1324            Slot::ready_at(slot, Some(gap), now)
1325        });
1326        let at_host = self.per_host.and_then(|gap| {
1327            let slot = self.last_at_host.get(&address).map(|slot| *slot);
1328            Slot::ready_at(slot, Some(gap), now)
1329        });
1330        anywhere.max(at_host)
1331    }
1332
1333    /// When a frame sent to a group may next leave, or `None` if it may now.
1334    /// Only the scan-wide gap applies.
1335    fn group_ready_at(&self, now: Instant) -> Option<Instant> {
1336        let gap = self.scan_wide?;
1337        let slot = *self
1338            .last_anywhere
1339            .lock()
1340            .unwrap_or_else(|held| held.into_inner());
1341        Slot::ready_at(slot, Some(gap), now)
1342    }
1343
1344    /// Takes the next slot for a probe to `address` if both gaps allow one
1345    /// now, or says when they will.
1346    fn claim(&self, address: IpAddr) -> Result<ProbeClaim, Instant> {
1347        self.claim_with(address, Instant::now)
1348    }
1349
1350    /// [`claim`](Self::claim), reading the time from `clock` once the locks
1351    /// are held.
1352    ///
1353    /// The scan-wide lock is always taken before the host's, here and in
1354    /// [`refund`](Self::refund), so two claims cannot deadlock.
1355    pub(crate) fn claim_with(
1356        &self,
1357        address: IpAddr,
1358        clock: impl FnOnce() -> Instant,
1359    ) -> Result<ProbeClaim, Instant> {
1360        self.claim_on(address, true, clock)
1361    }
1362
1363    /// Takes the next slot for a frame sent to `group` if the scan-wide gap
1364    /// allows one now, or says when it will; no host's clock is read or moved.
1365    fn claim_group(&self, group: IpAddr) -> Result<ProbeClaim, Instant> {
1366        self.claim_group_with(group, Instant::now)
1367    }
1368
1369    /// [`claim_group`](Self::claim_group), reading the time from `clock` once
1370    /// the lock is held.
1371    pub(crate) fn claim_group_with(
1372        &self,
1373        group: IpAddr,
1374        clock: impl FnOnce() -> Instant,
1375    ) -> Result<ProbeClaim, Instant> {
1376        self.claim_on(group, false, clock)
1377    }
1378
1379    /// A claim on the scan-wide clock, and on `address`'s own where `at_host`.
1380    fn claim_on(
1381        &self,
1382        address: IpAddr,
1383        at_host: bool,
1384        clock: impl FnOnce() -> Instant,
1385    ) -> Result<ProbeClaim, Instant> {
1386        if !self.is_spaced() {
1387            return Ok(ProbeClaim {
1388                address,
1389                at: clock(),
1390                at_host,
1391            });
1392        }
1393
1394        let mut anywhere = self.scan_wide.map(|_| {
1395            self.last_anywhere
1396                .lock()
1397                .unwrap_or_else(|held| held.into_inner())
1398        });
1399        let host_clock = self
1400            .per_host
1401            .filter(|_| at_host)
1402            .map(|_| self.last_at_host.entry(address));
1403        let now = clock();
1404
1405        let wait_anywhere = anywhere
1406            .as_deref()
1407            .and_then(|slot| Slot::ready_at(*slot, self.scan_wide, now));
1408        let wait_at_host = host_clock.as_ref().and_then(|entry| match entry {
1409            dashmap::Entry::Occupied(slot) => Slot::ready_at(Some(*slot.get()), self.per_host, now),
1410            dashmap::Entry::Vacant(_) => None,
1411        });
1412        if let Some(ready) = wait_anywhere.max(wait_at_host) {
1413            return Err(ready);
1414        }
1415
1416        if let Some(slot) = anywhere.as_deref_mut() {
1417            *slot = Some(Slot::after(*slot, now));
1418        }
1419        if let Some(entry) = host_clock {
1420            match entry {
1421                dashmap::Entry::Occupied(mut slot) => {
1422                    let previous = *slot.get();
1423                    slot.insert(Slot::after(Some(previous), now));
1424                }
1425                dashmap::Entry::Vacant(slot) => {
1426                    slot.insert(Slot::after(None, now));
1427                }
1428            }
1429        }
1430        Ok(ProbeClaim {
1431            address,
1432            at: now,
1433            at_host,
1434        })
1435    }
1436
1437    /// Gives back the slot `claim` took, on either clock where nothing has
1438    /// been recorded over it since.
1439    fn refund(&self, claim: ProbeClaim) {
1440        if !self.is_spaced() {
1441            return;
1442        }
1443        if self.scan_wide.is_some() {
1444            let mut anywhere = self
1445                .last_anywhere
1446                .lock()
1447                .unwrap_or_else(|held| held.into_inner());
1448            if let Some(restored) = anywhere.and_then(|slot| slot.refunded(claim.at)) {
1449                *anywhere = restored;
1450            }
1451        }
1452        if self.per_host.is_some()
1453            && claim.at_host
1454            && let dashmap::Entry::Occupied(mut slot) = self.last_at_host.entry(claim.address)
1455        {
1456            match slot.get().refunded(claim.at) {
1457                Some(Some(restored)) => {
1458                    slot.insert(restored);
1459                }
1460                Some(None) => {
1461                    slot.remove();
1462                }
1463                None => {}
1464            }
1465        }
1466    }
1467}
1468
1469impl HostClocks {
1470    /// Whether `address` has used up its budget, starting its clock if this is
1471    /// the first time it has been asked about.
1472    ///
1473    /// Always false for a scan with no budget, without touching the map.
1474    fn expired(&self, address: IpAddr) -> bool {
1475        let Some(budget) = self.budget else {
1476            return false;
1477        };
1478        // Read first, so only a host's first probe takes the shard's write
1479        // lock; this is on the send path once per target.
1480        if let Some(started) = self.started.get(&address) {
1481            return started.elapsed() >= budget;
1482        }
1483        let started = *self.started.entry(address).or_insert_with(Instant::now);
1484        started.elapsed() >= budget
1485    }
1486}
1487
1488/// The links a phase swept, gathered as its strategies run.
1489///
1490/// A sweep of a local segment reaches every host on the link, beyond the
1491/// addresses it was handed: every IPv6 neighbour must answer an all-nodes
1492/// solicitation. No address range expresses that coverage, so the link is
1493/// named by its interface.
1494///
1495/// Keyed by interface name, so a link swept by two strategies is recorded once.
1496#[derive(Debug, Default)]
1497pub(crate) struct SweptLinks {
1498    entries: Mutex<std::collections::BTreeMap<String, Zone>>,
1499}
1500
1501impl SweptLinks {
1502    fn insert(&self, zone: Zone) {
1503        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1504        entries.insert(zone.name().to_owned(), zone);
1505    }
1506
1507    fn drain(&self) -> Vec<Zone> {
1508        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1509        std::mem::take(&mut *entries).into_values().collect()
1510    }
1511}
1512
1513/// The switch ports a phase found itself plugged into, gathered as its
1514/// strategies run.
1515///
1516/// Keyed by the link and the protocol the announcement came from, so a switch
1517/// re-announcing itself every thirty seconds is recorded once. The latest
1518/// announcement wins, so a moved cable is not reported as two attachments.
1519///
1520/// A link answering on both LLDP and CDP keeps both, since the protocols a
1521/// network speaks are a fact about it and the two carry different fields.
1522#[derive(Debug, Default)]
1523pub(crate) struct Attachments {
1524    entries: Mutex<std::collections::BTreeMap<(String, AttachmentSource), Attachment>>,
1525}
1526
1527impl Attachments {
1528    fn insert(&self, attachment: Attachment) {
1529        let key = (attachment.link().name().to_owned(), attachment.source());
1530        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1531        entries.insert(key, attachment);
1532    }
1533
1534    fn drain(&self) -> Vec<Attachment> {
1535        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1536        std::mem::take(&mut *entries).into_values().collect()
1537    }
1538}
1539
1540/// Every host in `store`, cloned, ordered by the address each is keyed under.
1541///
1542/// Ordered because a journal compaction writes these to disk, and the same
1543/// findings should produce the same file.
1544///
1545/// A free function because both `ScanContext` and `ScanProgress` need it.
1546fn snapshot_of(store: &DashMap<ScopedIp, Host>) -> Vec<Host> {
1547    let mut hosts: Vec<Host> = store.iter().map(|entry| entry.value().clone()).collect();
1548    hosts.sort_by_cached_key(Host::scoped_ip);
1549    hosts
1550}
1551
1552/// The hosts `changed` has marked since it was last drained, with their current
1553/// state, dropping any the store no longer holds.
1554fn changed_since(store: &DashMap<ScopedIp, Host>, changed: &ChangedHosts) -> Vec<Host> {
1555    changed
1556        .drain()
1557        .into_keys()
1558        .filter_map(|key| store.get(&key).map(|host| host.clone()))
1559        .collect()
1560}
1561
1562/// [`changed_since`], each host carrying only the ports marked on it where
1563/// those were kept.
1564///
1565/// What a journal writes, costing what changed: a pass that identifies one
1566/// service on a host scanned on every port copies the host's own fields and
1567/// one port, under the lock every strategy writing that host waits on. See
1568/// [`Host::with_only_ports`].
1569#[cfg(feature = "journal-format")]
1570fn changes_since(store: &DashMap<ScopedIp, Host>, changed: &ChangedHosts) -> Vec<Host> {
1571    changed
1572        .drain()
1573        .into_iter()
1574        .filter_map(|(key, pending)| {
1575            let host = store.get(&key)?;
1576            Some(match pending {
1577                Pending::Ports(ports) => host.with_only_ports(&ports),
1578                Pending::Whole => host.clone(),
1579            })
1580        })
1581        .collect()
1582}
1583
1584/// Whether `host` is a record a port phase standing in for a liveness pass may
1585/// yet forget: one nothing has answered at. The phase decides these at its end,
1586/// and only these; see [`ScanContext::await_verdicts`].
1587#[cfg(feature = "journal-format")]
1588fn awaits_verdict(host: &Host) -> bool {
1589    host.status() == crate::model::host::HostStatus::Unknown
1590}
1591
1592/// What a port phase standing in for a liveness pass has concluded so far of
1593/// the records nothing has answered at; see
1594/// [`ScanProgress::verdicts_so_far`].
1595#[cfg(feature = "journal-format")]
1596#[derive(Debug, Clone, Default)]
1597pub(crate) struct SoFar {
1598    /// The addresses heard nothing from on every target, each settled.
1599    pub(crate) silent: Vec<IpRange>,
1600    /// The addresses of every other record nothing has answered at.
1601    pub(crate) awaiting: IpSet,
1602    /// How many targets the silent addresses were asked.
1603    pub(crate) unheard_probes: u64,
1604}
1605
1606/// `set`'s ranges, IPv4 first.
1607#[cfg(feature = "journal-format")]
1608pub(crate) fn ranges_of(set: &IpSet) -> Vec<IpRange> {
1609    let v4 = set.v4().iter().copied().map(IpRange::V4);
1610    let v6 = set.v6().iter().copied().map(IpRange::V6);
1611    v4.chain(v6).collect()
1612}
1613
1614/// What a journal needs from a running scan, and nothing more.
1615///
1616/// See [`ScanContext::progress`] for why a journal gets this and not a context.
1617#[derive(Debug, Clone)]
1618pub struct ScanProgress {
1619    store: Arc<DashMap<ScopedIp, Host>>,
1620    changed: Arc<ChangedHosts>,
1621    settlements: Arc<Settlements>,
1622    failures: Arc<FailureLog>,
1623    tapes: Arc<Tapes>,
1624    /// Whether a port phase standing in for a liveness pass has yet to reach
1625    /// its verdicts, which only a journal's writer asks.
1626    #[cfg(feature = "journal-format")]
1627    verdicts_pending: Arc<AtomicBool>,
1628    #[cfg(feature = "journal-format")]
1629    sitting: Arc<Sitting>,
1630    /// How the port phase numbers its targets, which says what an address
1631    /// is owed; see [`verdicts_so_far`](Self::verdicts_so_far).
1632    #[cfg(feature = "journal-format")]
1633    numbering: Arc<OnceLock<crate::model::target::TargetIndex>>,
1634}
1635
1636impl ScanProgress {
1637    /// How far the scan has got, and what became of what it did not settle.
1638    pub fn settlements(&self) -> &Settlements {
1639        &self.settlements
1640    }
1641
1642    /// Takes the hosts whose findings have changed since this was last called.
1643    pub fn take_changed_hosts(&self) -> Vec<Host> {
1644        changed_since(&self.store, &self.changed)
1645    }
1646
1647    /// Takes the detection tapes captured since this was last called, for the
1648    /// journal to write down.
1649    pub fn take_tapes(&self) -> Vec<DetectionRunRecord> {
1650        self.tapes.take()
1651    }
1652
1653    /// Every host found so far, cloned, ordered by the address each is keyed
1654    /// under.
1655    ///
1656    /// Ordered because a journal compaction writes these to disk, and the same
1657    /// findings should produce the same file.
1658    pub fn hosts_snapshot(&self) -> Vec<Host> {
1659        snapshot_of(&self.store)
1660    }
1661
1662    /// How many hosts have been found so far.
1663    pub fn host_count(&self) -> usize {
1664        self.store.len()
1665    }
1666
1667    /// The key of every host found so far.
1668    #[cfg(feature = "journal-format")]
1669    pub(crate) fn host_keys(&self) -> Vec<ScopedIp> {
1670        self.store.iter().map(|entry| entry.key().clone()).collect()
1671    }
1672
1673    /// Takes the hosts whose findings have changed since this was last
1674    /// called, for a journal to append as a scan runs.
1675    ///
1676    /// A record a port phase standing in for a liveness pass has yet to decide
1677    /// is taken too. Its targets are settled as they are asked, so holding it
1678    /// back until the verdict, which a killed sitting never reaches, would
1679    /// leave them settled with nothing on file. The job's report leaves it out
1680    /// while the phase names it undecided, and the next sitting restores and
1681    /// decides it; see [`verdicts_so_far`](Self::verdicts_so_far).
1682    ///
1683    /// Each host carries its own fields and only the ports marked on it since
1684    /// it was last taken; see `changes_since`.
1685    #[cfg(feature = "journal-format")]
1686    pub(crate) fn take_changed_findings(&self) -> Vec<Host> {
1687        changes_since(&self.store, &self.changed)
1688    }
1689
1690    /// This sitting's phases as they stand: those closed, and the open one
1691    /// so far, as `so_far` has it. See [`Sitting`].
1692    #[cfg(feature = "journal-format")]
1693    pub(crate) fn standing_phases(&self, so_far: &SoFar) -> Vec<crate::report::ScanPhase> {
1694        self.sitting.standing(self.failures.snapshot(), so_far)
1695    }
1696
1697    /// What a port phase standing in for a liveness pass has concluded so
1698    /// far of the records nothing has answered at, read against `cursor`.
1699    /// Empty for any other phase.
1700    ///
1701    /// For a checkpoint to write into the phase as it stands, so a sitting
1702    /// killed before its end still accounts for each record it wrote down.
1703    ///
1704    /// **Silent**, and counted: an address asked on every target the plan
1705    /// numbers there, each settled in `cursor`, and heard from on none. A
1706    /// resume asks nothing more of it and restores no record, so its probes are
1707    /// this sitting's to count. An address filed unreachable or withheld by the
1708    /// exclusions had its targets settled unasked and is not silent; nor is one
1709    /// whose own budget ran out, which left a target unasked.
1710    ///
1711    /// **Awaiting**: every other address of such a record, which the phase has
1712    /// not finished asking or decided. The phase names it undecided, so the
1713    /// job's report makes no host of it, and the next sitting restores and
1714    /// decides it, counting the probes sent to it then.
1715    #[cfg(feature = "journal-format")]
1716    pub(crate) fn verdicts_so_far(&self, cursor: &crate::journal::cursor::Checkpoint) -> SoFar {
1717        if !self.verdicts_pending.load(Ordering::Acquire) {
1718            return SoFar::default();
1719        }
1720        let Some(numbering) = self.numbering.get() else {
1721            return SoFar::default();
1722        };
1723        let mut silent = IpSet::new();
1724        let mut awaiting = IpSet::new();
1725        let mut unheard_probes = 0u64;
1726        for entry in self.store.iter() {
1727            let host = entry.value();
1728            if !awaits_verdict(host) {
1729                continue;
1730            }
1731            let address = entry.key().addr();
1732            let mut owed = 0u64;
1733            let mut settled = true;
1734            for run in numbering.runs_at(address) {
1735                owed += run.end - run.start;
1736                settled &= run.clone().all(|position| cursor.is_settled(position));
1737            }
1738            let asked = host
1739                .ports()
1740                .filter(|port| port.state() != PortState::Unasked)
1741                .count() as u64;
1742            if owed > 0 && settled && asked == owed {
1743                silent.insert(address);
1744                unheard_probes += asked;
1745            } else {
1746                awaiting.insert(address);
1747            }
1748        }
1749        silent.canonicalize();
1750        awaiting.canonicalize();
1751        SoFar {
1752            silent: ranges_of(&silent),
1753            awaiting,
1754            unheard_probes,
1755        }
1756    }
1757
1758    /// Marks `hosts` changed again, for a journal whose write of them failed.
1759    ///
1760    /// Taking the changed hosts clears their marks, and the next write takes
1761    /// only what changed since, so without this a failed write would lose
1762    /// them while its cursor settled their targets. Handed back, they go out
1763    /// with the next write that succeeds, in their state as of then.
1764    #[cfg(feature = "journal-format")]
1765    pub(crate) fn hand_back(&self, hosts: &[Host]) {
1766        for host in hosts {
1767            self.changed.put_back(host);
1768        }
1769    }
1770
1771    /// Puts back detection tapes a journal took and could not write, for the
1772    /// next write to take again.
1773    ///
1774    /// The counterpart of [`hand_back`](Self::hand_back) for tapes. A tape is
1775    /// captured only once, so one lost with a failed write could never be
1776    /// replayed.
1777    #[cfg(feature = "journal-format")]
1778    pub(crate) fn hand_back_tapes(&self, runs: Vec<DetectionRunRecord>) {
1779        self.tapes.hand_back(runs);
1780    }
1781
1782    /// Every host found so far, ordered by the address each is keyed under,
1783    /// including records a port phase has yet to decide. What a journal
1784    /// compacts its findings to; see
1785    /// [`take_changed_findings`](Self::take_changed_findings).
1786    #[cfg(feature = "journal-format")]
1787    pub(crate) fn findings_snapshot(&self) -> Vec<Host> {
1788        self.hosts_snapshot()
1789    }
1790
1791    /// Files a failure to the report, without an event; see
1792    /// [`ScanContext::progress`].
1793    ///
1794    /// Logged under the failing strategy's name, as
1795    /// [`ScanContext::record_failure`] logs it.
1796    pub fn record_failure(&self, scanner: ScannerKind, reason: String) {
1797        error!(
1798            "{} failed: {reason}",
1799            crate::record::wire::scanner_kind_name(scanner)
1800        );
1801        self.failures.push(ScannerFailure::new(scanner, reason));
1802    }
1803}
1804
1805/// The hosts whose findings a journal has yet to record, and of each, which
1806/// ports.
1807///
1808/// Ports are kept only once something will take them, which is whatever
1809/// holds the scan's [`ScanProgress`], as with [`Tapes`]. Before that, and in a
1810/// scan nobody journals, a host is marked whole.
1811#[derive(Debug, Default)]
1812pub(crate) struct ChangedHosts {
1813    entries: Mutex<BTreeMap<ScopedIp, Pending>>,
1814    ports_kept: AtomicBool,
1815}
1816
1817/// What a journal has yet to record of one host.
1818#[derive(Debug)]
1819enum Pending {
1820    /// Its own fields and these ports.
1821    Ports(BTreeSet<(u16, Protocol)>),
1822    /// Everything it holds, where the changed ports were not kept.
1823    Whole,
1824}
1825
1826impl ChangedHosts {
1827    /// Marks the host at `ip` changed, on the ports `touched` names where
1828    /// they are known and on all of them where they are not.
1829    fn insert(&self, ip: ScopedIp, touched: Option<BTreeSet<(u16, Protocol)>>) {
1830        let touched = touched.filter(|_| self.keeps_ports());
1831        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1832        match (entries.entry(ip), touched) {
1833            (std::collections::btree_map::Entry::Vacant(slot), touched) => {
1834                slot.insert(touched.map_or(Pending::Whole, Pending::Ports));
1835            }
1836            (std::collections::btree_map::Entry::Occupied(mut slot), Some(touched)) => {
1837                if let Pending::Ports(ports) = slot.get_mut() {
1838                    ports.extend(touched);
1839                }
1840            }
1841            (std::collections::btree_map::Entry::Occupied(mut slot), None) => {
1842                slot.insert(Pending::Whole);
1843            }
1844        }
1845    }
1846
1847    /// Marks `host`, a record a journal took and did not write, changed on
1848    /// every port it carries.
1849    #[cfg(feature = "journal-format")]
1850    fn put_back(&self, host: &Host) {
1851        let ports = host
1852            .ports()
1853            .map(|port| (port.number(), port.protocol()))
1854            .collect();
1855        self.insert(host.scoped_ip(), Some(ports));
1856    }
1857
1858    /// Keeps which ports change from here on, for a reader that will take
1859    /// them.
1860    fn keep_ports(&self) {
1861        self.ports_kept.store(true, Ordering::Release);
1862    }
1863
1864    fn keeps_ports(&self) -> bool {
1865        self.ports_kept.load(Ordering::Acquire)
1866    }
1867
1868    fn drain(&self) -> BTreeMap<ScopedIp, Pending> {
1869        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1870        std::mem::take(&mut *entries)
1871    }
1872}
1873
1874/// Where strategy failures accumulate for the final
1875/// [`ScanReport`](crate::report::ScanReport).
1876///
1877/// [`ScanEvent::ScannerFailed`] tells a live consumer, and this log keeps the
1878/// same failures for the report, so a caller that only awaits the scan can
1879/// still tell an empty network from a scanner that never started.
1880///
1881/// A plain [`Mutex`]: failures are rare, and the lock is never held across an
1882/// await.
1883#[derive(Debug, Default)]
1884pub(crate) struct FailureLog {
1885    entries: Mutex<Vec<ScannerFailure>>,
1886}
1887
1888impl FailureLog {
1889    fn push(&self, failure: ScannerFailure) {
1890        // A poisoned lock means another thread panicked mid-push. Recover the
1891        // entries so the panic does not spread into an unrelated scanner.
1892        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1893        entries.push(failure);
1894    }
1895
1896    fn drain(&self) -> Vec<ScannerFailure> {
1897        let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
1898        std::mem::take(&mut *entries)
1899    }
1900
1901    fn snapshot(&self) -> Vec<ScannerFailure> {
1902        self.entries
1903            .lock()
1904            .unwrap_or_else(|e| e.into_inner())
1905            .clone()
1906    }
1907}
1908
1909/// The phases a context has run this sitting, closed and open, for a journal
1910/// to write down before the sitting ends.
1911///
1912/// A sitting's phases reach its journal whole when it stops cleanly. For one
1913/// killed outright, the journal writes these as it goes: each closed phase,
1914/// and the open one so far.
1915#[derive(Debug, Default)]
1916pub(crate) struct Sitting {
1917    phases: Mutex<SittingPhases>,
1918}
1919
1920/// What [`Sitting`] holds behind its lock: the phases closed so far, and the
1921/// one open now, if any.
1922#[derive(Debug, Default)]
1923struct SittingPhases {
1924    closed: Vec<crate::report::ScanPhase>,
1925    open: Option<crate::scanner::recorder::Opened>,
1926}
1927
1928impl Sitting {
1929    fn open(&self, opened: crate::scanner::recorder::Opened) {
1930        let mut phases = self.phases.lock().unwrap_or_else(|e| e.into_inner());
1931        phases.open = Some(opened);
1932    }
1933
1934    fn close(&self, phase: &crate::report::ScanPhase) {
1935        let mut phases = self.phases.lock().unwrap_or_else(|e| e.into_inner());
1936        phases.open = None;
1937        phases.closed.push(phase.clone());
1938    }
1939
1940    /// The closed phases, and the open one as it stands with `failures` filed
1941    /// against it and what it has concluded as `so_far` has it.
1942    #[cfg(feature = "journal-format")]
1943    fn standing(
1944        &self,
1945        failures: Vec<ScannerFailure>,
1946        so_far: &SoFar,
1947    ) -> Vec<crate::report::ScanPhase> {
1948        let phases = self.phases.lock().unwrap_or_else(|e| e.into_inner());
1949        let mut standing = phases.closed.clone();
1950        standing.extend(
1951            phases
1952                .open
1953                .as_ref()
1954                .map(|open| open.standing(failures, so_far)),
1955        );
1956        standing
1957    }
1958}
1959
1960/// The shared, cloneable handles that every scanning strategy needs: somewhere to
1961/// write discovered hosts, somewhere to announce updates, a way to check for abort,
1962/// and somewhere to record its own failure.
1963///
1964/// Every field is `pub(crate)`. A scanner writes findings through
1965/// [`write_host`](Self::write_host), which keeps the lock-then-announce
1966/// ordering. A consumer reads through [`ScanSession`].
1967#[derive(Clone)]
1968pub struct ScanContext {
1969    pub(crate) handle: ScanHandle,
1970    pub(crate) store: Arc<DashMap<ScopedIp, Host>>,
1971    pub(crate) events_tx: broadcast::Sender<ScanEvent>,
1972    pub(crate) failures: Arc<FailureLog>,
1973    /// Ground this scan declined to cover before sending anything.
1974    pub(crate) refusals: Arc<RefusalLog>,
1975    pub(crate) probe_stats: Arc<ProbeStatsLog>,
1976    /// Addresses this host could not reach, so no probe was sent to them.
1977    pub(crate) unroutable: Arc<UnroutableLog>,
1978    /// Addresses this host's routing table refuses. See
1979    /// [`note_refused_by_route`](Self::note_refused_by_route).
1980    pub(crate) refused_by_route: Arc<UnroutableLog>,
1981    /// Neighbour-table addresses the exclusions kept from a sweep. See
1982    /// [`note_withheld_neighbour`](Self::note_withheld_neighbour).
1983    pub(crate) withheld_neighbours: Arc<UnroutableLog>,
1984    /// Addresses the scan stopped working on because their budget ran out.
1985    pub(crate) timed_out: Arc<TimedOutLog>,
1986    /// The passes a stop skipped or cut short.
1987    pub(crate) passes_cut: Arc<PassLog>,
1988    /// Addresses whose ICMP errors the scan found rate-limited.
1989    pub(crate) icmp_rate_limited: Arc<RateLimitedLog>,
1990    /// Addresses a raw phase reached by TCP connect.
1991    pub(crate) reached_by_connect: Arc<ConnectLog>,
1992    /// Addresses a discovery pass found silent, or that a port phase standing
1993    /// in for one asked on every port and heard nothing from.
1994    pub(crate) silent: Arc<SilenceLog>,
1995    /// Addresses a port phase standing in for a liveness pass heard nothing
1996    /// from without finishing asking them.
1997    pub(crate) undecided: Arc<SilenceLog>,
1998    /// How many of the plan's targets a port phase's walk stopped short of.
1999    pub(crate) unreached: Arc<AtomicU64>,
2000    /// How many targets a port phase asked at the addresses whose records it
2001    /// forgot as heard nothing from.
2002    pub(crate) unheard_probes: Arc<AtomicU64>,
2003    /// Whether a port phase standing in for a liveness pass has yet to decide
2004    /// which of its records are hosts. See
2005    /// [`await_verdicts`](Self::await_verdicts).
2006    pub(crate) verdicts_pending: Arc<AtomicBool>,
2007    /// The phases this context has run this sitting. See [`Sitting`].
2008    pub(crate) sitting: Arc<Sitting>,
2009    /// Which stage's unit the plan, and so the settlements, are counted in.
2010    pub(crate) plan_stage: Stage,
2011    /// When each host's budget started, for a scan that set one.
2012    pub(crate) clocks: Arc<HostClocks>,
2013    /// The gaps kept between the probes this scan sends.
2014    pub(crate) spacing: Arc<ProbeSpacing>,
2015    /// The interface each of this scan's link-local targets was named on.
2016    ///
2017    /// A scanner addressing its targets one at a time holds a bare link-local
2018    /// address. Completing the key from this keeps a port scan's verdicts on
2019    /// the same record as the sweep's hardware address.
2020    ///
2021    /// Learned once the port phase knows which targets it kept, and empty for
2022    /// every scan that named no zone.
2023    pub(crate) zones: Arc<OnceLock<ZoneMap>>,
2024    /// The links a reply to this scan's probes can arrive by, which is where
2025    /// its captures listen; see
2026    /// [`capture_links_toward`](crate::transport::probe::capture_links_toward).
2027    ///
2028    /// Learned once the scan knows its targets, and unset for a caller
2029    /// orchestrating their own scan, whose captures listen on every link.
2030    pub(crate) capture_links: Arc<OnceLock<Vec<Zone>>>,
2031    /// How a port scan numbers its targets, for settling every target at an
2032    /// address it files as unreachable; see
2033    /// [`record_unroutable`](Self::record_unroutable).
2034    ///
2035    /// Learned once the scan knows which targets it kept, before its liveness
2036    /// pass, since that pass files addresses too. Empty for a sweep, which
2037    /// numbers addresses in [`positions`](Self::positions), and for a caller
2038    /// orchestrating their own scan.
2039    pub(crate) numbering: Arc<OnceLock<crate::model::target::TargetIndex>>,
2040    pub(crate) swept_links: Arc<SweptLinks>,
2041    /// Where this machine turned out to be plugged in, as the equipment said.
2042    pub(crate) attachments: Arc<Attachments>,
2043    /// Addresses no finding may be recorded against.
2044    ///
2045    /// Behind an `Arc` because a context is cloned once per strategy and every
2046    /// strategy only reads the policy.
2047    pub(crate) exclusions: Arc<Exclusions>,
2048    /// The machines `exclusions` names, by hardware address, and the other
2049    /// addresses they answer at; see [`Exclusions::hardware_in`].
2050    pub(crate) hardware: Arc<WithheldHardware>,
2051    /// Which hosts have findings a journal has not written down yet.
2052    ///
2053    /// Marked on every write, which is a different condition from the one that
2054    /// fires [`ScanEvent::HostUpdated`]: a watcher is told about novelty, while
2055    /// a journal records state. An enrichment pass adding evidence to a host
2056    /// already announced has nothing new to say and a lot to write down.
2057    ///
2058    /// Bounded by the number of distinct hosts, which the store holds anyway.
2059    pub(crate) changed: Arc<ChangedHosts>,
2060    /// What the scan is working on, and how far through it.
2061    pub(crate) stages: Arc<Stages>,
2062    /// What became of each target, for a resume that must not skip one.
2063    ///
2064    /// Separate from a target's verdict, which is the same for an exhausted
2065    /// probe, an interrupted one and one never sent. See
2066    /// [`journal::settle`](crate::journal::settle).
2067    pub(crate) settlements: Arc<Settlements>,
2068    /// How this scan numbers an address, when it is counted in addresses.
2069    ///
2070    /// Empty for every port scan, whose positions pair an address with a port
2071    /// and arrive on the target stream. A sweep has no such stream, since a
2072    /// [`HostScanner`](crate::scanner::strategy::HostScanner) owns its targets,
2073    /// so the numbering travels here.
2074    ///
2075    /// A port scan's liveness pass runs the discovery strategies, which settle
2076    /// addresses, against the port scan's context. Empty, this answers `None`
2077    /// to every address, so those settlements do not advance the port plan's
2078    /// watermark over probes nobody sent.
2079    pub(crate) positions: Arc<Positions>,
2080    /// The seed of the order this scan asks its targets in.
2081    ///
2082    /// [`None`] for a scan whose caller asked to walk the plan in order; see
2083    /// [`SessionBuilder::ordering`]. Read only by the dispatcher and the sweeps
2084    /// that hold their own first attempts.
2085    pub(crate) order_seed: Option<u64>,
2086    /// Each open port's gathered responses, kept from the service phase for the
2087    /// detection phase to hand a passive detection.
2088    pub(crate) responses: Arc<Responses>,
2089    /// The tapes of detection runs, captured for the journal to write down so a
2090    /// recorded scan can be replayed offline.
2091    pub(crate) tapes: Arc<Tapes>,
2092    /// The hosts an earlier sitting finished every pass over, for a sitting
2093    /// continuing a job. See [`owes_passes`](Self::owes_passes).
2094    finished: Arc<Finished>,
2095    /// The corpus the detection phase runs, the shipped one unless a caller set
2096    /// their own on the config. Cheap to clone: the compiled tiers sit behind
2097    /// `Arc`s.
2098    pub(crate) detections: crate::detect::Detections,
2099    /// The sources the scan forced, which decide where each connection it
2100    /// opens leaves from. Empty for a scan that forced none.
2101    pub(crate) forced: Arc<crate::transport::dial::ForcedSources>,
2102    /// The TCP ports this scan only connects to and listens on, sending nothing;
2103    /// see [`listens_only`](Self::listens_only).
2104    pub(crate) listen_only: Arc<BTreeSet<u16>>,
2105    /// The ports a sitting continuing a job excludes beyond what the job's
2106    /// plan is numbered without; see [`may_ask`](Self::may_ask).
2107    withheld_ports: Arc<crate::model::port::PortSet>,
2108    /// The name each address was asked for by, where a target named a host;
2109    /// see [`ZondConfig::target_names`](crate::config::ZondConfig::target_names).
2110    target_names: Arc<BTreeMap<IpAddr, Arc<str>>>,
2111}
2112
2113impl ScanContext {
2114    /// The name a target reached `ip` by, which its web ports are asked for
2115    /// by, or `None` where it was named by its address.
2116    pub(crate) fn target_name(&self, ip: IpAddr) -> Option<Arc<str>> {
2117        self.target_names.get(&ip).cloned()
2118    }
2119
2120    /// Where a connection this scan opens to `target` leaves from, and when.
2121    ///
2122    /// Asked by every phase that dials, once per destination, so a port the
2123    /// probe reached from a forced source is spoken to from that source too,
2124    /// and every connection and datagram keeps the scan's probe gaps; see
2125    /// [`dial::pacing`](crate::transport::dial::pacing).
2126    pub(crate) fn egress_toward(&self, target: IpAddr) -> crate::transport::dial::Egress {
2127        let gate = self
2128            .probe_gap()
2129            .map(|_| crate::transport::dial::pacing::Gate::new(std::sync::Arc::new(self.clone())));
2130        self.forced.toward(target).paced_by(gate)
2131    }
2132
2133    /// Whether this scan may do no more than connect to `number` over
2134    /// `protocol` and read what it volunteers.
2135    ///
2136    /// Asked by every pass that would put bytes on a port: the service pass and
2137    /// the connect scanner's inline identification, through
2138    /// [`service_detection_on`](Self::service_detection_on), and the detection
2139    /// and TLS enumeration passes, which leave such a port alone. Writing to
2140    /// such a port can make a printer print; see
2141    /// [`ZondConfig::listen_only_ports`](crate::config::ZondConfig::listen_only_ports).
2142    pub(crate) fn listens_only(&self, number: u16, protocol: Protocol) -> bool {
2143        protocol == Protocol::Tcp && self.listen_only.contains(&number)
2144    }
2145
2146    /// How far identification goes on one port under a scan asking for
2147    /// `detection`: that far, or no further than listening on a port this scan
2148    /// [only listens on](Self::listens_only).
2149    ///
2150    /// A cap, because connecting and reading is safe on any port and names
2151    /// every service that greets on connect. Everything past
2152    /// [`ServiceDetection::Banner`] sends something, including a handshake's
2153    /// ClientHello and an analyzer's second connection.
2154    pub(crate) fn service_detection_on(
2155        &self,
2156        detection: ServiceDetection,
2157        number: u16,
2158        protocol: Protocol,
2159    ) -> ServiceDetection {
2160        if self.listens_only(number, protocol) {
2161            detection.min(ServiceDetection::Banner)
2162        } else {
2163            detection
2164        }
2165    }
2166
2167    /// Records the responses the service phase gathered for one port, for the
2168    /// detection phase to hand a passive detection.
2169    pub(crate) fn record_responses(
2170        &self,
2171        ip: ScopedIp,
2172        number: u16,
2173        protocol: Protocol,
2174        banners: Vec<String>,
2175    ) {
2176        self.responses.record(ip, number, protocol, banners);
2177    }
2178
2179    /// Whether an earlier sitting identified this port and this one has not;
2180    /// see [`Responses`] on a port a sitting inherits.
2181    pub(crate) fn responses_lost(&self, ip: &ScopedIp, number: u16, protocol: Protocol) -> bool {
2182        self.responses.lost(ip, number, protocol)
2183    }
2184
2185    /// Takes a port's gathered responses, freeing them as the detection phase
2186    /// reads it.
2187    pub(crate) fn take_responses(
2188        &self,
2189        ip: &ScopedIp,
2190        number: u16,
2191        protocol: Protocol,
2192    ) -> Vec<String> {
2193        self.responses.take(ip, number, protocol)
2194    }
2195
2196    /// Whether this scan may address a probe to `address`.
2197    ///
2198    /// The send-side half of what [`Exclusions`] promises, for addresses a
2199    /// strategy learns while it runs. A segment sweep takes leads off the wire,
2200    /// from mDNS records and unsolicited advertisements, and asks each directly.
2201    /// None was in the target list, and [`write_host`](Self::write_host) sees
2202    /// only the answer, so this check keeps the question off the wire.
2203    ///
2204    /// Asked by whoever turns a learned address into a probe. A target the
2205    /// caller named was withheld by address up front, and is asked this only
2206    /// for the machine behind it, by the walk that hands a port scan its
2207    /// targets.
2208    ///
2209    /// An address a machine the policy names answers at is held to it as
2210    /// well, from the moment the neighbour tables or a reply tie the two; see
2211    /// [the machine an address names](crate::model::exclusion#an-address-names-a-machine).
2212    pub fn may_probe(&self, address: &IpAddr) -> bool {
2213        !self.exclusions.excludes(address) && !self.hardware.withholds(address)
2214    }
2215
2216    /// Whether this scan may send `target` its probe: [`may_probe`](Self::may_probe)
2217    /// its address, and its port is not one this sitting withholds.
2218    ///
2219    /// A port the caller excluded is out of the plan before anything numbers
2220    /// it. One a sitting continuing a job excludes beyond what the job did
2221    /// stays in the plan, since removing it would move every later target; the
2222    /// walk passes over its targets, settling each as withheld. See
2223    /// [`JobOptions`](crate::journal::manifest::JobOptions).
2224    pub(crate) fn may_ask(&self, target: &crate::model::target::Target) -> bool {
2225        self.may_probe(&target.ip) && !self.withheld_ports.contains(target.port, target.protocol)
2226    }
2227
2228    /// The single place a host finding enters the store.
2229    ///
2230    /// Upserts the host at `ip`, runs `edit` against it while the store guard is
2231    /// held, then releases that guard *before* emitting
2232    /// [`ScanEvent::HostUpdated`], so the DashMap lock is never held across the
2233    /// channel send. Returns `true` if this call created the host.
2234    ///
2235    /// `edit` returns whether the change is worth announcing: `false` suppresses
2236    /// the event, e.g. for a duplicate reply that revealed nothing new. A newly
2237    /// created host is always announced.
2238    ///
2239    /// Anything a caller must do *without* the guard held, such as hostname
2240    /// resolution or adaptive-deadline bookkeeping, keys off the returned flag
2241    /// and runs after this call. Callers that always announce their change use
2242    /// [`update_host`](Self::update_host).
2243    ///
2244    /// # Exclusions
2245    ///
2246    /// A key the scan's [`Exclusions`] forbid is dropped here: `edit` is not run,
2247    /// no host is created, no event is emitted, and this returns `false`. Every
2248    /// other address `edit` attaches to the host (later replies from the same
2249    /// machine, a merged sighting, an mDNS record's other addresses) is held to
2250    /// the same policy once it has run, so none reaches the report or becomes
2251    /// the address the host is reached at. A router on the host's path that the
2252    /// policy names, measured or spliced in from another trace, keeps its
2253    /// distance and loses its address; see
2254    /// [`Hop::withheld`](crate::model::host::Hop::withheld). A router or
2255    /// firewall the policy names that sent second-hand evidence, such as an ICMP
2256    /// unreachable, leaves its evidence on the host and its address off it; see
2257    /// [`EvidenceSource::Withheld`](crate::model::host::EvidenceSource::Withheld).
2258    ///
2259    /// Every finding reaches the store through this function, so this one branch
2260    /// covers what a target-list subtraction cannot: ARP and
2261    /// neighbour-advertisement replies, the host's own neighbour table, mDNS
2262    /// records, and, since they read the store to decide what to probe, the
2263    /// service, OS-series and SNMP phases that run afterwards.
2264    ///
2265    /// A host whose record, once `edit` has run, holds the hardware address of a
2266    /// machine the policy names is that machine at another address, and is
2267    /// dropped whole: its record leaves the store, no event is emitted, and
2268    /// every address it held is refused a probe from then on and listed with
2269    /// the phase's exclusions. See
2270    /// [the machine an address names](crate::model::exclusion#an-address-names-a-machine).
2271    ///
2272    /// A drop is logged, not counted: a reader can check that no excluded
2273    /// address appears in the report against the ranges it records. The
2274    /// addresses a machine's drop withholds are counted once, when the phase
2275    /// closes; see [`TargetScope::withheld`](crate::report::TargetScope::withheld).
2276    pub fn write_host(
2277        &self,
2278        key: impl Into<ScopedIp>,
2279        edit: impl FnOnce(&mut Host) -> bool,
2280    ) -> bool {
2281        let key = self.key(key);
2282        let ip = key.addr();
2283
2284        if self.exclusions.excludes(&ip) || self.hardware.withholds(&ip) {
2285            // Ordinary on a sweep, whose all-nodes echo also reaches excluded
2286            // neighbours; logged so the gate's work is visible.
2287            info!(
2288                verbosity = 2,
2289                "excluded address {ip} answered a probe it was not addressed; dropping the finding"
2290            );
2291            return false;
2292        }
2293
2294        let mut is_new = false;
2295        let mut host = self.store.entry(key.clone()).or_insert_with(|| {
2296            is_new = true;
2297            let mut host = Host::new(ip);
2298            // `Host::set_zone` keeps the first zone it is given, and the key's
2299            // zone is certain, since it is what the host was looked up by.
2300            if let Some(zone) = key.zone() {
2301                host.set_zone(zone.clone());
2302            }
2303            // Named as the caller's target named it; a reverse lookup leaves a
2304            // named host be.
2305            if let Some(name) = self.target_names.get(&ip) {
2306                host.set_hostname(Some(name.to_string()));
2307            }
2308            host
2309        });
2310        if self.changed.keeps_ports() {
2311            host.track_touched_ports();
2312        }
2313        let announce = edit(&mut host);
2314        // The key passed the gate above; what the edit attached has not. The
2315        // key's own address is kept, so the host never runs out of addresses.
2316        if !self.exclusions.is_empty() {
2317            let keep = |address: &IpAddr| !self.exclusions.excludes(address);
2318            let before = host.ips().len();
2319            host.retain_ips(keep);
2320            if host.ips().len() < before {
2321                info!(
2322                    verbosity = 2,
2323                    "an excluded address arrived beside {ip}; leaving it off the host"
2324                );
2325            }
2326            if host.withhold_intermediaries(keep) {
2327                info!(
2328                    verbosity = 2,
2329                    "an excluded router answered for a probe to {ip}; withholding its address"
2330                );
2331            }
2332            if self.hardware.names(&host) {
2333                let addresses = host.ips().clone();
2334                drop(host);
2335                self.store.remove(&key);
2336                info!(
2337                    verbosity = 2,
2338                    "{ip} answered from an excluded machine's hardware address; dropping it"
2339                );
2340                self.hardware.withhold(addresses);
2341                return false;
2342            }
2343        }
2344        let touched = host.take_touched_ports();
2345        drop(host);
2346
2347        // Marked whether or not the edit asked to be announced: announcing is
2348        // about novelty, journalling about state. The echo probe answers
2349        // `false` for a host already up, yet has just added an `icmp_echo`
2350        // reason and a round trip that the journal must record.
2351        //
2352        // Marked with the ports the edit touched, so the journal copies and
2353        // compares only those, plus the host's own fields; an edit that
2354        // changed nothing writes nothing.
2355        self.changed.insert(key.clone(), touched);
2356
2357        if announce || is_new {
2358            let _ = self.events_tx.send(ScanEvent::HostUpdated(key));
2359        }
2360        is_new
2361    }
2362
2363    /// Reads the host at `ip`, if there is one, without cloning it.
2364    ///
2365    /// The store's guard is held for the duration of `read` and released before
2366    /// this returns, so a caller cannot keep it across an await.
2367    ///
2368    /// `read` must not touch this context again: reaching back into the store
2369    /// under its own guard deadlocks.
2370    pub fn read_host<R>(
2371        &self,
2372        ip: impl Into<ScopedIp>,
2373        read: impl FnOnce(&Host) -> R,
2374    ) -> Option<R> {
2375        self.store
2376            .get(&self.key(ip))
2377            .map(|entry| read(entry.value()))
2378    }
2379
2380    /// `ip` as this scan keys a host under.
2381    ///
2382    /// A key that already names its interface is kept as it is. One that needs
2383    /// an interface and has none is completed from the zones the scan named its
2384    /// targets on, so a finding recorded against a bare `fe80::…` reaches the
2385    /// host it belongs to. An address needing no zone passes straight through.
2386    fn key(&self, ip: impl Into<ScopedIp>) -> ScopedIp {
2387        let key = ip.into();
2388        match key.is_unusable() {
2389            true => self
2390                .zones
2391                .get()
2392                .map_or(key.clone(), |zones| zones.key(key.addr())),
2393            false => key,
2394        }
2395    }
2396
2397    /// Records the links a reply to this scan's probes can arrive by. The
2398    /// first call decides; later ones are ignored.
2399    pub(crate) fn capture_on(&self, links: Vec<Zone>) {
2400        let _ = self.capture_links.set(links);
2401    }
2402
2403    /// The links this scan's captures listen on: those
2404    /// [`capture_on`](Self::capture_on) recorded, or every link that is up
2405    /// where nothing was.
2406    pub(crate) fn capture_links(&self) -> Vec<Zone> {
2407        self.capture_links
2408            .get()
2409            .cloned()
2410            .unwrap_or_else(crate::transport::probe::capturable_interfaces)
2411    }
2412
2413    /// Records which interface each of this scan's link-local targets was named
2414    /// on. The first call decides; later ones are ignored.
2415    pub(crate) fn learn_zones(&self, zones: ZoneMap) {
2416        let _ = self.zones.set(zones);
2417    }
2418
2419    /// Whether anything is recorded under `ip`.
2420    ///
2421    /// The writing half's [`HostStore::contains`].
2422    ///
2423    /// A question about the key: a host is recorded under one of its addresses,
2424    /// so this says whether there is a record here, not whether the machine is
2425    /// known.
2426    pub fn contains_host(&self, ip: &ScopedIp) -> bool {
2427        self.store.contains_key(&self.key(ip.clone()))
2428    }
2429
2430    /// Every address a host is currently recorded under.
2431    ///
2432    /// A snapshot, so a caller may call [`write_host`](Self::write_host) while
2433    /// walking it; holding a live iterator over the map would deadlock.
2434    pub fn host_addresses(&self) -> Vec<ScopedIp> {
2435        self.store.iter().map(|entry| entry.key().clone()).collect()
2436    }
2437
2438    /// The single place a strategy failure enters the record.
2439    ///
2440    /// Logs it, files it for the final report, and announces it to any live
2441    /// consumer, in that order, so the durable copy exists before the
2442    /// notification that might be dropped. The scan continues with the
2443    /// strategies that remain.
2444    ///
2445    /// Public so a caller running strategies themselves can file failures the
2446    /// way the engine's own orchestration does.
2447    ///
2448    /// The console line names the strategy as the report files it, then the
2449    /// reason.
2450    pub fn record_failure(&self, scanner: ScannerKind, reason: String) {
2451        error!(
2452            "{} failed: {reason}",
2453            crate::record::wire::scanner_kind_name(scanner)
2454        );
2455        self.failures
2456            .push(ScannerFailure::new(scanner, reason.clone()));
2457        let _ = self
2458            .events_tx
2459            .send(ScanEvent::ScannerFailed { scanner, reason });
2460    }
2461
2462    /// Where a strategy files work it began and could not finish because a
2463    /// limit it runs under was reached: a detection whose declared time or
2464    /// bytes were spent before its question was answered, a connection the
2465    /// process had no descriptor for, a pinned source port still in use.
2466    ///
2467    /// Filed like [`record_failure`](Self::record_failure), as a
2468    /// [`ScannerFailure`] and a [`ScanEvent::ScannerFailed`], since the report
2469    /// keeps one account of incomplete work. Nothing broke, so the entry is
2470    /// marked [cut short](ScannerFailure::is_cut_short) and the console gets a
2471    /// warning naming the limit, not an error.
2472    pub(crate) fn record_cut_short(&self, scanner: ScannerKind, reason: String) {
2473        crate::warn!("{reason}");
2474        self.file_cut_short(scanner, reason);
2475    }
2476
2477    /// [`record_cut_short`](Self::record_cut_short) without the console line,
2478    /// for a caller that announces many in one: a port given up on leaves every
2479    /// detection gated onto it unfinished, each with a report entry, under one
2480    /// line about the port.
2481    pub(crate) fn file_cut_short(&self, scanner: ScannerKind, reason: String) {
2482        self.failures
2483            .push(ScannerFailure::cut_short(scanner, reason.clone()));
2484        let _ = self
2485            .events_tx
2486            .send(ScanEvent::ScannerFailed { scanner, reason });
2487    }
2488
2489    /// The single place a refusal enters the record.
2490    ///
2491    /// A refusal is the engine working out, before anything is sent, that part
2492    /// of what it was asked has no strategy behind it: an SCTP port on a host
2493    /// with no raw sockets, a prefix too large to walk, a technique a connect
2494    /// scan cannot express. Nothing broke, so it is not announced on the event
2495    /// stream and no strategy is blamed; see [`Refusal`].
2496    ///
2497    /// Filed once per distinct refusal, so a plan that declines the same range
2498    /// on two links says it once.
2499    ///
2500    /// Not logged: a front end prints the report's refusals at every verbosity,
2501    /// and logging would show each twice.
2502    ///
2503    /// Public, like [`record_failure`](Self::record_failure), so a caller
2504    /// assembling their own scan can say what they declined.
2505    pub fn record_refusal(&self, refusal: Refusal) {
2506        self.refusals.push(refusal);
2507    }
2508
2509    /// Takes the refusals recorded so far, leaving the log empty.
2510    pub(crate) fn take_refusals(&self) -> Vec<Refusal> {
2511        self.refusals.drain()
2512    }
2513
2514    /// The refusals filed so far, left in place.
2515    ///
2516    /// The reading counterpart of [`record_refusal`](Self::record_refusal), as
2517    /// [`failures_snapshot`](Self::failures_snapshot) is for failures, for a
2518    /// caller driving strategies themselves.
2519    pub fn refusals_snapshot(&self) -> Vec<Refusal> {
2520        self.refusals.snapshot()
2521    }
2522
2523    /// Files what an instrumented scanner observed about its own run.
2524    ///
2525    /// Called once per scanner, as its receive loop exits. Not announced on the
2526    /// event stream, since it describes the run and changes no finding.
2527    ///
2528    /// Public, like [`record_failure`](Self::record_failure), so a custom
2529    /// strategy can account for its own run in the report's audit.
2530    pub fn record_probe_stats(&self, stats: ProbeStats) {
2531        self.probe_stats.push(stats);
2532    }
2533
2534    /// Takes the probe counters recorded so far, leaving the log empty.
2535    pub(crate) fn take_probe_stats(&self) -> Vec<ProbeStats> {
2536        self.probe_stats.drain()
2537    }
2538
2539    /// The probe counters filed so far, left in place.
2540    ///
2541    /// The reading counterpart of [`record_probe_stats`](Self::record_probe_stats),
2542    /// for a caller driving strategies themselves, who never reaches the phase
2543    /// that drains these into a [`ScanReport`](crate::report::ScanReport).
2544    /// It leaves the log in place, so the report still gets them.
2545    pub fn probe_stats_snapshot(&self) -> Vec<ProbeStats> {
2546        self.probe_stats.snapshot()
2547    }
2548
2549    /// Takes the failures recorded so far, leaving the log empty.
2550    ///
2551    /// Called once, when a phase assembles its report. Draining means a context
2552    /// that outlives its phase cannot hand the same failure to a second one.
2553    pub(crate) fn take_failures(&self) -> Vec<ScannerFailure> {
2554        self.failures.drain()
2555    }
2556
2557    /// Records that this host could not reach `address`, so no probe was sent
2558    /// to it: no route or source address led there, or the neighbour never
2559    /// answered address resolution.
2560    ///
2561    /// Neither a failure nor an event. It is recorded so the report says why a
2562    /// target the caller asked about is missing.
2563    ///
2564    /// Every target the plan numbers at the address is settled here as
2565    /// [`Unreachable`](Outcome::Unreachable), unless it earned a verdict of its
2566    /// own first: the address in a sweep's numbering, and each of its ports in
2567    /// a port scan's, whichever phase filed it. See
2568    /// [`Outcome::Unreachable`] for why that is settled.
2569    pub fn record_unroutable(&self, address: IpAddr) {
2570        self.unroutable.insert(address);
2571        if let Some(position) = self.positions.find(address) {
2572            self.settlements
2573                .record_unsettled(Outcome::Unreachable { position });
2574        }
2575        if let Some(index) = self.numbering.get() {
2576            for position in index.runs_at(address).flatten() {
2577                self.settlements
2578                    .record_unsettled(Outcome::Unreachable { position });
2579            }
2580        }
2581    }
2582
2583    /// Sets how this port scan numbers its targets; see
2584    /// [`numbering`](Self::numbering). The first numbering set stands.
2585    pub(crate) fn number_targets(&self, index: crate::model::target::TargetIndex) {
2586        let _ = self.numbering.set(index);
2587    }
2588
2589    /// Settles `address` as [`Withheld`](Outcome::Withheld), where this scan
2590    /// is counted in addresses and its plan numbers it: a target the policy
2591    /// forbids asking for the machine behind it, which a resume must not owe
2592    /// a question. Nothing for a scan counted otherwise, whose walk settles
2593    /// its own targets.
2594    pub(crate) fn settle_withheld(&self, address: IpAddr) {
2595        if let Some(position) = self.positions.find(address) {
2596            self.record_outcome(Outcome::Withheld { position });
2597        }
2598    }
2599
2600    /// Every address withheld so far for answering from the hardware of a
2601    /// machine the exclusions name, ascending: the ones the neighbour tables
2602    /// tied to it when the scan started, and the ones heard since. Left in
2603    /// place, since the policy holds for the whole scan and every later phase
2604    /// lists these among its exclusions too.
2605    pub(crate) fn withheld_by_hardware(&self) -> Vec<IpAddr> {
2606        self.hardware.addresses()
2607    }
2608
2609    /// The unroutable addresses filed so far, taken.
2610    pub(crate) fn take_unroutable(&self) -> Vec<IpAddr> {
2611        self.unroutable.drain()
2612    }
2613
2614    /// Notes that this host's own routing table refuses `address`, which is
2615    /// why whatever files it [unroutable](Self::record_unroutable) sent it
2616    /// nothing.
2617    ///
2618    /// Only a note on the reason: the strategy that meets the address files
2619    /// it, and a phase names an address refused by a route only where it also
2620    /// files it unroutable. See
2621    /// [`ScanPhase::refused_by_route`](crate::report::ScanPhase::refused_by_route).
2622    pub(crate) fn note_refused_by_route(&self, address: IpAddr) {
2623        self.refused_by_route.insert(address);
2624    }
2625
2626    /// The addresses noted refused by a route so far, taken.
2627    pub(crate) fn take_refused_by_route(&self) -> Vec<IpAddr> {
2628        self.refused_by_route.drain()
2629    }
2630
2631    /// Notes that the exclusions kept `address`, from this host's neighbour
2632    /// table, out of the phase's sweep. The phase counts it among the
2633    /// addresses its policy
2634    /// withheld; see
2635    /// [`TargetScope::withheld`](crate::report::TargetScope::withheld).
2636    pub(crate) fn note_withheld_neighbour(&self, address: IpAddr) {
2637        self.withheld_neighbours.insert(address);
2638    }
2639
2640    /// The neighbour-table addresses noted withheld so far, taken.
2641    pub(crate) fn take_withheld_neighbours(&self) -> Vec<IpAddr> {
2642        self.withheld_neighbours.drain()
2643    }
2644
2645    /// Whether `address` has been filed as unroutable in this phase, left in
2646    /// place.
2647    pub(crate) fn is_unroutable(&self, address: IpAddr) -> bool {
2648        self.unroutable.contains(address)
2649    }
2650
2651    /// Whether `address` has been filed as left early by its own budget in this
2652    /// phase, left in place.
2653    ///
2654    /// Unlike [`host_expired`](Self::host_expired), this files nothing, so a
2655    /// host whose clock runs out after its last probe still counts as covered
2656    /// in full.
2657    pub(crate) fn left_early(&self, address: IpAddr) -> bool {
2658        self.timed_out.contains(address)
2659    }
2660
2661    /// Marks every record nothing has answered at as one the phase has yet to
2662    /// decide, until [`verdicts_reached`](Self::verdicts_reached).
2663    ///
2664    /// For a port phase standing in for a liveness pass, which decides only at
2665    /// its end which of those records are hosts and forgets the rest as silent
2666    /// or undecided. A sitting killed outright never writes its closed phase,
2667    /// so the checkpoints write the phase as it stands, with what it has
2668    /// concluded so far; see [`ScanProgress::verdicts_so_far`].
2669    pub(crate) fn await_verdicts(&self) {
2670        self.verdicts_pending.store(true, Ordering::Release);
2671    }
2672
2673    /// Ends what [`await_verdicts`](Self::await_verdicts) began, once the phase
2674    /// has forgotten the records it heard nothing from.
2675    pub(crate) fn verdicts_reached(&self) {
2676        self.verdicts_pending.store(false, Ordering::Release);
2677    }
2678
2679    /// Files the host records at `keys` as addresses a port phase standing in
2680    /// for its liveness pass asked on every port and heard nothing from, and
2681    /// forgets those records.
2682    ///
2683    /// The liveness pass would have found each address silent and made no host
2684    /// of it. Forgetting the record keeps [`ScanSession::hosts`] after the scan
2685    /// in step with the report. The addresses go where a discovery pass files
2686    /// its silence, which the phase's
2687    /// [`silent`](crate::report::ScanPhase::silent) list is read from.
2688    ///
2689    /// A record a journal already wrote down is left out when the sitting's
2690    /// findings are written whole at its end, and dropped on read-back by the
2691    /// same list; see [`Unheard`](crate::report::Unheard). The ports it was
2692    /// asked are counted before it goes; see
2693    /// [`ScanPhase::unheard_probes`](crate::report::ScanPhase::unheard_probes).
2694    pub(crate) fn forget_silent(&self, keys: Vec<ScopedIp>) {
2695        for key in keys {
2696            self.silent.insert(key.addr());
2697            self.forget_unheard(&key);
2698        }
2699    }
2700
2701    /// Files the host records at `keys` as addresses a port phase standing in
2702    /// for its liveness pass heard nothing from and did not finish asking, and
2703    /// forgets those records.
2704    ///
2705    /// Nothing answered, so no host was found, and not every port was asked, so
2706    /// this is not silence either. They are named in the phase's
2707    /// [`undecided`](crate::report::ScanPhase::undecided) list, as the liveness
2708    /// pass would name them. Their ports stay unsettled, so a resume asks them
2709    /// again, and the ones already asked are counted before the record goes.
2710    pub(crate) fn forget_undecided(&self, keys: Vec<ScopedIp>) {
2711        for key in keys {
2712            self.undecided.insert(key.addr());
2713            self.forget_unheard(&key);
2714        }
2715    }
2716
2717    /// Drops the record at `key`, counting the ports it had been asked as
2718    /// [`unheard_probes`](crate::report::ScanPhase::unheard_probes) and the
2719    /// ones it had not with the targets the phase never reached, so the phase
2720    /// still accounts for every one. See
2721    /// [`ScanPhase::unreached`](crate::report::ScanPhase::unreached).
2722    fn forget_unheard(&self, key: &ScopedIp) {
2723        if let Some((_, host)) = self.store.remove(key) {
2724            let (unasked, asked): (Vec<_>, Vec<_>) = host
2725                .ports()
2726                .partition(|port| port.state() == PortState::Unasked);
2727            self.unheard_probes
2728                .fetch_add(asked.len() as u64, Ordering::Relaxed);
2729            self.record_unreached(unasked.len() as u64);
2730        }
2731    }
2732
2733    /// The addresses [`forget_undecided`](Self::forget_undecided) filed,
2734    /// merged and taken.
2735    pub(crate) fn take_undecided(&self) -> IpSet {
2736        self.undecided.drain()
2737    }
2738
2739    /// Records `count` of a port phase's targets as ones it never asked and
2740    /// holds on no host: passed by its walk undecided, left by a walk that
2741    /// stopped, or left unasked at an address whose record it dropped.
2742    ///
2743    /// A count, since a walk stopped early on a wide plan leaves them scattered
2744    /// across all of it. They stay unsettled, so a resume asks them. See
2745    /// [`ScanPhase::unreached`](crate::report::ScanPhase::unreached).
2746    pub(crate) fn record_unreached(&self, count: u64) {
2747        self.unreached.fetch_add(count, Ordering::Relaxed);
2748    }
2749
2750    /// The count [`record_unreached`](Self::record_unreached) filed, taken.
2751    pub(crate) fn take_unreached(&self) -> u64 {
2752        self.unreached.swap(0, Ordering::Relaxed)
2753    }
2754
2755    /// How many targets the records [`forget_silent`](Self::forget_silent)
2756    /// and [`forget_undecided`](Self::forget_undecided) dropped had been
2757    /// asked, taken. See
2758    /// [`ScanPhase::unheard_probes`](crate::report::ScanPhase::unheard_probes).
2759    pub(crate) fn take_unheard_probes(&self) -> u64 {
2760        self.unheard_probes.swap(0, Ordering::Relaxed)
2761    }
2762
2763    /// Whether `address` has spent the per-host budget this scan was given,
2764    /// starting its clock on the first probe aimed at it.
2765    ///
2766    /// Every pass asks this before probing a host again. A host that answers
2767    /// true writes itself into the phase's
2768    /// [`timed_out`](crate::report::ScanPhase::timed_out) list, so no strategy
2769    /// can leave a host early without the report saying so.
2770    ///
2771    /// Always false, and cheap, for a scan with no budget. See
2772    /// [`ZondConfig::host_timeout`](crate::config::ZondConfig::host_timeout).
2773    pub fn host_expired(&self, address: IpAddr) -> bool {
2774        if !self.clocks.expired(address) {
2775            return false;
2776        }
2777        self.timed_out.insert(address);
2778        true
2779    }
2780
2781    /// Whether the passes that follow a scan's probes are owed `host` in this
2782    /// sitting: service identification, the detections, TLS enumeration, the
2783    /// active OS probes, the route trace and the rest that ask something of a
2784    /// host, and those that write a conclusion back, since a host written to
2785    /// is written to the journal whole again.
2786    ///
2787    /// Every host is owed them except one an earlier sitting ran to its end
2788    /// with, whose answers are already in its record. Such a host is owed them
2789    /// again where this sitting still has a target at one of its addresses,
2790    /// since that target may reveal a port or service the passes have not
2791    /// seen.
2792    ///
2793    /// A sitting killed or stopped before its end records nothing finished, so
2794    /// the next owes all its hosts the passes. A pass asked twice costs probes;
2795    /// one never asked leaves a record silently short.
2796    pub(crate) fn owes_passes(&self, host: &Host) -> bool {
2797        let finished = &self.finished;
2798        !finished.hosts.contains(&host.scoped_ip().to_string())
2799            || host.ips().iter().any(|ip| finished.asked.contains(ip))
2800    }
2801
2802    /// The hosts owed the passes that follow the probes, keyed as
2803    /// [`host_addresses`](Self::host_addresses) keys them; see
2804    /// [`owes_passes`](Self::owes_passes).
2805    pub(crate) fn hosts_owed_passes(&self) -> Vec<ScopedIp> {
2806        self.host_addresses()
2807            .into_iter()
2808            .filter(|key| {
2809                self.read_host(key, |host| self.owes_passes(host))
2810                    .unwrap_or(false)
2811            })
2812            .collect()
2813    }
2814
2815    /// When a probe to `address` may next leave, or `None` if it may now.
2816    ///
2817    /// For choosing which probe to try: another pass may take the slot before
2818    /// the send. [`claim_probe`](Self::claim_probe) decides.
2819    ///
2820    /// **Being turned away is not a verdict.** The probe has not been sent, so
2821    /// a caller that drops it reports an unasked port as silent. Hold it and
2822    /// try again at the instant returned, or file it
2823    /// [`Unasked`](crate::model::port::PortState::Unasked).
2824    ///
2825    /// Always `None`, and cheap, for a scan that keeps no gap. See
2826    /// [`ZondConfig::host_probe_interval`](crate::config::ZondConfig::host_probe_interval)
2827    /// and [`ZondConfig::probe_interval`](crate::config::ZondConfig::probe_interval).
2828    pub fn probe_ready_at(&self, address: IpAddr, now: Instant) -> Option<Instant> {
2829        self.spacing.ready_at(address, now)
2830    }
2831
2832    /// Takes the slot for one probe to `address`, or says when one will be
2833    /// free.
2834    ///
2835    /// Every send site asks this immediately before sending, beside
2836    /// [`host_expired`](Self::host_expired). An expired host is finished with
2837    /// and goes into the phase's
2838    /// [`timed_out`](crate::report::ScanPhase::timed_out) list; a host turned
2839    /// away here will be ready at the instant returned. As with
2840    /// [`probe_ready_at`](Self::probe_ready_at), a probe turned away is owed a
2841    /// send or an `Unasked`, never a silence.
2842    ///
2843    /// The decision and the record are one operation, so concurrent passes
2844    /// share one bound. A send the kernel refuses gives the slot back with
2845    /// [`refund_probe`](Self::refund_probe).
2846    ///
2847    /// Always granted for a scan that keeps no gap, and then nothing is locked
2848    /// or stored.
2849    pub fn claim_probe(&self, address: IpAddr) -> Result<ProbeClaim, Instant> {
2850        self.spacing.claim(address)
2851    }
2852
2853    /// Gives back the slot `claim` took, for a probe that never reached the
2854    /// wire.
2855    ///
2856    /// A probe the kernel refused must not spend a slot, as
2857    /// `RawProbeScan::record_send` keeps it out of the congestion window. A
2858    /// slot another probe has been recorded over since stays spent, which can
2859    /// only lengthen a gap.
2860    pub fn refund_probe(&self, claim: ProbeClaim) {
2861        self.spacing.refund(claim);
2862    }
2863
2864    /// Takes the slot for one frame sent to `group`, a broadcast or multicast
2865    /// address, or says when one will be free.
2866    ///
2867    /// A frame to a group spends the scan-wide gap like any probe, but moves no
2868    /// host's clock, since it singles out no machine. A frame that asks about
2869    /// one address, as a broadcast ARP request does, is aimed at that address
2870    /// and claims with [`claim_probe`](Self::claim_probe).
2871    ///
2872    /// Otherwise as [`claim_probe`](Self::claim_probe): taken immediately
2873    /// before the send, a frame turned away is owed a send later, and one the
2874    /// kernel refused gives its slot back with
2875    /// [`refund_probe`](Self::refund_probe).
2876    pub fn claim_group_probe(&self, group: IpAddr) -> Result<ProbeClaim, Instant> {
2877        self.spacing.claim_group(group)
2878    }
2879
2880    /// When a frame sent to a group may next leave, or `None` if it may now;
2881    /// see [`claim_group_probe`](Self::claim_group_probe).
2882    ///
2883    /// This is also when *any* probe may next leave as far as the scan-wide gap
2884    /// goes. Always `None` for a scan that keeps no scan-wide gap.
2885    pub fn group_probe_ready_at(&self, now: Instant) -> Option<Instant> {
2886        self.spacing.group_ready_at(now)
2887    }
2888
2889    /// The longer of the gaps this scan keeps between probes, or `None` for a
2890    /// scan that keeps neither.
2891    ///
2892    /// For a scanner sizing its own deadline. See
2893    /// [`ZondConfig::host_probe_interval`](crate::config::ZondConfig::host_probe_interval)
2894    /// and [`ZondConfig::probe_interval`](crate::config::ZondConfig::probe_interval).
2895    pub(crate) fn probe_gap(&self) -> Option<Duration> {
2896        self.spacing.longest()
2897    }
2898
2899    /// The gap this scan keeps between any two probes, wherever they are
2900    /// aimed, or `None` for a scan that keeps none. A pass whose deadline is
2901    /// sized from its own send rate reads it as a cap on that rate.
2902    pub(crate) fn scan_probe_interval(&self) -> Option<Duration> {
2903        self.spacing.scan_wide
2904    }
2905
2906    /// The addresses left early so far, taken.
2907    pub(crate) fn take_timed_out(&self) -> Vec<IpAddr> {
2908        self.timed_out.drain()
2909    }
2910
2911    /// Whether the scan is stopping, recording `pass` as cut by the stop if
2912    /// it is.
2913    ///
2914    /// Asked by a pass that has work in front of it, before it begins and
2915    /// between items, so the report names the passes a stop cut; see
2916    /// [`ScanPhase::passes_cut`](crate::report::ScanPhase::passes_cut). A pass
2917    /// with nothing to do does not ask.
2918    pub(crate) fn stopping_before(&self, pass: Pass) -> bool {
2919        let stopping = self.handle.should_stop();
2920        if stopping {
2921            self.passes_cut.insert(pass);
2922        }
2923        stopping
2924    }
2925
2926    /// The passes a stop has cut so far, taken, in the order a scan runs them.
2927    pub(crate) fn take_passes_cut(&self) -> Vec<Pass> {
2928        self.passes_cut.drain()
2929    }
2930
2931    /// Records that `address` rate-limited the ICMP errors a scanner reads
2932    /// its verdicts from, so the ports it had no allowance to answer for
2933    /// read as silent; see
2934    /// [`ScanPhase::icmp_rate_limited`](crate::report::ScanPhase::icmp_rate_limited).
2935    pub(crate) fn record_icmp_rate_limited(&self, address: IpAddr) {
2936        self.icmp_rate_limited.insert(address);
2937    }
2938
2939    /// The addresses found rate-limiting their ICMP errors so far, taken.
2940    pub(crate) fn take_icmp_rate_limited(&self) -> Vec<IpAddr> {
2941        self.icmp_rate_limited.drain()
2942    }
2943
2944    /// Records that `targets` were reached by TCP connect in a phase that held
2945    /// the privilege its raw strategies need.
2946    ///
2947    /// For a strategy that, inside a raw phase, reaches its targets by connect:
2948    /// loopback in any raw phase, and whatever self-built frames cannot reach
2949    /// when frames are all the process has. Its findings are connect evidence,
2950    /// which the phase's privilege alone would present as raw. Ignored by a
2951    /// phase recorded at
2952    /// [`Privilege::Connect`](crate::system::privilege::Privilege::Connect),
2953    /// which reached everything this way. See
2954    /// [`ScanPhase::reached_by_connect`](crate::report::ScanPhase::reached_by_connect).
2955    pub fn record_reached_by_connect(&self, targets: &IpSet) {
2956        self.reached_by_connect.extend(targets);
2957    }
2958
2959    /// The addresses reached by connect so far, merged and taken, less
2960    /// `unreached`: the addresses the phase filed unroutable.
2961    ///
2962    /// The log holds everything a strategy was handed, and an address a local
2963    /// route refused was never asked and holds no connect evidence.
2964    pub(crate) fn take_reached_by_connect(&self, unreached: &[IpAddr]) -> Vec<IpRange> {
2965        self.reached_by_connect.drain(unreached)
2966    }
2967
2968    /// Records that this phase swept a whole link, beyond the addresses on it
2969    /// that were named.
2970    ///
2971    /// Called by a strategy that sent a probe every host on the segment must
2972    /// answer. See [`TargetScope::links`](crate::report::TargetScope::links):
2973    /// a comparison can then tell a new host on a watched link from one on
2974    /// ground nobody covered.
2975    pub fn record_sweep(&self, zone: Zone) {
2976        self.swept_links.insert(zone);
2977    }
2978
2979    /// Takes the links swept so far, leaving the log empty.
2980    pub(crate) fn take_swept_links(&self) -> Vec<Zone> {
2981        self.swept_links.drain()
2982    }
2983
2984    /// Records which switch port this machine turned out to be plugged into.
2985    ///
2986    /// Called by whatever read an announcement off a link; see [`Attachment`]
2987    /// for why this belongs to the phase. A device re-announcing itself
2988    /// replaces the previous reading for that link and protocol.
2989    pub fn record_attachment(&self, attachment: Attachment) {
2990        self.attachments.insert(attachment);
2991    }
2992
2993    /// Takes the attachments observed so far, leaving the log empty.
2994    pub(crate) fn take_attachments(&self) -> Vec<Attachment> {
2995        self.attachments.drain()
2996    }
2997
2998    /// Records that a phase has opened, for a journal to write down what it
2999    /// is before it closes. See [`Sitting`].
3000    pub(crate) fn open_phase(&self, opened: crate::scanner::recorder::Opened) {
3001        self.sitting.open(opened);
3002    }
3003
3004    /// Records that the open phase has closed as `phase`. See [`Sitting`].
3005    pub(crate) fn close_phase(&self, phase: &crate::report::ScanPhase) {
3006        self.sitting.close(phase);
3007    }
3008
3009    /// Records what became of one target, for a later resume.
3010    ///
3011    /// Separate from the verdict: a target reaches the store with a port
3012    /// state, and this says whether the scan *earned* it or assigned it
3013    /// because the run ended. See [`Outcome`].
3014    ///
3015    /// Call this only once the target's finding is in the store. A checkpoint
3016    /// reads the settlements before it takes the changed hosts, so settling
3017    /// first could write a cursor that skips the target beside a findings file
3018    /// without it, and a resume would never report the finding. See
3019    /// [`checkpoint`](crate::scanner::checkpoint).
3020    pub fn record_outcome(&self, outcome: Outcome) {
3021        self.settlements.record(outcome);
3022    }
3023
3024    /// Announces the stage the scan has moved into, with how much work it holds
3025    /// where that is known before any of it is done.
3026    ///
3027    /// Entering the stage that is already current adds to its total, so service
3028    /// detection running once per protocol reports one stage the size of both
3029    /// runs.
3030    pub fn enter_stage(&self, stage: Stage, total: Option<u64>) {
3031        if self.stages.enter(stage, total) {
3032            let _ = self.events_tx.send(ScanEvent::StageChanged { stage });
3033        }
3034    }
3035
3036    /// Counts one unit of the current stage as finished.
3037    ///
3038    /// Called where the work completes. A stage that submits into a pool hands
3039    /// out all its work long before any of it is done.
3040    pub fn stage_advanced(&self) {
3041        self.stages.advance();
3042    }
3043
3044    /// Records `count` targets ending the same way, for the outcomes that carry
3045    /// no position. See [`Settlements::record_many`].
3046    pub fn record_many_outcomes(&self, outcome: Outcome, count: u64) {
3047        self.settlements.record_many(outcome, count);
3048    }
3049
3050    /// Records `count` addresses a sweep left unsettled the same way, where the
3051    /// scan's settlements are counted in addresses.
3052    ///
3053    /// A port scan's plan counts address-and-port pairs, so its liveness pass's
3054    /// addresses are left out of the tally. The pass accounts for them in its
3055    /// phase's [`undecided`](crate::report::ScanPhase::undecided) list.
3056    pub(crate) fn record_address_outcomes(&self, outcome: Outcome, count: u64) {
3057        if self.plan_stage != Stage::Ports {
3058            self.settlements.record_many(outcome, count);
3059        }
3060    }
3061
3062    /// Records what became of one address, in a scan counted in addresses.
3063    ///
3064    /// The position comes from the plan this scan is numbered in, so a
3065    /// strategy needs only the address and what came back.
3066    ///
3067    /// Nothing is settled in two cases. A scan not counted in addresses has no
3068    /// numbering, so a port scan's liveness pass settles nothing. An address
3069    /// the plan does not name, such as a neighbour a sweep found unasked, has
3070    /// no position. Either way the address is asked again on the next sitting,
3071    /// which is the safe direction.
3072    ///
3073    /// Silence is recorded in both cases, for two readers. The port phase after
3074    /// a liveness pass settles the ports of a host found down; see
3075    /// [`Outcome::Skipped`]. And every discovery phase names the addresses it
3076    /// reached no verdict on: its scope less what answered and what was asked
3077    /// to exhaustion; see
3078    /// [`ScanPhase::undecided`](crate::report::ScanPhase::undecided).
3079    ///
3080    /// Call this only once the answer's finding is in the store; see
3081    /// [`record_outcome`](Self::record_outcome).
3082    pub fn settle_address(&self, ip: IpAddr, settled: Settled) {
3083        if let Some(position) = self.positions.find(ip) {
3084            self.record_outcome(settled.at(position));
3085        }
3086        if settled == Settled::Exhausted {
3087            self.silent.insert(ip);
3088        }
3089    }
3090
3091    /// The addresses a discovery pass asked as many times as its policy allows
3092    /// and heard nothing from, merged and taken.
3093    ///
3094    /// Only these may have their ports settled as
3095    /// [`Skipped`](crate::journal::settle::Outcome::Skipped), and only these
3096    /// keep an address out of a phase's
3097    /// [`undecided`](crate::report::ScanPhase::undecided) list without a host
3098    /// found at it. An address the pass reached no verdict on is not here. See
3099    /// [`Dispatcher::screened`](crate::scanner::dispatcher::Dispatcher::screened).
3100    pub(crate) fn take_silent(&self) -> IpSet {
3101        self.silent.drain()
3102    }
3103
3104    /// How far the scan has got, and what became of what it did not settle.
3105    pub fn settlements(&self) -> &Settlements {
3106        &self.settlements
3107    }
3108
3109    /// Seeds the store with hosts an earlier sitting found.
3110    ///
3111    /// Merged, so a host this sitting has already seen keeps both readings.
3112    ///
3113    /// Each restored host is announced, since to a caller watching the stream
3114    /// it has just appeared. It is not marked *changed*, since it came from the
3115    /// journal.
3116    ///
3117    /// This sitting's exclusions apply to what comes back, address by address,
3118    /// as in [`write_host`](Self::write_host), since a journal written before
3119    /// an exclusion was added may hold addresses it now forbids. A host loses
3120    /// each of those, and is restored under its best remaining address if its
3121    /// key was among them; a host with no address left is left out. Routers on
3122    /// its path and senders of evidence the policy names lose their addresses
3123    /// as they would in `write_host`.
3124    ///
3125    /// The journal itself is left as recorded; only what this sitting reports
3126    /// changes.
3127    pub fn restore_hosts(&self, hosts: &[Host]) {
3128        let keep = |address: &IpAddr| !self.exclusions.excludes(address);
3129        for host in hosts {
3130            let mut host = host.clone();
3131            if !host.retain_ips(keep) {
3132                info!(
3133                    verbosity = 2,
3134                    "every address of {} in the journal is excluded; leaving it out of this sitting",
3135                    host.primary_ip()
3136                );
3137                continue;
3138            }
3139            host.withhold_intermediaries(keep);
3140            host.withhold_ports(&self.withheld_ports);
3141
3142            let key = host.scoped_ip();
3143            // What the earlier sitting drew identifying these ports ended
3144            // with it; see `Responses`.
3145            for port in host.ports() {
3146                if port.state() == PortState::Open {
3147                    self.responses
3148                        .inherit(key.clone(), port.number(), port.protocol());
3149                }
3150            }
3151            match self.store.get_mut(&key) {
3152                Some(mut existing) => {
3153                    existing.merge(host);
3154                    // The journal already holds what the merge touched.
3155                    let _ = existing.take_touched_ports();
3156                }
3157                None => {
3158                    self.store.insert(key.clone(), host);
3159                }
3160            }
3161            let _ = self.events_tx.send(ScanEvent::HostUpdated(key));
3162        }
3163    }
3164
3165    /// What a journal needs from a running scan.
3166    ///
3167    /// A [`ScanContext`] carries the event sender, and a checkpoint task
3168    /// holding one would keep the event stream open after the scan ended: a
3169    /// caller waiting for the stream to end would wait for the checkpoint task,
3170    /// which waits for the caller to stop it.
3171    ///
3172    /// A failure recorded through this reaches the report but not the stream,
3173    /// since a checkpoint that could not be written is about the journal, not a
3174    /// scanning strategy.
3175    ///
3176    /// From the first call on, the detection phase keeps its runs' tapes for
3177    /// [`ScanProgress::take_tapes`], and which ports of a host changed is
3178    /// tracked too.
3179    pub fn progress(&self) -> ScanProgress {
3180        self.tapes.keep();
3181        self.changed.keep_ports();
3182        ScanProgress {
3183            store: Arc::clone(&self.store),
3184            changed: Arc::clone(&self.changed),
3185            settlements: Arc::clone(&self.settlements),
3186            failures: Arc::clone(&self.failures),
3187            tapes: Arc::clone(&self.tapes),
3188            #[cfg(feature = "journal-format")]
3189            verdicts_pending: Arc::clone(&self.verdicts_pending),
3190            #[cfg(feature = "journal-format")]
3191            sitting: Arc::clone(&self.sitting),
3192            #[cfg(feature = "journal-format")]
3193            numbering: Arc::clone(&self.numbering),
3194        }
3195    }
3196
3197    /// Every host found so far, cloned, ordered by the address each is keyed
3198    /// under.
3199    ///
3200    /// For a journal compacting its findings. Ordered so the same findings
3201    /// produce the same file.
3202    pub fn hosts_snapshot(&self) -> Vec<Host> {
3203        let mut hosts: Vec<Host> = self
3204            .store
3205            .iter()
3206            .map(|entry| entry.value().clone())
3207            .collect();
3208        hosts.sort_by_cached_key(Host::scoped_ip);
3209        hosts
3210    }
3211
3212    /// How many hosts have been found so far.
3213    pub fn host_count(&self) -> usize {
3214        self.store.len()
3215    }
3216
3217    /// Takes the hosts whose findings have changed since this was last called,
3218    /// with their current state.
3219    ///
3220    /// For a journal writing findings down as a scan produces them. Draining,
3221    /// so a host is written once per change.
3222    pub fn take_changed_hosts(&self) -> Vec<Host> {
3223        changed_since(&self.store, &self.changed)
3224    }
3225
3226    /// The strategy failures filed so far, left in place.
3227    ///
3228    /// The reading counterpart of [`record_failure`](Self::record_failure), like
3229    /// [`probe_stats_snapshot`](Self::probe_stats_snapshot), for a caller
3230    /// driving strategies themselves who wants failures before a phase closes.
3231    ///
3232    /// Leaves the log in place for
3233    /// [`PhaseRecorder::finish`](crate::scanner::recorder::PhaseRecorder::finish)
3234    /// to drain into the report.
3235    pub fn failures_snapshot(&self) -> Vec<ScannerFailure> {
3236        self.failures.snapshot()
3237    }
3238
3239    /// Upserts the host at `ip`, applies `update`, and unconditionally announces
3240    /// the change. The convenience form of [`write_host`](Self::write_host) for
3241    /// paths that always record a finding worth emitting, such as a port state
3242    /// or a merged host. Returns `true` if this call created the host.
3243    pub fn update_host(&self, ip: impl Into<ScopedIp>, update: impl FnOnce(&mut Host)) -> bool {
3244        self.write_host(ip, |host| {
3245            update(host);
3246            true
3247        })
3248    }
3249}
3250
3251/// The machines a scan's exclusions name, by hardware address, and every other
3252/// address one of them answers at.
3253///
3254/// The hardware is read once, when the scan starts, from the host's neighbour
3255/// tables, so every finding is held to the same policy. The addresses start as
3256/// the ones the same tables tie to that hardware, so a target named at one of
3257/// them is asked nothing, and grow as the scan hears more.
3258/// See [`Exclusions::hardware_in`] and [`Exclusions::tied_to`].
3259#[derive(Debug, Default)]
3260pub(crate) struct WithheldHardware {
3261    macs: BTreeSet<MacAddr>,
3262    addresses: Mutex<BTreeSet<IpAddr>>,
3263}
3264
3265impl WithheldHardware {
3266    /// Withholds the machines `exclusions` names in `table`, a neighbour
3267    /// table's addresses and the hardware each resolved to, at every address
3268    /// the table ties to them.
3269    fn read(exclusions: &Exclusions, table: Vec<(IpAddr, Option<MacAddr>)>) -> Self {
3270        let macs = exclusions.hardware_in(table.iter().copied());
3271        let tied = exclusions.tied_to(&macs, table);
3272        if !macs.is_empty() {
3273            info!(
3274                verbosity = 1,
3275                "excluding {} by hardware address too",
3276                crate::counted(macs.len() as u128, "machine", "machines")
3277            );
3278        }
3279        Self {
3280            macs,
3281            addresses: Mutex::new(tied),
3282        }
3283    }
3284
3285    /// Whether `host` answered from the hardware of a machine withheld here.
3286    fn names(&self, host: &Host) -> bool {
3287        !self.macs.is_empty()
3288            && host
3289                .hardware()
3290                .is_some_and(|hardware| hardware.macs().keys().any(|mac| self.macs.contains(mac)))
3291    }
3292
3293    /// Whether `address` answers from such hardware, as the neighbour tables
3294    /// or a reply said.
3295    fn withholds(&self, address: &IpAddr) -> bool {
3296        !self.macs.is_empty()
3297            && self
3298                .addresses
3299                .lock()
3300                .expect("the withheld addresses are never poisoned")
3301                .contains(address)
3302    }
3303
3304    /// Records `addresses` as heard from such hardware.
3305    fn withhold(&self, addresses: impl IntoIterator<Item = IpAddr>) {
3306        self.addresses
3307            .lock()
3308            .expect("the withheld addresses are never poisoned")
3309            .extend(addresses);
3310    }
3311
3312    /// Every address tied to such hardware so far, ascending.
3313    fn addresses(&self) -> Vec<IpAddr> {
3314        self.addresses
3315            .lock()
3316            .expect("the withheld addresses are never poisoned")
3317            .iter()
3318            .copied()
3319            .collect()
3320    }
3321}
3322
3323/// The order a session's scan asks its targets in, as its caller left it.
3324#[derive(Debug, Default, Clone, Copy)]
3325enum Order {
3326    /// Nothing said: a seed is drawn when the session is built.
3327    #[default]
3328    Drawn,
3329    /// The walk this seed names.
3330    Seeded(u64),
3331    /// Plan order, shuffled within a batch.
3332    Planned,
3333}
3334
3335/// Builds a [`ScanSession`] and the [`ScanContext`] the strategies behind it
3336/// write into.
3337///
3338/// Everything a session can be given beyond its defaults, most of which a
3339/// caller leaves alone. Each setting is named once, and an unset one keeps its
3340/// neutral value.
3341///
3342/// ```no_run
3343/// use zond_engine::scanner::session::ScanSession;
3344///
3345/// let (session, ctx) = ScanSession::builder().build();
3346/// # let _ = (session, ctx);
3347/// ```
3348#[must_use]
3349#[derive(Debug, Default)]
3350pub struct SessionBuilder {
3351    exclusions: Exclusions,
3352    settled: crate::journal::cursor::Checkpoint,
3353    positions: Positions,
3354    planned: Option<u64>,
3355    plan_stage: Stage,
3356    staging: Vec<Stage>,
3357    detections: crate::detect::Detections,
3358    host_timeout: Option<Duration>,
3359    scan_timeout: Option<Duration>,
3360    host_probe_interval: Option<Duration>,
3361    probe_interval: Option<Duration>,
3362    order: Order,
3363    send_source: Vec<IpAddr>,
3364    /// `None` for the default, [`RAW_PRINT_PORTS`](crate::config::RAW_PRINT_PORTS).
3365    listen_only: Option<BTreeSet<u16>>,
3366    withheld_ports: crate::model::port::PortSet,
3367    /// The neighbour tables the exclusions are read against for the machines
3368    /// they name; `None` to read the host's own.
3369    neighbours: Option<Vec<(IpAddr, Option<MacAddr>)>>,
3370    finished: Finished,
3371    target_names: BTreeMap<IpAddr, String>,
3372}
3373
3374impl SessionBuilder {
3375    /// Addresses the scan may not record a finding against.
3376    ///
3377    /// A caller orchestrating their own scan under an exclusion policy has to
3378    /// set this as well as subtracting the addresses from their target list,
3379    /// since a segment sweep reaches beyond the addresses named. See
3380    /// [`Exclusions`] for what each of the two enforcements is for.
3381    ///
3382    /// A policy naming an address on a segment this host has spoken to
3383    /// recently names the machine there too, whatever other addresses it
3384    /// answers at: [`build`](Self::build) reads the host's neighbour tables for
3385    /// its hardware address. See [`Exclusions`].
3386    pub fn excluding(mut self, exclusions: Exclusions) -> Self {
3387        self.exclusions = exclusions;
3388        self
3389    }
3390
3391    /// The name each address was asked for by, where a target named a host.
3392    ///
3393    /// A host recorded at one of these addresses carries its name as its
3394    /// hostname from the moment it is recorded, and its web ports are asked
3395    /// for by it; see
3396    /// [`ZondConfig::target_names`](crate::config::ZondConfig::target_names).
3397    pub fn naming(mut self, names: BTreeMap<IpAddr, String>) -> Self {
3398        self.target_names = names;
3399        self
3400    }
3401
3402    /// The neighbour tables the exclusions are read against, replacing the
3403    /// host's own: each address and the hardware address it resolved to.
3404    #[cfg(test)]
3405    pub(crate) fn with_neighbours(mut self, table: Vec<(IpAddr, Option<MacAddr>)>) -> Self {
3406        self.neighbours = Some(table);
3407        self
3408    }
3409
3410    /// The cursor this scan checkpoints from, for one continuing an earlier
3411    /// sitting.
3412    ///
3413    /// Without it a resumed scan writes a cursor covering only its own sitting,
3414    /// and the journal forgets everything the first one settled.
3415    pub fn resuming(mut self, settled: &crate::journal::cursor::Checkpoint) -> Self {
3416        self.settled = settled.clone();
3417        self
3418    }
3419
3420    /// The hosts an earlier sitting of this job finished every pass over,
3421    /// named as the journal writes them, and the addresses this sitting still
3422    /// has something to ask; see [`ScanContext::owes_passes`].
3423    #[cfg(feature = "journal-format")]
3424    pub(crate) fn finished(mut self, hosts: HashSet<String>, asked: IpSet) -> Self {
3425        self.finished = Finished { hosts, asked };
3426        self
3427    }
3428
3429    /// How this scan numbers an address, for one counted in addresses.
3430    ///
3431    /// A sweep sets this so a strategy that has earned a verdict for an address
3432    /// can settle it without knowing where in the plan it sits; see
3433    /// [`ScanContext::settle_address`].
3434    ///
3435    /// A port scan leaves it alone. It numbers address-and-port pairs on its
3436    /// target stream, so the discovery strategies in its liveness pass settle
3437    /// nothing, and the port plan's watermark does not advance over probes
3438    /// nobody sent.
3439    pub fn counting(mut self, positions: Positions) -> Self {
3440        self.positions = positions;
3441        self
3442    }
3443
3444    /// The seed of the order this scan asks its targets in.
3445    ///
3446    /// With a seed, the scan walks a permutation of the whole index space, so a
3447    /// sweep of a range does not have the address-order shape correlating
3448    /// sensors look for. See [`Permutation`](crate::model::order::Permutation).
3449    ///
3450    /// Left unset, the session draws its own seed when built, so the
3451    /// dispatcher's streams and the sweeps that hold their own first attempts
3452    /// all walk one order.
3453    ///
3454    /// Pass [`None`] for plan order, shuffled within a batch, which is the
3455    /// fallback for a plan that cannot be addressed by position. A sitting
3456    /// continuing a journal that recorded no seed must pass it, since its
3457    /// checkpoint counts along the plan.
3458    ///
3459    /// A caller journalling their scan should pass the journal's seed, so a
3460    /// resumed sitting continues in the first one's order, as
3461    /// [`scan_with_journal`](crate::scanner::scan_with_journal) does.
3462    pub fn ordering(mut self, seed: Option<u64>) -> Self {
3463        self.order = match seed {
3464            Some(seed) => Order::Seeded(seed),
3465            None => Order::Planned,
3466        };
3467        self
3468    }
3469
3470    /// How many targets the plan holds, and which [`Stage`] does that work.
3471    ///
3472    /// This is the denominator [`Progress::fraction`] divides into while that
3473    /// stage is running, so it has to be counted in the same unit the stage
3474    /// settles in: addresses for a sweep, address-and-port pairs for a port
3475    /// scan. [`Positions::total`](crate::model::ip::set::Positions::total) and
3476    /// [`TargetIndex::total`](crate::model::target::TargetIndex::total) are
3477    /// those two counts, and each has a companion that says whether it covered
3478    /// the whole plan.
3479    ///
3480    /// The stage matters in a scan with more than one: a port scan's liveness
3481    /// pass measured against address-and-port pairs would read nought percent
3482    /// throughout.
3483    ///
3484    /// Left unset, a consumer gets only a running count of what has settled,
3485    /// which is all an uncountable plan can offer.
3486    pub fn planning(mut self, stage: Stage, total: Option<u64>) -> Self {
3487        self.plan_stage = stage;
3488        self.planned = total;
3489        self
3490    }
3491
3492    /// The stages this scan expects to run, in the order it will run them.
3493    ///
3494    /// What [`Progress::overall`] measures a whole run against. Pass a
3495    /// superset: a listed stage that is skipped moves the figure forward over
3496    /// it, while an unlisted stage that runs leaves the figure still until the
3497    /// next listed one.
3498    ///
3499    /// [`discover`](crate::scanner::discover) and [`scan`](crate::scanner::scan)
3500    /// derive this from their settings. A caller orchestrating their own scan
3501    /// lists the stages they mean to run, or reads progress one stage at a time.
3502    pub fn staging(mut self, stages: Vec<Stage>) -> Self {
3503        self.staging = stages;
3504        self
3505    }
3506
3507    /// The corpus the detection phase runs, the shipped one unless set otherwise.
3508    ///
3509    /// [`scan`](crate::scanner::scan) sets the corpus it was given here; a caller
3510    /// orchestrating their own scan sets it directly so their detections run in it.
3511    pub fn detections(mut self, detections: crate::detect::Detections) -> Self {
3512        self.detections = detections;
3513        self
3514    }
3515
3516    /// The wall-clock budget each host gets before the scan leaves it.
3517    ///
3518    /// A caller orchestrating their own scan sets this to have the same bound
3519    /// [`scan`](crate::scanner::scan) applies from
3520    /// [`ZondConfig::host_timeout`](crate::config::ZondConfig::host_timeout).
3521    /// Every strategy that probes a host reads it through
3522    /// [`ScanContext::host_expired`].
3523    pub fn host_timeout(mut self, budget: Option<Duration>) -> Self {
3524        self.host_timeout = budget;
3525        self
3526    }
3527
3528    /// The wall-clock budget the whole scan gets before it winds down.
3529    ///
3530    /// Starts when [`build`](Self::build) is called, and reaches every strategy
3531    /// through the [`ScanHandle`] they already read. See
3532    /// [`ZondConfig::scan_timeout`](crate::config::ZondConfig::scan_timeout).
3533    pub fn scan_timeout(mut self, budget: Option<Duration>) -> Self {
3534        self.scan_timeout = budget;
3535        self
3536    }
3537
3538    /// The shortest gap the scan keeps between two probes aimed at one host.
3539    ///
3540    /// A caller orchestrating their own scan sets this to have the same spacing
3541    /// [`scan`](crate::scanner::scan) applies from
3542    /// [`ZondConfig::host_probe_interval`](crate::config::ZondConfig::host_probe_interval).
3543    /// Every pass that sends claims its slots through
3544    /// [`ScanContext::claim_probe`], which says what being turned away means
3545    /// for a probe.
3546    ///
3547    /// `None` is no gap. `Some(Duration::MAX)` is the longest gap there is,
3548    /// one probe per host for the rest of the scan, not "no limit"; see the
3549    /// config field.
3550    pub fn host_probe_interval(mut self, minimum: Option<Duration>) -> Self {
3551        self.host_probe_interval = minimum;
3552        self
3553    }
3554
3555    /// The shortest gap the scan keeps between any two probes it sends,
3556    /// whatever host each is aimed at.
3557    ///
3558    /// A caller orchestrating their own scan sets this to have the same spacing
3559    /// [`scan`](crate::scanner::scan) applies from
3560    /// [`ZondConfig::probe_interval`](crate::config::ZondConfig::probe_interval).
3561    /// Claimed through [`ScanContext::claim_probe`] alongside the per-host gap,
3562    /// on the same terms.
3563    pub fn probe_interval(mut self, minimum: Option<Duration>) -> Self {
3564        self.probe_interval = minimum;
3565        self
3566    }
3567
3568    /// The source addresses the connections this scan opens are forced to, one
3569    /// per family.
3570    ///
3571    /// A caller orchestrating their own scan sets this to have the same pinning
3572    /// [`scan`](crate::scanner::scan) applies from
3573    /// [`ZondConfig::send_source`](crate::config::ZondConfig::send_source):
3574    /// every connection to a routed target, from the connect scan or the
3575    /// service pass, leaves from the forced source and its interface, as the
3576    /// raw probes do.
3577    pub fn send_source(mut self, sources: Vec<IpAddr>) -> Self {
3578        self.send_source = sources;
3579        self
3580    }
3581
3582    /// The TCP ports this scan only connects to and listens on, sending
3583    /// nothing.
3584    ///
3585    /// Left unset, the printers' ports,
3586    /// [`RAW_PRINT_PORTS`](crate::config::RAW_PRINT_PORTS), as
3587    /// [`scan`](crate::scanner::scan) uses by default. A caller
3588    /// orchestrating their own scan sets this to what
3589    /// [`ZondConfig::listen_only_ports`](crate::config::ZondConfig::listen_only_ports)
3590    /// says, and an empty set probes every port alike.
3591    pub fn listening_only_to(mut self, ports: BTreeSet<u16>) -> Self {
3592        self.listen_only = Some(ports);
3593        self
3594    }
3595
3596    /// The ports a sitting continuing a job sends nothing to beyond those the
3597    /// job's plan is numbered without; see [`ScanContext::may_ask`].
3598    #[cfg(feature = "journal-format")]
3599    pub(crate) fn withholding_ports(mut self, ports: crate::model::port::PortSet) -> Self {
3600        self.withheld_ports = ports;
3601        self
3602    }
3603
3604    /// Opens the session and the context.
3605    ///
3606    /// The scan's own clock starts here, so building late still gets the full
3607    /// budget.
3608    pub fn build(self) -> (ScanSession, ScanContext) {
3609        let store = Arc::new(DashMap::new());
3610        let handle = ScanHandle::bounded(self.scan_timeout);
3611        let (events_tx, rx) = broadcast::channel(ScanEvents::CAPACITY);
3612        // Counted along the dispatcher's walk where there is one (a seed and a
3613        // plan it can number whole). The two must agree, or every answer waits
3614        // above the watermark. Without a plan the dispatcher names the walk
3615        // when it starts; see `Settlements::walk_along`.
3616        let order_seed = match self.order {
3617            Order::Drawn => Some(rand::random()),
3618            Order::Seeded(seed) => Some(seed),
3619            Order::Planned => None,
3620        };
3621        let walk = order_seed
3622            .zip(self.planned)
3623            .map(|(seed, total)| crate::model::order::Permutation::new(seed, total));
3624        let settlements = Arc::new(Settlements::walking(&self.settled, walk));
3625        let stages = Arc::new(Stages::new(self.staging));
3626
3627        let session = ScanSession {
3628            store: HostStore::new(store.clone()),
3629            events: ScanEvents { rx },
3630            handle: handle.clone(),
3631            progress: Progress::new(
3632                settlements.clone(),
3633                self.planned,
3634                self.plan_stage,
3635                stages.clone(),
3636            ),
3637        };
3638
3639        let ctx = ScanContext {
3640            handle,
3641            store,
3642            events_tx,
3643            failures: Arc::new(FailureLog::default()),
3644            refusals: Arc::new(RefusalLog::default()),
3645            probe_stats: Arc::new(ProbeStatsLog::default()),
3646            unroutable: Arc::new(UnroutableLog::default()),
3647            refused_by_route: Arc::new(UnroutableLog::default()),
3648            withheld_neighbours: Arc::new(UnroutableLog::default()),
3649            timed_out: Arc::new(TimedOutLog::default()),
3650            passes_cut: Arc::new(PassLog::default()),
3651            icmp_rate_limited: Arc::new(RateLimitedLog::default()),
3652            reached_by_connect: Arc::new(ConnectLog::default()),
3653            silent: Arc::new(SilenceLog::default()),
3654            undecided: Arc::new(SilenceLog::default()),
3655            unreached: Arc::new(AtomicU64::new(0)),
3656            unheard_probes: Arc::new(AtomicU64::new(0)),
3657            verdicts_pending: Arc::new(AtomicBool::new(false)),
3658            sitting: Arc::new(Sitting::default()),
3659            plan_stage: self.plan_stage,
3660            clocks: Arc::new(HostClocks {
3661                budget: self.host_timeout,
3662                started: DashMap::new(),
3663            }),
3664            spacing: Arc::new(ProbeSpacing {
3665                per_host: self.host_probe_interval,
3666                scan_wide: self.probe_interval,
3667                ..ProbeSpacing::default()
3668            }),
3669            zones: Arc::new(OnceLock::new()),
3670            capture_links: Arc::new(OnceLock::new()),
3671            numbering: Arc::new(OnceLock::new()),
3672            swept_links: Arc::new(SweptLinks::default()),
3673            attachments: Arc::new(Attachments::default()),
3674            hardware: Arc::new(WithheldHardware::read(
3675                &self.exclusions,
3676                self.neighbours.unwrap_or_else(|| {
3677                    if self.exclusions.is_empty() {
3678                        return Vec::new();
3679                    }
3680                    crate::system::neighbor_cache::neighbour_table()
3681                }),
3682            )),
3683            exclusions: Arc::new(self.exclusions),
3684            changed: Arc::new(ChangedHosts::default()),
3685            stages,
3686            settlements,
3687            positions: Arc::new(self.positions),
3688            order_seed,
3689            responses: Arc::new(Responses::default()),
3690            tapes: Arc::new(Tapes::default()),
3691            finished: Arc::new(self.finished),
3692            detections: self.detections,
3693            forced: Arc::new(crate::transport::dial::ForcedSources::new(
3694                &self.send_source,
3695            )),
3696            listen_only: Arc::new(
3697                self.listen_only
3698                    .unwrap_or_else(|| crate::config::RAW_PRINT_PORTS.iter().copied().collect()),
3699            ),
3700            withheld_ports: Arc::new(self.withheld_ports),
3701            target_names: Arc::new(
3702                self.target_names
3703                    .into_iter()
3704                    .map(|(ip, name)| (ip, Arc::from(name)))
3705                    .collect(),
3706            ),
3707        };
3708
3709        (session, ctx)
3710    }
3711}
3712
3713impl ScanSession {
3714    /// A session and the context the strategies behind it write into, with
3715    /// nothing excluded, nothing resumed, no address numbering, and a walk
3716    /// order of its own; see [`SessionBuilder::ordering`].
3717    ///
3718    /// [`discover`](crate::scanner::discover) and [`scan`](crate::scanner::scan)
3719    /// build their own session. A caller orchestrating their own scan calls
3720    /// this first, since every strategy in [`strategy`](crate::scanner::strategy)
3721    /// is constructed with a [`ScanContext`].
3722    ///
3723    /// [`builder`](Self::builder) takes further settings.
3724    pub fn new() -> (Self, ScanContext) {
3725        Self::builder().build()
3726    }
3727
3728    /// A session with exclusions, a resume point or an address numbering.
3729    ///
3730    /// See [`SessionBuilder`].
3731    pub fn builder() -> SessionBuilder {
3732        SessionBuilder::default()
3733    }
3734}
3735
3736// ╔════════════════════════════════════════════╗
3737// ║ ████████╗███████╗███████╗████████╗███████╗ ║
3738// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
3739// ║    ██║   █████╗  ███████╗   ██║   ███████╗ ║
3740// ║    ██║   ██╔══╝  ╚════██║   ██║   ╚════██║ ║
3741// ║    ██║   ███████╗███████║   ██║   ███████║ ║
3742// ║    ╚═╝   ╚══════╝╚══════╝   ╚═╝   ╚══════╝ ║
3743// ╚════════════════════════════════════════════╝
3744
3745#[cfg(test)]
3746mod tests {
3747    use super::*;
3748    use crate::model::host::{EvidenceSource, Hop, HostStatus, StatusProtocol, StatusReason};
3749
3750    /// A whole run reads as one figure that only grows.
3751    #[test]
3752    fn a_whole_run_reads_as_one_figure_rather_than_one_per_stage() {
3753        let (session, ctx) = ScanSession::builder()
3754            .planning(Stage::Ports, Some(4))
3755            .staging(vec![Stage::Ports, Stage::Services, Stage::Detections])
3756            .build();
3757
3758        ctx.enter_stage(Stage::Ports, None);
3759        ctx.record_outcome(Outcome::Answered { position: 0 });
3760        ctx.record_outcome(Outcome::Answered { position: 1 });
3761
3762        // Half of the first stage of three, which is a sixth of the run.
3763        let (done, total) = session.progress().overall().expect("a staged run");
3764        assert_eq!(
3765            done * 6,
3766            total,
3767            "half of one stage in three: {done}/{total}"
3768        );
3769
3770        ctx.enter_stage(Stage::Services, Some(2));
3771        ctx.stage_advanced();
3772
3773        // One stage behind it and half way through the second: half the run.
3774        let (done, total) = session.progress().overall().expect("a staged run");
3775        assert_eq!(done * 2, total, "half the run: {done}/{total}");
3776    }
3777
3778    /// Across a whole scan the figure only grows, and is whole only at the
3779    /// end. Walks a port scan's stages: a liveness pass, a port phase whose
3780    /// plan is mostly silent hosts, service detection once for TCP and again
3781    /// for UDP, the detections, and the later passes.
3782    #[test]
3783    fn a_scans_figure_only_grows_and_is_whole_only_at_its_end() {
3784        let (session, ctx) = ScanSession::builder()
3785            .planning(Stage::Ports, Some(1_000))
3786            .staging(vec![
3787                Stage::Discovery,
3788                Stage::Ports,
3789                Stage::Services,
3790                Stage::Detections,
3791                Stage::Os,
3792                Stage::Traceroute,
3793                Stage::Filters,
3794                Stage::IpProtocols,
3795            ])
3796            .build();
3797        let progress = session.progress().clone();
3798        let mut readings: Vec<(&str, (u64, u64))> = Vec::new();
3799        let mut read = |what| readings.push((what, progress.overall().expect("staged")));
3800
3801        ctx.enter_stage(Stage::Discovery, None);
3802        read("liveness");
3803        ctx.enter_stage(Stage::Ports, None);
3804        for position in 10..1_000 {
3805            ctx.record_outcome(Outcome::Skipped { position });
3806        }
3807        read("silent hosts passed over");
3808        let passed_over = progress.fraction().expect("the plan's own stage");
3809        for position in 0..10 {
3810            ctx.record_outcome(Outcome::Answered { position });
3811        }
3812        read("ports probed");
3813        ctx.enter_stage(Stage::Services, Some(4));
3814        for _ in 0..4 {
3815            ctx.stage_advanced();
3816        }
3817        read("tcp services");
3818        ctx.enter_stage(Stage::Services, Some(4));
3819        read("udp services begun");
3820        for _ in 0..4 {
3821            ctx.stage_advanced();
3822        }
3823        read("udp services");
3824        for stage in [
3825            Stage::Detections,
3826            Stage::Os,
3827            Stage::Traceroute,
3828            Stage::Filters,
3829            Stage::IpProtocols,
3830        ] {
3831            ctx.enter_stage(stage, None);
3832            read("a later pass");
3833        }
3834        ctx.enter_stage(Stage::Finishing, None);
3835        read("finishing");
3836
3837        let share = |(done, total): (u64, u64)| done as f64 / total as f64;
3838        assert_eq!(
3839            passed_over, 0.0,
3840            "silent hosts passed over read as ports probed"
3841        );
3842        for pair in readings.windows(2) {
3843            assert!(
3844                share(pair[1].1) >= share(pair[0].1),
3845                "the figure stepped back from {:?} to {:?}",
3846                pair[0],
3847                pair[1]
3848            );
3849        }
3850        let (last, others) = readings.split_last().expect("readings");
3851        assert_eq!(share(last.1), 1.0, "a finished scan reads whole");
3852        for (what, reading) in others {
3853            assert!(share(*reading) < 1.0, "{what} read whole: {reading:?}");
3854        }
3855    }
3856
3857    /// A stage that turned out to have nothing to do is stepped over.
3858    ///
3859    /// The running order is a superset, and some stages never announce
3860    /// themselves.
3861    #[test]
3862    fn a_stage_with_nothing_to_do_is_stepped_over_rather_than_waited_for() {
3863        let (session, ctx) = ScanSession::builder()
3864            .staging(vec![
3865                Stage::Ports,
3866                Stage::Services,
3867                Stage::Detections,
3868                Stage::Os,
3869            ])
3870            .build();
3871
3872        ctx.enter_stage(Stage::Ports, Some(1));
3873        ctx.stage_advanced();
3874
3875        // Services and detections never announced themselves; the run is
3876        // still three stages on.
3877        ctx.enter_stage(Stage::Os, None);
3878
3879        let (done, total) = session.progress().overall().expect("a staged run");
3880        assert_eq!(done * 4, total * 3, "three stages of four: {done}/{total}");
3881    }
3882
3883    /// A session given no running order reports no whole-run figure.
3884    #[test]
3885    fn a_session_with_no_running_order_reports_no_whole_run_figure() {
3886        let (session, ctx) = ScanSession::new();
3887
3888        ctx.enter_stage(Stage::Services, Some(4));
3889        ctx.stage_advanced();
3890
3891        let progress = session.progress();
3892        assert_eq!(progress.overall(), None, "nothing said how many stages");
3893        assert_eq!(
3894            progress.counted(),
3895            Some((1, 4)),
3896            "the stage still answers for itself"
3897        );
3898    }
3899
3900    /// A stage that knows its own size answers for itself, ignoring the plan,
3901    /// which a port scan settles long before the detections end.
3902    #[test]
3903    fn a_stage_that_counted_itself_answers_for_itself() {
3904        let (session, ctx) = ScanSession::builder()
3905            .planning(Stage::Ports, Some(4))
3906            .build();
3907
3908        // The plan, settled in full.
3909        ctx.enter_stage(Stage::Ports, None);
3910        ctx.record_outcome(Outcome::Answered { position: 0 });
3911        ctx.record_outcome(Outcome::Answered { position: 1 });
3912        ctx.record_outcome(Outcome::Answered { position: 2 });
3913        ctx.record_outcome(Outcome::Answered { position: 3 });
3914        assert_eq!(
3915            session.progress().fraction(),
3916            Some(1.0),
3917            "the ports are done"
3918        );
3919
3920        ctx.enter_stage(Stage::Detections, Some(8));
3921        ctx.stage_advanced();
3922        ctx.stage_advanced();
3923
3924        let progress = session.progress();
3925        assert_eq!(progress.stage(), Stage::Detections);
3926        assert_eq!(progress.stage_done(), 2);
3927        assert_eq!(progress.stage_total(), Some(8));
3928        assert_eq!(
3929            progress.fraction(),
3930            Some(0.25),
3931            "a quarter through the detections, not finished with the scan"
3932        );
3933        assert_eq!(progress.settled(), 4, "the plan is still settled in full");
3934    }
3935
3936    /// An unsized stage other than the plan's own reports no fraction, as a
3937    /// port scan's liveness pass settles none of the plan's pairs.
3938    #[test]
3939    fn an_unsized_stage_that_is_not_the_plans_own_reports_nothing() {
3940        let (session, ctx) = ScanSession::builder()
3941            .planning(Stage::Ports, Some(1_000))
3942            .build();
3943
3944        ctx.enter_stage(Stage::Discovery, None);
3945        let progress = session.progress();
3946        assert_eq!(progress.stage(), Stage::Discovery);
3947        assert_eq!(
3948            progress.fraction(),
3949            None,
3950            "a liveness pass is not nought percent of a port plan"
3951        );
3952
3953        ctx.enter_stage(Stage::Ports, None);
3954        assert_eq!(
3955            session.progress().fraction(),
3956            Some(0.0),
3957            "the stage the plan was drawn for reads from the plan"
3958        );
3959    }
3960
3961    /// Entering the stage that is already current adds to it, as service
3962    /// detection does once per protocol.
3963    #[test]
3964    fn re_entering_a_stage_adds_to_it_rather_than_starting_it_over() {
3965        let (mut session, ctx) = ScanSession::new();
3966
3967        ctx.enter_stage(Stage::Services, Some(3));
3968        ctx.stage_advanced();
3969        ctx.enter_stage(Stage::Services, Some(2));
3970
3971        let progress = session.progress().clone();
3972        assert_eq!(progress.stage_total(), Some(5), "both runs' ports");
3973        assert_eq!(progress.stage_done(), 1, "and the one already finished");
3974
3975        // The stage did not change the second time.
3976        let mut announced = 0;
3977        while let Some(event) = session.events().try_recv() {
3978            if matches!(event, ScanEvent::StageChanged { .. }) {
3979                announced += 1;
3980            }
3981        }
3982        assert_eq!(announced, 1, "one stage, announced once");
3983    }
3984
3985    /// Every stage has a place in the list, and the list is in running order.
3986    #[test]
3987    fn the_list_of_stages_holds_every_one_of_them_in_running_order() {
3988        let codes: Vec<u8> = Stage::ALL.iter().map(|stage| stage.code()).collect();
3989        let mut sorted = codes.clone();
3990        sorted.sort_unstable();
3991        sorted.dedup();
3992
3993        assert_eq!(codes, sorted, "the stages are listed in the order they run");
3994        assert_eq!(
3995            codes.len(),
3996            Stage::ALL.len(),
3997            "a stage is listed once and no stage twice"
3998        );
3999
4000        for &stage in Stage::ALL {
4001            assert_eq!(
4002                Stage::from_code(stage.code()),
4003                stage,
4004                "{stage} does not survive its own code"
4005            );
4006        }
4007    }
4008
4009    /// Moving to a stage announces it, naming the stage moved to.
4010    #[test]
4011    fn a_stage_announces_itself_as_it_begins() {
4012        let (mut session, ctx) = ScanSession::new();
4013
4014        ctx.enter_stage(Stage::Os, None);
4015
4016        let Some(ScanEvent::StageChanged { stage }) = session.events().try_recv() else {
4017            panic!("entering a stage announces it");
4018        };
4019        assert_eq!(stage, Stage::Os);
4020    }
4021
4022    /// A scan whose plan was never counted still counts what it settles.
4023    ///
4024    /// A running total with nothing to divide it into, as for a listener or a
4025    /// sweep of an IPv6 range too wide to number.
4026    #[test]
4027    fn an_uncounted_plan_settles_targets_but_reports_no_fraction() {
4028        let (session, ctx) = ScanSession::new();
4029
4030        ctx.record_outcome(Outcome::Answered { position: 0 });
4031        ctx.record_outcome(Outcome::Exhausted { position: 1 });
4032
4033        let progress = session.progress();
4034        assert_eq!(progress.settled(), 2, "both targets settled");
4035        assert_eq!(
4036            progress.planned(),
4037            None,
4038            "nothing said how big the plan was"
4039        );
4040        assert_eq!(
4041            progress.fraction(),
4042            None,
4043            "so there is nothing to divide into"
4044        );
4045        assert_eq!(progress.remaining(), None);
4046    }
4047
4048    /// The fraction is settled against the plan, and both move as the scan does.
4049    #[test]
4050    fn settling_targets_advances_the_fraction() {
4051        let (session, ctx) = ScanSession::builder()
4052            .planning(Stage::Discovery, Some(4))
4053            .build();
4054
4055        assert_eq!(
4056            session.progress().fraction(),
4057            Some(0.0),
4058            "nothing settled yet"
4059        );
4060
4061        ctx.record_outcome(Outcome::Answered { position: 0 });
4062        ctx.record_outcome(Outcome::Exhausted { position: 1 });
4063
4064        let progress = session.progress();
4065        assert_eq!(progress.settled(), 2);
4066        assert_eq!(progress.remaining(), Some(2));
4067        let fraction = progress.fraction().expect("a counted plan has a fraction");
4068        assert!(
4069            (fraction - 0.5).abs() < f64::EPSILON,
4070            "two of four settled is half the plan, got {fraction}"
4071        );
4072    }
4073
4074    /// An outcome that settles nothing moves the scan no further through its
4075    /// plan.
4076    ///
4077    /// `Unasked` is what a scan that stopped early leaves behind, and the bar
4078    /// stays short.
4079    #[test]
4080    fn an_unsettled_outcome_does_not_advance_the_plan() {
4081        let (session, ctx) = ScanSession::builder()
4082            .planning(Stage::Discovery, Some(2))
4083            .build();
4084
4085        ctx.record_outcome(Outcome::Answered { position: 0 });
4086        ctx.record_many_outcomes(Outcome::Unasked, 1);
4087
4088        let progress = session.progress();
4089        assert_eq!(progress.settled(), 1, "only the answered target settled");
4090        assert_eq!(
4091            progress.remaining(),
4092            Some(1),
4093            "the unasked one is still owed"
4094        );
4095    }
4096
4097    /// A resumed sitting measures against the whole job, since the numerator
4098    /// carries what earlier sittings settled.
4099    #[test]
4100    fn a_resumed_sitting_starts_part_way_through_the_plan() {
4101        let earlier = crate::journal::cursor::Checkpoint::new(6, []);
4102        let (session, ctx) = ScanSession::builder()
4103            .resuming(&earlier)
4104            .planning(Stage::Discovery, Some(8))
4105            .build();
4106
4107        assert_eq!(
4108            session.progress().settled(),
4109            6,
4110            "what the earlier sitting settled is already covered"
4111        );
4112
4113        ctx.record_outcome(Outcome::Answered { position: 6 });
4114
4115        let fraction = session
4116            .progress()
4117            .fraction()
4118            .expect("a counted plan has a fraction");
4119        assert!(
4120            (fraction - 0.875).abs() < f64::EPSILON,
4121            "seven of eight, got {fraction}"
4122        );
4123    }
4124
4125    /// An empty plan has nothing left to do, and a plan cannot be overshot.
4126    #[test]
4127    fn a_fraction_saturates_rather_than_passing_one() {
4128        let (empty, _ctx) = ScanSession::builder()
4129            .planning(Stage::Discovery, Some(0))
4130            .build();
4131        assert_eq!(
4132            empty.progress().fraction(),
4133            Some(1.0),
4134            "an empty plan is complete"
4135        );
4136
4137        let (session, ctx) = ScanSession::builder()
4138            .planning(Stage::Discovery, Some(1))
4139            .build();
4140        ctx.record_outcome(Outcome::Answered { position: 0 });
4141        ctx.record_outcome(Outcome::Answered { position: 1 });
4142        assert_eq!(
4143            session.progress().fraction(),
4144            Some(1.0),
4145            "more settled than planned still reads as done"
4146        );
4147        assert_eq!(session.progress().remaining(), Some(0));
4148    }
4149
4150    /// A reply from an excluded address leaves no host, emits no event, and
4151    /// `write_host` returns `false`.
4152    ///
4153    /// The `edit` closure panics, so the test also fails if the closure runs
4154    /// and its result is discarded, which would let a scanner's bookkeeping
4155    /// run for an excluded host.
4156    #[test]
4157    fn an_excluded_address_reaches_neither_the_store_nor_the_stream() {
4158        let excluded: IpAddr = "198.51.100.7".parse().expect("literal");
4159        let allowed: IpAddr = "203.0.113.7".parse().expect("literal");
4160
4161        let mut ips = crate::model::ip::set::IpSet::new();
4162        ips.insert_range("198.51.100.0/24".parse().expect("a valid range"));
4163        let (mut session, ctx) = ScanSession::builder()
4164            .excluding(Exclusions::new(ips))
4165            .build();
4166
4167        assert!(
4168            !ctx.write_host(excluded, |_| unreachable!(
4169                "an excluded address must not reach the caller's edit"
4170            )),
4171            "an excluded address is never reported as a new host"
4172        );
4173        assert!(ctx.write_host(allowed, |_| true));
4174
4175        assert_eq!(ctx.store.len(), 1);
4176        assert!(!ctx.store.contains_key(&ScopedIp::unscoped(excluded)));
4177
4178        // One announcement, for the allowed address.
4179        let ScanEvent::HostUpdated(announced) =
4180            session.events().try_recv().expect("the allowed host")
4181        else {
4182            panic!("expected a host update");
4183        };
4184        assert_eq!(announced, ScopedIp::unscoped(allowed));
4185        assert!(session.events().try_recv().is_none());
4186    }
4187
4188    /// `fe80::1` on two segments is two machines, and each keeps its own
4189    /// interface.
4190    #[test]
4191    fn two_link_locals_on_different_segments_are_two_hosts() {
4192        let shared: IpAddr = "fe80::1".parse().expect("literal");
4193        let (_session, ctx) = ScanSession::new();
4194
4195        ctx.write_host(ScopedIp::scoped(shared, Zone::new(1, "en0")), |host| {
4196            host.set_status(HostStatus::Up);
4197            true
4198        });
4199        ctx.write_host(ScopedIp::scoped(shared, Zone::new(2, "en1")), |host| {
4200            host.set_status(HostStatus::Up);
4201            true
4202        });
4203
4204        assert_eq!(ctx.store.len(), 2, "two segments, two machines");
4205
4206        // Each takes its link from the key it was created under.
4207        let mut zones: Vec<String> = ctx
4208            .store
4209            .iter()
4210            .filter_map(|entry| entry.value().zone().map(|zone| zone.name().to_owned()))
4211            .collect();
4212        zones.sort();
4213        assert_eq!(zones, ["en0", "en1"]);
4214    }
4215
4216    /// A port scan holds its link-local targets bare, so its verdicts arrive
4217    /// with no interface. They land on the host the sweep found on the
4218    /// interface the scan named.
4219    #[test]
4220    fn a_port_verdict_on_a_bare_link_local_lands_on_the_host_the_scan_named() {
4221        use crate::model::ip::range::Ipv6Range;
4222
4223        let address: IpAddr = "fe80::1".parse().expect("literal");
4224        let (_session, ctx) = ScanSession::new();
4225
4226        let mut zones = ZoneMap::new();
4227        let IpAddr::V6(v6) = address else {
4228            panic!("a v6 literal");
4229        };
4230        zones.insert(
4231            Ipv6Range::scoped(v6, v6, Some(1)).expect("a scoped range"),
4232            &[(1, "en0")],
4233        );
4234        ctx.learn_zones(zones);
4235
4236        ctx.write_host(ScopedIp::scoped(address, Zone::new(1, "en0")), |host| {
4237            host.set_status(HostStatus::Up);
4238            true
4239        });
4240        ctx.write_host(address, |host| {
4241            host.set_status(HostStatus::Up);
4242            true
4243        });
4244
4245        assert_eq!(ctx.store.len(), 1, "one machine, one record");
4246        assert!(
4247            ctx.read_host(address, |host| host.zone().is_some())
4248                .expect("the bare address reaches it too"),
4249            "and it is still the host on en0"
4250        );
4251    }
4252
4253    /// A global address is the same machine through whichever interface answered
4254    /// it, so the zone is dropped from the key and two sightings are one host.
4255    #[test]
4256    fn one_global_address_seen_on_two_interfaces_is_one_host() {
4257        let global: IpAddr = "2001:db8::1".parse().expect("literal");
4258        let (_session, ctx) = ScanSession::new();
4259
4260        ctx.write_host(ScopedIp::scoped(global, Zone::new(1, "en0")), |_| true);
4261        ctx.write_host(ScopedIp::scoped(global, Zone::new(2, "en1")), |_| true);
4262
4263        assert_eq!(ctx.store.len(), 1, "one address, one machine");
4264    }
4265
4266    /// A finding written back under a key read from the store lands on the
4267    /// same host, as every phase after discovery relies on.
4268    #[test]
4269    fn a_finding_written_back_under_a_key_from_the_store_lands_on_the_same_host() {
4270        let shared: IpAddr = "fe80::1".parse().expect("literal");
4271        let (_session, ctx) = ScanSession::new();
4272
4273        ctx.write_host(ScopedIp::scoped(shared, Zone::new(1, "en0")), |host| {
4274            host.set_status(HostStatus::Up);
4275            true
4276        });
4277
4278        for key in ctx.host_addresses() {
4279            ctx.write_host(key, |host| {
4280                host.add_reason(StatusReason::new(StatusProtocol::IcmpEcho, "echo answered"));
4281                true
4282            });
4283        }
4284
4285        assert_eq!(ctx.store.len(), 1, "the same host, enriched");
4286        assert_eq!(
4287            ctx.store
4288                .iter()
4289                .next()
4290                .expect("the host")
4291                .value()
4292                .reasons()
4293                .len(),
4294            1,
4295            "and the finding reached it"
4296        );
4297    }
4298
4299    #[test]
4300    fn a_failure_survives_a_consumer_that_never_listens() {
4301        let (session, ctx) = ScanSession::new();
4302        // A caller that never touches the event stream.
4303        drop(session);
4304
4305        ctx.record_failure(ScannerKind::Routed, "raw socket unavailable".into());
4306
4307        let failures = ctx.take_failures();
4308        assert_eq!(failures.len(), 1);
4309        assert_eq!(failures[0].scanner(), ScannerKind::Routed);
4310        assert_eq!(failures[0].reason(), "raw socket unavailable");
4311    }
4312
4313    #[test]
4314    fn a_failure_reaches_both_the_log_and_the_stream() {
4315        let (mut session, ctx) = ScanSession::new();
4316
4317        ctx.record_failure(ScannerKind::Local, "eth0: no address".into());
4318
4319        match session.events().try_recv() {
4320            Some(ScanEvent::ScannerFailed { scanner, reason }) => {
4321                assert_eq!(scanner, ScannerKind::Local);
4322                assert_eq!(reason, "eth0: no address");
4323            }
4324            other => panic!("expected a ScannerFailed event, got {other:?}"),
4325        }
4326        assert_eq!(ctx.take_failures().len(), 1);
4327    }
4328
4329    /// The snapshot leaves the log for the report.
4330    #[test]
4331    fn snapshotting_failures_leaves_them_for_the_report() {
4332        let (_session, ctx) = ScanSession::new();
4333        ctx.record_failure(ScannerKind::Local, "eth0: no address".into());
4334
4335        assert_eq!(ctx.failures_snapshot().len(), 1);
4336        assert_eq!(ctx.failures_snapshot().len(), 1, "reading is not taking");
4337        assert_eq!(ctx.take_failures().len(), 1, "and the report still gets it");
4338    }
4339
4340    /// A failure is logged as the strategy's report name and the reason, with
4341    /// nothing else on the line.
4342    #[test]
4343    fn a_failure_is_said_under_the_name_the_report_files_it_by() {
4344        let (_session, ctx) = ScanSession::new();
4345        let lines = crate::logging::logged(|| {
4346            ctx.record_failure(ScannerKind::SynPort, "the capture would not open".into());
4347        });
4348
4349        let said: Vec<&str> = lines.iter().map(|line| line.message.as_str()).collect();
4350        assert_eq!(said, ["syn_port failed: the capture would not open"]);
4351    }
4352
4353    #[test]
4354    fn taking_failures_empties_the_log() {
4355        let (_session, ctx) = ScanSession::new();
4356        ctx.record_failure(ScannerKind::Connect, "refused".into());
4357
4358        assert_eq!(ctx.take_failures().len(), 1);
4359        // A context outliving its phase must not hand the same failure to a
4360        // second report.
4361        assert!(ctx.take_failures().is_empty());
4362    }
4363
4364    #[test]
4365    fn failures_from_every_clone_land_in_one_log() {
4366        let (_session, ctx) = ScanSession::new();
4367        let clone = ctx.clone();
4368
4369        ctx.record_failure(ScannerKind::Local, "eth0".into());
4370        clone.record_failure(ScannerKind::Routed, "gateway".into());
4371
4372        // Each strategy gets its own clone; the report is built from one.
4373        assert_eq!(ctx.take_failures().len(), 2);
4374    }
4375
4376    /// A session built to continue an earlier sitting starts from its progress.
4377    ///
4378    /// Otherwise its first checkpoint would roll the cursor back to its own
4379    /// sitting's work.
4380    #[test]
4381    fn a_resuming_session_starts_from_the_earlier_cursor() {
4382        use crate::journal::cursor::Checkpoint;
4383
4384        let settled = Checkpoint {
4385            watermark: 12,
4386            settled_above: vec![14],
4387            walked: None,
4388        };
4389        let (_session, ctx) = ScanSession::builder()
4390            .excluding(Exclusions::none())
4391            .resuming(&settled)
4392            .build();
4393
4394        assert_eq!(ctx.settlements().settled_count(), 13);
4395        assert_eq!(ctx.settlements().checkpoint(), settled);
4396
4397        // A fresh session has nothing inherited.
4398        let (_session, fresh) = ScanSession::new();
4399        assert_eq!(fresh.settlements().settled_count(), 0);
4400    }
4401
4402    /// A session left unordered draws its own seed; one told there is no seed
4403    /// walks the plan.
4404    #[test]
4405    fn a_session_left_to_itself_draws_a_seed_and_one_told_otherwise_does_not() {
4406        let (_session, left) = ScanSession::new();
4407        let (_session, other) = ScanSession::builder().build();
4408        let (_session, told) = ScanSession::builder().ordering(None).build();
4409        let (_session, given) = ScanSession::builder().ordering(Some(0x5EED)).build();
4410
4411        assert!(left.order_seed.is_some(), "no seed drawn");
4412        assert_ne!(left.order_seed, other.order_seed, "two sessions, one order");
4413        assert_eq!(told.order_seed, None);
4414        assert_eq!(given.order_seed, Some(0x5EED));
4415    }
4416
4417    /// A scan walked in a seeded order keeps a checkpoint the size of what is
4418    /// in flight, whatever the size of the plan.
4419    ///
4420    /// A seeded scan's answers arrive scattered across the plan. Counted in
4421    /// plan order, the watermark would stay near zero with half the plan
4422    /// waiting above it at the halfway mark. Counted along the walk, with each
4423    /// batch shuffled as the dispatcher does, what waits stays under a batch.
4424    #[test]
4425    fn a_walked_scan_checkpoints_what_is_in_flight_rather_than_what_it_settled() {
4426        use crate::journal::settle::Outcome;
4427        use crate::model::order::Permutation;
4428        use rand::seq::SliceRandom;
4429
4430        const PLAN: u64 = 1 << 16;
4431        const BATCH: usize = 256;
4432        let (_session, ctx) = ScanSession::builder()
4433            .planning(Stage::Ports, Some(PLAN))
4434            .ordering(Some(0x5EED))
4435            .build();
4436
4437        let walk: Vec<u64> = Permutation::new(0x5EED, PLAN).iter().collect();
4438        let mut rng = rand::rng();
4439        let mut most_waiting = 0;
4440        for batch in walk[..walk.len() / 2].chunks(BATCH) {
4441            let mut batch = batch.to_vec();
4442            batch.shuffle(&mut rng);
4443            for position in batch {
4444                ctx.record_outcome(Outcome::Answered { position });
4445            }
4446            most_waiting = most_waiting.max(ctx.settlements().checkpoint().settled_above.len());
4447        }
4448
4449        assert_eq!(ctx.settlements().settled_count(), PLAN / 2);
4450        assert!(
4451            most_waiting < BATCH,
4452            "{most_waiting} settled positions waited in the checkpoint at once, \
4453             where a batch is {BATCH}"
4454        );
4455    }
4456
4457    /// An edit that asks not to be announced still marks the host changed for
4458    /// the journal, as when the echo probe adds evidence to a host already
4459    /// found.
4460    #[test]
4461    fn a_write_nobody_needs_announcing_is_still_a_write() {
4462        let ip: IpAddr = "192.0.2.1".parse().expect("an address");
4463        let (mut session, ctx) = ScanSession::new();
4464
4465        // Found, announced, and written down.
4466        ctx.update_host(ip, |host| host.set_status(HostStatus::Up));
4467        assert_eq!(ctx.take_changed_hosts().len(), 1);
4468        assert!(
4469            session.events().try_recv().is_some(),
4470            "a new host is announced"
4471        );
4472
4473        // Enriched: worth writing, not worth announcing.
4474        ctx.write_host(ip, |host| {
4475            host.record_evidence(
4476                HostStatus::Up,
4477                StatusReason::new(StatusProtocol::IcmpEcho, "echo reply to an OS probe"),
4478            );
4479            false
4480        });
4481
4482        let changed = ctx.take_changed_hosts();
4483        assert_eq!(
4484            changed.len(),
4485            1,
4486            "the record moved, so a journal has something to write"
4487        );
4488        assert!(
4489            changed[0]
4490                .reasons()
4491                .iter()
4492                .any(|reason| reason.protocol == StatusProtocol::IcmpEcho),
4493            "and what it writes is what the pass learned"
4494        );
4495        assert!(
4496            session.events().try_recv().is_none(),
4497            "a host already announced is not announced again"
4498        );
4499    }
4500
4501    /// A stream nobody reads until the scan is over: the store holds
4502    /// everything, and what the buffer could not keep is counted in
4503    /// `EventsDropped`.
4504    #[test]
4505    fn a_stream_nobody_reads_drops_the_oldest_and_says_how_many() {
4506        let flooded: IpAddr = "192.0.2.1".parse().expect("literal");
4507        let last: IpAddr = "192.0.2.2".parse().expect("literal");
4508        let (mut session, ctx) = ScanSession::new();
4509
4510        let overflow = 64;
4511        let sent = ScanEvents::CAPACITY + overflow;
4512        for _ in 0..sent - 1 {
4513            ctx.update_host(flooded, |host| host.set_status(HostStatus::Up));
4514        }
4515        ctx.update_host(last, |host| host.set_status(HostStatus::Up));
4516
4517        assert_eq!(
4518            ctx.store.len(),
4519            2,
4520            "a full event buffer does not stop the scan writing findings"
4521        );
4522
4523        let mut dropped = 0u64;
4524        let mut delivered = Vec::new();
4525        while let Some(event) = session.events().try_recv() {
4526            match event {
4527                ScanEvent::EventsDropped { count } => dropped += count,
4528                ScanEvent::HostUpdated(ip) => delivered.push(ip),
4529                other => panic!("unexpected event {other:?}"),
4530            }
4531        }
4532
4533        assert_eq!(
4534            delivered.len(),
4535            ScanEvents::CAPACITY,
4536            "the stream holds its stated capacity and no more"
4537        );
4538        assert_eq!(
4539            dropped as usize + delivered.len(),
4540            sent,
4541            "every event is either delivered or declared missing"
4542        );
4543        assert_eq!(
4544            delivered.last(),
4545            Some(&ScopedIp::unscoped(last)),
4546            "the newest event survives, which is what drop-oldest means"
4547        );
4548    }
4549
4550    /// A scan with no budget answers `false` for every host, however many times
4551    /// it is asked, and files nothing.
4552    #[test]
4553    fn a_scan_with_no_host_budget_leaves_no_host() {
4554        let (_session, ctx) = ScanSession::new();
4555        let ip: IpAddr = "192.0.2.1".parse().expect("an address");
4556
4557        assert!(!ctx.host_expired(ip));
4558        assert!(!ctx.host_expired(ip));
4559        assert!(ctx.take_timed_out().is_empty());
4560    }
4561
4562    /// A spent budget is answered for every pass that asks, and the address is
4563    /// filed once however many of them do.
4564    #[test]
4565    fn a_spent_host_budget_is_filed_once() {
4566        let (_session, ctx) = ScanSession::builder()
4567            .host_timeout(Some(Duration::ZERO))
4568            .build();
4569        let ip: IpAddr = "192.0.2.1".parse().expect("an address");
4570
4571        assert!(ctx.host_expired(ip));
4572        assert!(ctx.host_expired(ip));
4573        assert_eq!(ctx.take_timed_out(), vec![ip]);
4574    }
4575
4576    /// A scan with no gap set grants every claim and never touches the map.
4577    #[test]
4578    fn a_scan_with_no_gap_never_holds_a_probe() {
4579        let (_session, ctx) = ScanSession::new();
4580        let ip: IpAddr = "192.0.2.1".parse().expect("an address");
4581        let now = Instant::now();
4582
4583        assert!(ctx.spacing.claim_with(ip, || now).is_ok());
4584        assert!(
4585            ctx.spacing.claim_with(ip, || now).is_ok(),
4586            "a granted claim holds nothing back while there is no gap to hold it against"
4587        );
4588        assert!(ctx.probe_ready_at(ip, now).is_none());
4589        assert!(ctx.spacing.last_at_host.is_empty());
4590    }
4591
4592    /// The longest gap a caller can write holds a host's next probe past the
4593    /// end of any scan without panicking, though `Duration::MAX` after the last
4594    /// probe is past what a clock can count to.
4595    #[test]
4596    fn the_longest_gap_holds_a_host_rather_than_panicking() {
4597        let (_session, ctx) = ScanSession::builder()
4598            .host_probe_interval(Some(Duration::MAX))
4599            .build();
4600        let ip: IpAddr = "192.0.2.1".parse().expect("an address");
4601        let now = Instant::now();
4602
4603        let _ = ctx.spacing.claim_with(ip, || now).expect("the first probe");
4604        let ready = ctx
4605            .spacing
4606            .claim_with(ip, || now)
4607            .expect_err("asked too recently");
4608        assert!(ready > now + Duration::from_secs(365 * 24 * 60 * 60));
4609    }
4610
4611    /// A host is ready until it is probed, and then not until the gap has run.
4612    #[test]
4613    fn a_gap_starts_at_the_first_probe_and_runs_from_the_last() {
4614        let gap = Duration::from_secs(3600);
4615        let (_session, ctx) = ScanSession::builder()
4616            .host_probe_interval(Some(gap))
4617            .build();
4618        let ip: IpAddr = "192.0.2.1".parse().expect("an address");
4619        let now = Instant::now();
4620
4621        assert!(
4622            ctx.probe_ready_at(ip, now).is_none(),
4623            "an address nothing has probed is ready"
4624        );
4625        let _ = ctx.spacing.claim_with(ip, || now).expect("the first probe");
4626
4627        assert_eq!(ctx.probe_ready_at(ip, now), Some(now + gap));
4628        assert_eq!(ctx.spacing.claim_with(ip, || now), Err(now + gap));
4629        assert!(
4630            ctx.spacing.claim_with(ip, || now + gap).is_ok(),
4631            "the gap having run, the host is ready again"
4632        );
4633    }
4634
4635    /// One host's gap leaves every other host ready.
4636    #[test]
4637    fn a_gap_at_one_host_leaves_every_other_host_ready() {
4638        let (_session, ctx) = ScanSession::builder()
4639            .host_probe_interval(Some(Duration::from_secs(3600)))
4640            .build();
4641        let probed: IpAddr = "192.0.2.1".parse().expect("an address");
4642        let other: IpAddr = "192.0.2.2".parse().expect("an address");
4643        let now = Instant::now();
4644
4645        let _ = ctx
4646            .spacing
4647            .claim_with(probed, || now)
4648            .expect("the first probe");
4649
4650        assert!(ctx.spacing.claim_with(probed, || now).is_err());
4651        assert!(ctx.spacing.claim_with(other, || now).is_ok());
4652    }
4653
4654    /// The scan-wide gap is the one that spaces a range: a probe at one host
4655    /// holds back the next probe at any other.
4656    #[test]
4657    fn a_scan_wide_gap_holds_every_host_behind_the_last_probe() {
4658        let gap = Duration::from_secs(3600);
4659        let (_session, ctx) = ScanSession::builder().probe_interval(Some(gap)).build();
4660        let first: IpAddr = "192.0.2.1".parse().expect("an address");
4661        let other: IpAddr = "192.0.2.2".parse().expect("an address");
4662        let now = Instant::now();
4663
4664        let _ = ctx
4665            .spacing
4666            .claim_with(first, || now)
4667            .expect("the first probe");
4668
4669        assert_eq!(ctx.probe_ready_at(other, now), Some(now + gap));
4670        assert_eq!(ctx.spacing.claim_with(other, || now), Err(now + gap));
4671        assert!(ctx.spacing.claim_with(other, || now + gap).is_ok());
4672    }
4673
4674    /// With both gaps kept, a probe waits for whichever runs out later, and a
4675    /// claim turned away by one records nothing on the other.
4676    #[test]
4677    fn two_gaps_hold_a_probe_until_the_later_has_run() {
4678        let short = Duration::from_secs(60);
4679        let long = Duration::from_secs(3600);
4680        let (_session, ctx) = ScanSession::builder()
4681            .host_probe_interval(Some(long))
4682            .probe_interval(Some(short))
4683            .build();
4684        let ip: IpAddr = "192.0.2.1".parse().expect("an address");
4685        let other: IpAddr = "192.0.2.2".parse().expect("an address");
4686        let now = Instant::now();
4687
4688        let _ = ctx.spacing.claim_with(ip, || now).expect("the first probe");
4689        assert_eq!(ctx.spacing.claim_with(ip, || now + short), Err(now + long));
4690
4691        // Turned away at its host, so the scan-wide slot is still the first
4692        // probe's.
4693        assert!(ctx.spacing.claim_with(other, || now + short).is_ok());
4694    }
4695
4696    /// A frame sent to a group spends the scan-wide gap and no host's, so a
4697    /// refund gives back only the scan's slot.
4698    #[test]
4699    fn a_group_probe_spends_the_scan_wide_gap_and_no_hosts() {
4700        let gap = Duration::from_secs(3600);
4701        let (_session, ctx) = ScanSession::builder()
4702            .host_probe_interval(Some(gap))
4703            .probe_interval(Some(gap))
4704            .build();
4705        let group: IpAddr = "ff02::2".parse().expect("an address");
4706        let host: IpAddr = "192.0.2.1".parse().expect("an address");
4707        let now = Instant::now();
4708
4709        let claim = ctx
4710            .spacing
4711            .claim_group_with(group, || now)
4712            .expect("the first frame");
4713        assert_eq!(ctx.group_probe_ready_at(now), Some(now + gap));
4714        assert_eq!(ctx.spacing.claim_with(host, || now), Err(now + gap));
4715        assert!(
4716            ctx.spacing.last_at_host.is_empty(),
4717            "no host's clock was moved by a frame aimed at none of them"
4718        );
4719
4720        ctx.refund_probe(claim);
4721        assert!(ctx.group_probe_ready_at(now).is_none());
4722        assert!(
4723            ctx.spacing.claim_with(host, || now).is_ok(),
4724            "the refunded frame's slot is free again"
4725        );
4726        assert_eq!(
4727            ctx.spacing.claim_group_with(group, || now),
4728            Err(now + gap),
4729            "and the host probe after it holds the scan's slot"
4730        );
4731    }
4732
4733    /// A send the kernel refused gives its slot back, and the next probe may
4734    /// leave as though it had never been claimed.
4735    #[test]
4736    fn a_refunded_claim_frees_its_slot() {
4737        let gap = Duration::from_secs(3600);
4738        let (_session, ctx) = ScanSession::builder()
4739            .host_probe_interval(Some(gap))
4740            .probe_interval(Some(gap))
4741            .build();
4742        let ip: IpAddr = "192.0.2.1".parse().expect("an address");
4743        let now = Instant::now();
4744
4745        let earlier = ctx.spacing.claim_with(ip, || now).expect("the first probe");
4746        let refused = ctx
4747            .spacing
4748            .claim_with(ip, || now + gap)
4749            .expect("the gap has run");
4750        ctx.refund_probe(refused);
4751
4752        assert_eq!(
4753            ctx.probe_ready_at(ip, now + gap),
4754            None,
4755            "the refused probe's slot is free again"
4756        );
4757        assert_eq!(
4758            ctx.probe_ready_at(ip, now),
4759            Some(now + gap),
4760            "and the probe before it still holds its own"
4761        );
4762        let _ = earlier;
4763    }
4764
4765    /// A refund arriving after a later claim leaves that claim's slot alone.
4766    #[test]
4767    fn a_refund_never_frees_a_later_probes_slot() {
4768        let gap = Duration::from_secs(3600);
4769        let (_session, ctx) = ScanSession::builder().probe_interval(Some(gap)).build();
4770        let first: IpAddr = "192.0.2.1".parse().expect("an address");
4771        let second: IpAddr = "192.0.2.2".parse().expect("an address");
4772        let now = Instant::now();
4773
4774        let refused = ctx
4775            .spacing
4776            .claim_with(first, || now)
4777            .expect("the first probe");
4778        let sent = ctx
4779            .spacing
4780            .claim_with(second, || now + gap)
4781            .expect("the gap has run");
4782        ctx.refund_probe(refused);
4783
4784        assert_eq!(
4785            ctx.probe_ready_at(first, now + gap),
4786            Some(now + gap + gap),
4787            "the probe that went out still holds the scan-wide slot"
4788        );
4789        let _ = sent;
4790    }
4791
4792    /// Claims made at once from many threads grant one slot between them.
4793    #[test]
4794    fn concurrent_claims_share_one_slot() {
4795        let (_session, ctx) = ScanSession::builder()
4796            .host_probe_interval(Some(Duration::from_secs(3600)))
4797            .probe_interval(Some(Duration::from_secs(3600)))
4798            .build();
4799        let ip: IpAddr = "192.0.2.1".parse().expect("an address");
4800        let start = std::sync::Barrier::new(16);
4801
4802        let granted = std::thread::scope(|scope| {
4803            let claims: Vec<_> = (0..16)
4804                .map(|_| {
4805                    scope.spawn(|| {
4806                        start.wait();
4807                        ctx.claim_probe(ip).is_ok()
4808                    })
4809                })
4810                .collect();
4811            claims
4812                .into_iter()
4813                .map(|claim| claim.join().expect("a claiming thread"))
4814                .filter(|granted| *granted)
4815                .count()
4816        });
4817
4818        assert_eq!(granted, 1);
4819    }
4820
4821    /// The clock starts on the first probe aimed at a host, so a host the scan
4822    /// reaches late still has its whole budget.
4823    #[test]
4824    fn a_budget_still_running_leaves_the_host_alone() {
4825        let (_session, ctx) = ScanSession::builder()
4826            .host_timeout(Some(Duration::from_secs(3600)))
4827            .build();
4828        let ip: IpAddr = "192.0.2.1".parse().expect("an address");
4829
4830        assert!(!ctx.host_expired(ip));
4831        assert!(ctx.take_timed_out().is_empty());
4832    }
4833
4834    /// A resume does not restore what this sitting is forbidden to report,
4835    /// including addresses excluded after the journal was written.
4836    #[test]
4837    fn a_resume_leaves_out_an_address_this_sitting_may_not_report() {
4838        let excluded: IpAddr = "198.51.100.7".parse().expect("literal");
4839        let allowed: IpAddr = "203.0.113.7".parse().expect("literal");
4840
4841        let mut ips = crate::model::ip::set::IpSet::new();
4842        ips.insert_range("198.51.100.0/24".parse().expect("a valid range"));
4843        let (mut session, ctx) = ScanSession::builder()
4844            .excluding(Exclusions::new(ips))
4845            .build();
4846
4847        let restored = |ip: IpAddr| {
4848            let mut host = Host::new(ip);
4849            host.set_status(HostStatus::Up);
4850            host
4851        };
4852        ctx.restore_hosts(&[restored(excluded), restored(allowed)]);
4853
4854        assert!(
4855            !ctx.store.contains_key(&ScopedIp::unscoped(excluded)),
4856            "the journal's own record of an excluded address must not come back"
4857        );
4858        assert!(
4859            ctx.store.contains_key(&ScopedIp::unscoped(allowed)),
4860            "and everything else still does"
4861        );
4862        assert_eq!(ctx.store.len(), 1);
4863
4864        // One announcement, for the restored host.
4865        let Some(ScanEvent::HostUpdated(announced)) = session.events().try_recv() else {
4866            panic!("a restored host is announced");
4867        };
4868        assert_eq!(announced.addr(), allowed);
4869        assert!(
4870            session.events().try_recv().is_none(),
4871            "an excluded address is not announced either"
4872        );
4873    }
4874
4875    /// A session forbidding exactly `address`.
4876    fn forbidding(address: IpAddr) -> (ScanSession, ScanContext) {
4877        let mut ips = crate::model::ip::set::IpSet::new();
4878        ips.insert(address);
4879        ScanSession::builder()
4880            .excluding(Exclusions::new(ips))
4881            .build()
4882    }
4883
4884    /// What an edit attaches under a permitted key is held to the policy too.
4885    ///
4886    /// The local sweep, listen mode, mDNS hostname resolution and the resume
4887    /// path all add addresses inside the edit, under a key that passes the
4888    /// gate.
4889    #[test]
4890    fn an_address_an_edit_attaches_is_held_to_the_exclusions() {
4891        let key: IpAddr = "192.0.2.60".parse().expect("literal");
4892        let excluded: IpAddr = "192.0.2.61".parse().expect("literal");
4893        let (_session, ctx) = forbidding(excluded);
4894
4895        ctx.write_host(key, |host| host.add_ip(excluded));
4896
4897        let ips = ctx
4898            .read_host(key, |host| host.ips().clone())
4899            .expect("the permitted key is recorded");
4900        assert!(!ips.contains(&excluded), "{ips:?}");
4901        assert!(ips.contains(&key));
4902    }
4903
4904    /// An address filed as unreachable settles every target of the plan at
4905    /// it. A sweep settles the address; a port scan settles each of its ports,
4906    /// and one that earned a verdict first keeps it and is not counted twice.
4907    #[test]
4908    fn an_address_filed_unreachable_settles_its_targets() {
4909        use crate::model::ip::set::Positions;
4910        use crate::model::target::{TargetIndex, TargetMap, TargetSet};
4911
4912        let unreachable: IpAddr = "192.0.2.2".parse().expect("literal");
4913
4914        let sweep: IpSet = "192.0.2.1-192.0.2.3".parse().expect("a range");
4915        let (_session, ctx) = ScanSession::builder()
4916            .counting(Positions::of(&sweep))
4917            .build();
4918        ctx.record_unroutable(unreachable);
4919        ctx.record_unroutable(unreachable);
4920        let settled = ctx.settlements();
4921        assert!(
4922            settled.checkpoint().is_settled(1),
4923            "the address is still owed"
4924        );
4925        assert_eq!(settled.checkpoint().settled_count(), 1);
4926        assert_eq!(settled.count(Outcome::Unreachable { position: 0 }), 1);
4927
4928        let mut map = TargetMap::new();
4929        map.add_unit(TargetSet::new(sweep, "1-3".parse().expect("ports")));
4930        let (_session, ctx) = ScanSession::new();
4931        ctx.number_targets(TargetIndex::of(&map));
4932        ctx.record_outcome(Outcome::Exhausted { position: 4 });
4933        ctx.record_unroutable(unreachable);
4934        let checkpoint = ctx.settlements().checkpoint();
4935        assert_eq!(
4936            (0..9)
4937                .filter(|position| checkpoint.is_settled(*position))
4938                .collect::<Vec<_>>(),
4939            [3, 4, 5],
4940            "the three ports of the second address, and nothing else"
4941        );
4942        assert_eq!(
4943            ctx.settlements()
4944                .count(Outcome::Unreachable { position: 0 }),
4945            2
4946        );
4947    }
4948
4949    /// A machine an exclusion names is withheld at every address it answers
4950    /// from, such as the IPv6 addresses an excluded IPv4 device answers the
4951    /// all-nodes echo from. The shared hardware address ties them: a finding
4952    /// carrying it is dropped whole, the address is asked nothing more, and
4953    /// the phase lists it as excluded. A neighbour with other hardware is kept.
4954    #[test]
4955    fn a_machine_an_exclusion_names_is_withheld_at_its_other_addresses() {
4956        use crate::model::mac::MacAddr;
4957        use crate::report::{ScanKind, TargetScope};
4958        use crate::scanner::recorder::PhaseRecorder;
4959
4960        let excluded: IpAddr = "192.0.2.30".parse().expect("literal");
4961        let machine = MacAddr::new(0x02, 0, 0, 0, 0, 0x30);
4962        let neighbour_mac = MacAddr::new(0x02, 0, 0, 0, 0, 0x31);
4963        let (link_local, global, neighbour): (IpAddr, IpAddr, IpAddr) = (
4964            "2001:db8::30".parse().expect("literal"),
4965            "2001:db8::3030".parse().expect("literal"),
4966            "2001:db8::31".parse().expect("literal"),
4967        );
4968        let mut ips = IpSet::new();
4969        ips.insert(excluded);
4970        let (session, ctx) = ScanSession::builder()
4971            .excluding(Exclusions::new(ips))
4972            .with_neighbours(vec![(excluded, Some(machine))])
4973            .build();
4974        let mut scope_ips = IpSet::new();
4975        scope_ips.insert(neighbour);
4976        let recorder = PhaseRecorder::start(
4977            ScanKind::Discovery,
4978            crate::system::privilege::Privilege::Raw,
4979            TargetScope::from_ip_set(&mut scope_ips, &ctx.exclusions),
4980            &crate::config::ZondConfig::default(),
4981        );
4982
4983        // An echo reply off the segment: the source address, and the frame's.
4984        let answered = |address: IpAddr, mac: MacAddr| {
4985            ctx.write_host(address, |host| {
4986                host.set_status(crate::model::host::HostStatus::Up);
4987                host.record_mac(mac);
4988                true
4989            });
4990        };
4991        answered(link_local, machine);
4992        answered(neighbour, neighbour_mac);
4993        // Found by address first, its hardware arriving with a later frame.
4994        ctx.update_host(global, |host| {
4995            host.set_status(crate::model::host::HostStatus::Up)
4996        });
4997        answered(global, machine);
4998
4999        for address in [link_local, global] {
5000            assert!(
5001                session.hosts().get(address).is_none(),
5002                "{address} answered from the excluded machine and was recorded"
5003            );
5004            assert!(!ctx.may_probe(&address), "{address} may still be asked");
5005        }
5006        assert!(session.hosts().get(neighbour).is_some());
5007        assert!(ctx.may_probe(&neighbour));
5008
5009        let report = recorder.finish(&ctx);
5010        let listed: Vec<IpAddr> = report.phases()[0]
5011            .targets()
5012            .excluded()
5013            .iter()
5014            .map(|range| range.start_addr())
5015            .collect();
5016        for address in [excluded, link_local, global] {
5017            assert!(listed.contains(&address), "{address} not in {listed:?}");
5018        }
5019    }
5020
5021    /// An excluded address never leads a host, since the service, SNMP, TLS
5022    /// and detection passes connect to the leading address. A global IPv6
5023    /// address outranks a link-local, so it would otherwise take the lead.
5024    #[test]
5025    fn an_excluded_address_does_not_become_the_one_a_host_is_reached_at() {
5026        let key: IpAddr = "fe80::10".parse().expect("literal");
5027        let excluded: IpAddr = "2001:db8::5".parse().expect("literal");
5028        let (_session, ctx) = forbidding(excluded);
5029
5030        ctx.write_host(key, |host| host.consider_primary_ip(excluded));
5031
5032        let (primary, ips) = ctx
5033            .read_host(key, |host| (host.primary_ip(), host.ips().clone()))
5034            .expect("the permitted key is recorded");
5035        assert_eq!(primary, key, "led by the address the policy allows");
5036        assert!(!ips.contains(&excluded), "{ips:?}");
5037    }
5038
5039    /// A path three routers long, whose second router is `router`.
5040    fn traced_through(target: IpAddr, router: IpAddr) -> [Hop; 3] {
5041        [
5042            Hop::answered(
5043                1,
5044                "203.0.113.1".parse().expect("literal"),
5045                Some(Duration::from_millis(1)),
5046            ),
5047            Hop::answered(2, router, Some(Duration::from_millis(4))),
5048            Hop::answered(3, target, None),
5049        ]
5050    }
5051
5052    /// A router the policy forbids keeps its distance on a traced host's path
5053    /// and loses its address and timing.
5054    ///
5055    /// A trace sends nothing to the routers themselves, so only recording needs
5056    /// the policy. The hop stays as answered, since an empty entry would read
5057    /// as nothing known there.
5058    #[test]
5059    fn a_router_the_exclusions_forbid_is_withheld_from_a_traced_hosts_path() {
5060        let target: IpAddr = "203.0.113.9".parse().expect("literal");
5061        let excluded: IpAddr = "198.51.100.1".parse().expect("literal");
5062        let (_session, ctx) = forbidding(excluded);
5063
5064        ctx.write_host(target, |host| {
5065            for hop in traced_through(target, excluded) {
5066                host.record_hop(hop);
5067            }
5068            true
5069        });
5070
5071        let path = ctx
5072            .read_host(target, |host| host.path().clone())
5073            .expect("the traced host is recorded");
5074        assert!(
5075            path.hops()
5076                .iter()
5077                .all(|hop| hop.address() != Some(excluded)),
5078            "{path:?}"
5079        );
5080        let at_two = path.hops()[1];
5081        assert_eq!(at_two.distance(), 2, "the router keeps its place");
5082        assert!(at_two.is_withheld(), "a router answered there: {at_two:?}");
5083        assert_eq!(at_two.rtt(), None, "its timing is a fact about the router");
5084        assert_eq!(path.length(), Some(3));
5085        assert_eq!(path.at(1), Some("203.0.113.1".parse().expect("literal")));
5086    }
5087
5088    /// And a journal written before the router was excluded does not bring it
5089    /// back, since the resume path reaches the store without `write_host`.
5090    #[test]
5091    fn a_resume_withholds_a_router_this_sitting_may_not_report() {
5092        let target: IpAddr = "203.0.113.9".parse().expect("literal");
5093        let excluded: IpAddr = "198.51.100.1".parse().expect("literal");
5094        let (_session, ctx) = forbidding(excluded);
5095
5096        let mut journalled = Host::new(target);
5097        for hop in traced_through(target, excluded) {
5098            journalled.record_hop(hop);
5099        }
5100        ctx.restore_hosts(&[journalled]);
5101
5102        let path = ctx
5103            .read_host(target, |host| host.path().clone())
5104            .expect("the host is restored");
5105        assert!(
5106            path.hops()
5107                .iter()
5108                .all(|hop| hop.address() != Some(excluded)),
5109            "{path:?}"
5110        );
5111        assert!(path.hops()[1].is_withheld(), "{path:?}");
5112    }
5113
5114    /// A host-down reason sent by `sender`, a middlebox in front of the host.
5115    fn unreachable_from(sender: IpAddr) -> StatusReason {
5116        StatusReason::new(StatusProtocol::IcmpUnreachable, "destination unreachable")
5117            .from_source(sender)
5118    }
5119
5120    /// A middlebox the policy forbids is withheld from the evidence it sent
5121    /// about a permitted host, and the evidence is kept.
5122    ///
5123    /// The source is marked withheld, not cleared: a cleared source would say
5124    /// the host answered for itself.
5125    #[test]
5126    fn an_excluded_middlebox_is_withheld_from_a_permitted_hosts_evidence() {
5127        let target: IpAddr = "203.0.113.9".parse().expect("literal");
5128        let excluded: IpAddr = "198.51.100.1".parse().expect("literal");
5129        let (_session, ctx) = forbidding(excluded);
5130
5131        ctx.write_host(target, |host| {
5132            host.record_evidence(HostStatus::Down, unreachable_from(excluded));
5133            true
5134        });
5135
5136        let (status, reasons) = ctx
5137            .read_host(target, |host| (host.status(), host.reasons().clone()))
5138            .expect("the host the evidence is about is recorded");
5139        assert_eq!(status, HostStatus::Down, "the evidence still counts");
5140        let sources: Vec<EvidenceSource> = reasons.iter().map(|reason| reason.source).collect();
5141        assert_eq!(sources, [EvidenceSource::Withheld], "{reasons:?}");
5142    }
5143
5144    /// And a journal written before the middlebox was excluded does not bring
5145    /// its address back, since the resume path reaches the store without
5146    /// `write_host`.
5147    #[test]
5148    fn a_resume_withholds_a_middlebox_this_sitting_may_not_report() {
5149        let target: IpAddr = "203.0.113.9".parse().expect("literal");
5150        let excluded: IpAddr = "198.51.100.1".parse().expect("literal");
5151        let (_session, ctx) = forbidding(excluded);
5152
5153        let mut journalled = Host::new(target);
5154        journalled.record_evidence(HostStatus::Down, unreachable_from(excluded));
5155        ctx.restore_hosts(&[journalled]);
5156
5157        let sources: Vec<EvidenceSource> = ctx
5158            .read_host(target, |host| {
5159                host.reasons().iter().map(|reason| reason.source).collect()
5160            })
5161            .expect("the host is restored");
5162        assert_eq!(sources, [EvidenceSource::Withheld]);
5163    }
5164
5165    /// The resume path, which writes into the store without going through
5166    /// `write_host`, holds a restored host's other addresses to the policy as
5167    /// well as the one it is keyed by.
5168    #[test]
5169    fn a_resume_brings_back_none_of_a_hosts_excluded_addresses() {
5170        let key: IpAddr = "192.0.2.60".parse().expect("literal");
5171        let excluded: IpAddr = "192.0.2.61".parse().expect("literal");
5172        let (_session, ctx) = forbidding(excluded);
5173
5174        let mut host = Host::new(key);
5175        host.add_ip(excluded);
5176        ctx.restore_hosts(&[host]);
5177
5178        let ips = ctx
5179            .read_host(key, |host| host.ips().clone())
5180            .expect("the host is restored");
5181        assert!(!ips.contains(&excluded), "{ips:?}");
5182    }
5183
5184    /// A host an earlier sitting recorded under an address excluded since is
5185    /// restored under its best remaining one.
5186    #[test]
5187    fn a_resumed_host_led_by_an_excluded_address_is_kept_at_its_others() {
5188        let other: IpAddr = "fe80::10".parse().expect("literal");
5189        let excluded: IpAddr = "2001:db8::5".parse().expect("literal");
5190        let (_session, ctx) = forbidding(excluded);
5191
5192        let mut host = Host::new(other);
5193        host.consider_primary_ip(excluded);
5194        host.set_status(HostStatus::Up);
5195        assert_eq!(host.primary_ip(), excluded, "test premise");
5196        ctx.restore_hosts(&[host]);
5197
5198        let (primary, ips) = ctx
5199            .read_host(other, |host| (host.primary_ip(), host.ips().clone()))
5200            .expect("the host is kept at the address the policy allows");
5201        assert_eq!(primary, other);
5202        assert!(!ips.contains(&excluded), "{ips:?}");
5203    }
5204
5205    /// A port scan's settlements count port targets, so the addresses its
5206    /// liveness pass left are not counted. A sweep's plan is its addresses, and
5207    /// there they count.
5208    #[test]
5209    fn a_liveness_pass_leaves_a_port_scans_counters_alone() {
5210        let (_session, ports) = ScanSession::builder()
5211            .planning(Stage::Ports, Some(1_024))
5212            .build();
5213        ports.record_address_outcomes(Outcome::Unasked, 300);
5214        assert_eq!(ports.settlements().count(Outcome::Unasked), 0);
5215
5216        let (_session, sweep) = ScanSession::builder()
5217            .planning(Stage::Discovery, Some(1_024))
5218            .build();
5219        sweep.record_address_outcomes(Outcome::Unasked, 300);
5220        assert_eq!(sweep.settlements().count(Outcome::Unasked), 300);
5221    }
5222}