Skip to main content

zond_engine/
scanner.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//! # Network Scanning
10//!
11//! Turns a set of target addresses into scan results.
12//!
13//! A scan runs in two phases, each with its own entry point. [`discover`] finds
14//! which hosts in a target range are alive, and [`scan`] reports which ports are
15//! open on a set of targets, usually ones [`discover`] confirmed. A caller can run a
16//! cheap sweep first and spend port scanning only on hosts known to exist.
17//!
18//! # Three levels of control
19//!
20//! Each level is written in terms of the one below it, so moving down means taking
21//! over more of the decisions with the same code.
22//!
23//! Call [`discover`] or [`scan`]. Targets and a [`ZondConfig`] go in, a live
24//! [`ScanSession`] and a [`ScanReport`] come out. The engine decides privilege,
25//! interfaces, fallbacks, retries and hostname resolution. Most callers should stay
26//! here. [`scan_with_journal`] and [`discover_with_journal`] also record how far the
27//! run got, so one cut short can be continued, and the journal can be read back as
28//! the report it produced with [`store::report`](crate::journal::store::report).
29//!
30//! Build a [`plan`], edit it, run it. A [`DiscoveryPlan`](plan::DiscoveryPlan) is
31//! the set of strategies a scan intends to run, worked out from the targets and this
32//! host's configuration, with nothing opened and nothing sent. Printing it is a dry
33//! run, and steps can be dropped before running the rest. Its
34//! [refusals](plan::RefusedStep) say what a scan will not cover before it starts.
35//!
36//! Build one strategy and drive it yourself. Everything in [`strategy`] is public
37//! API: open a [`ScanSession`], construct a
38//! [`LocalScanner`](strategy::local::LocalScanner) aimed at one segment or a
39//! [`TcpPortScanner`](strategy::ports::TcpPortScanner) over a transport the caller
40//! opened, run it, and read the store. None of it needs a cargo feature.
41//!
42//! [`recorder::PhaseRecorder`] takes the scope and settings before the strategies
43//! start and closes into a [`ScanReport`] when they finish, so a scan driven this way
44//! reaches the exporters like one from [`discover`] or [`scan`]. Until then, what a
45//! strategy has filed is readable through
46//! [`ScanContext::failures_snapshot`](session::ScanContext::failures_snapshot) and
47//! [`probe_stats_snapshot`](session::ScanContext::probe_stats_snapshot).
48//!
49//! ```no_run
50//! use zond_engine::config::ZondConfig;
51//! use zond_engine::model::parse::ip::to_set;
52//! use zond_engine::scanner::plan::DiscoveryPlan;
53//! use zond_engine::scanner::session::ScanSession;
54//! use zond_engine::scanner::strategy::local::Scope;
55//!
56//! # fn example() -> Result<(), Box<dyn std::error::Error>> {
57//! let cfg = ZondConfig::default();
58//! let plan = DiscoveryPlan::build(
59//!     to_set(&["192.0.2.0/24"], None, None)?,
60//!     Scope::Sweep,
61//!     &cfg.exclusions,
62//!     &cfg.send_source,
63//! );
64//!
65//! // What the sweep would do, before it does any of it.
66//! for step in plan.steps() {
67//!     println!("{:?}: {} address(es)", step.kind(), step.target_count());
68//! }
69//! for refusal in plan.refusals() {
70//!     println!("not covered: {}", refusal.reason);
71//! }
72//!
73//! // And to run it, a context is what a strategy is built with.
74//! let (_session, ctx) = ScanSession::new();
75//! for step in plan.into_steps() {
76//!     let mut scanner = step.into_scanner(ctx.clone(), None, cfg.probe_tuning())?;
77//!     // scanner.discover_hosts().await?;
78//!     let _ = &mut scanner;
79//! }
80//! # Ok(())
81//! # }
82//! ```
83//!
84//! # How a scan is assembled
85//!
86//! Both phases adapt to whether the process holds root privileges. When it does,
87//! [`discover`] groups targets by the interface that reaches them and gives each
88//! group a strategy: [`LocalScanner`](strategy::local::LocalScanner) with ARP and
89//! ICMPv6 for hosts on the same segment, and
90//! [`RoutedScanner`](strategy::routed::RoutedScanner) with TCP SYN for anything
91//! behind a gateway. [`scan`] does the same for ports: a privileged caller gets
92//! [`TcpPortScanner`](strategy::ports::TcpPortScanner), which classifies each port
93//! from a single raw exchange. Targets that map to no usable interface, and every
94//! target when unprivileged, fall back to TCP connect.
95//!
96//! All of these implement [`HostScanner`](strategy::HostScanner) or
97//! [`PortScanner`](strategy::PortScanner), so one loop drives them. Discovered hosts
98//! land in a shared store as they are found and each update fires an event, so a
99//! caller can watch a scan in progress. When DNS resolution is enabled, [`rdns`]
100//! looks up hostnames in the background without blocking discovery.
101
102use std::pin::Pin;
103
104use tokio::task::JoinHandle;
105
106use crate::config::ZondConfig;
107use crate::detect::Detections;
108use crate::journal::cursor::Checkpoint;
109use crate::model::{
110    ip::scoped::Zone,
111    ip::set::{IpSet, Positions},
112    port::PortSet,
113    target::{TargetIndex, TargetMap},
114};
115#[cfg(feature = "journal-format")]
116use crate::report::ScanPhase;
117use crate::report::ScannerKind;
118use crate::report::{LivenessSkip, ScanKind, ScanReport, TargetScope};
119use crate::scanner::orchestrator::{
120    Enrichment, ScanCapabilities, finish_enrichment, probed_subset, run_port_phase,
121};
122use crate::scanner::recorder::PhaseRecorder;
123use crate::scanner::session::{ScanContext, ScanSession, Stage};
124use crate::system::interface;
125use crate::system::privilege::Privilege;
126use strategy::local::Scope;
127use strategy::routed::SynPorts;
128
129// What running a scan produces: a `ScanSession` to watch it, a `ScanHandle` to
130// stop it, and a `ScanReport` once it is over.
131pub mod handle;
132pub mod recorder;
133pub mod session;
134
135// The strategies and the traits that make them interchangeable. Driving one
136// scanner yourself is supported, so these are public without a feature.
137pub mod plan;
138pub mod strategy;
139
140// What a caller driving strategies itself needs beside them. `dispatcher` feeds
141// targets to a `PortScanner`, `rdns` is the hostname tail, and `service` and
142// `detection` are the passes run over the ports a scan found open.
143/// The timer that writes a running scan into its journal, and the handle that
144/// stops it. Behind `journal-format` because that is what compiles a
145/// [`Journal`](crate::journal::Journal) to write into.
146#[cfg(feature = "journal-format")]
147pub mod checkpoint;
148pub mod detection;
149pub mod dispatcher;
150pub mod rdns;
151pub mod service;
152
153// What the strategies are built from: `pacing` decides when a probe is sent
154// again and when silence is an answer, `audit` counts what a raw scanner saw of
155// its own run, `pool` bounds a fan-out of connect probes, and `payload` is what a
156// UDP probe carries. Each is tuned through its strategy's constructor.
157pub(crate) mod audit;
158pub(crate) mod pacing;
159pub(crate) mod payload;
160pub(crate) mod pool;
161
162// How the entry points below assemble a scan. A caller who wants a different
163// policy builds a `plan` and runs the steps they want. `vantage` reads what this
164// machine's own interfaces and routes say about the hosts the scan found.
165mod orchestrator;
166mod vantage;
167
168/// An error returned when a scan fails to run to completion.
169#[non_exhaustive]
170#[derive(Debug, thiserror::Error)]
171pub enum ScanError {
172    /// The scan task did not run to completion.
173    ///
174    /// Reached on a panic inside the engine or on the runtime shutting down
175    /// under it. A stop through
176    /// [`ScanHandle::abort`](crate::scanner::handle::ScanHandle::abort) still
177    /// yields a report. A panic carries its message so the caller has something
178    /// to report upstream.
179    #[error("the scan task {}: {detail}", if *.panicked { "panicked" } else { "was cancelled" })]
180    TaskFailed {
181        /// Whether the task panicked; false if the runtime cancelled it.
182        panicked: bool,
183        /// What the panic said, or why the task was cancelled.
184        detail: String,
185    },
186
187    /// The journal handed to a scan records the engine's other phase.
188    ///
189    /// A sweep counts addresses and a port scan counts address-and-port pairs,
190    /// so one continued as the other would skip targets nothing ever probed.
191    #[error("this journal records the other phase of a scan")]
192    WrongPhase,
193
194    /// This run's settings would not produce the plan the journal is counted in.
195    #[cfg(feature = "journal-format")]
196    #[error("{0}")]
197    PlanChanged(#[from] crate::journal::manifest::PlanChanged),
198
199    /// This run asks for an option the job its journal records did not run
200    /// under.
201    ///
202    /// A sitting under a different technique, retry policy or set of passes
203    /// answers a different question, and its results would be mixed into one
204    /// report with the earlier sittings'. See
205    /// [`JobOptions`](crate::journal::manifest::JobOptions) for which options
206    /// are held, and [`JobOptions::apply_to`](crate::journal::manifest::JobOptions::apply_to)
207    /// for continuing a job under the ones it recorded.
208    #[cfg(feature = "journal-format")]
209    #[error("{0}")]
210    OptionChanged(#[from] crate::journal::manifest::OptionChanged),
211
212    /// The evasion profile is not one a scan could put on the wire.
213    ///
214    /// Checked once before anything is sent, since a profile every probe refuses
215    /// would report an empty network. See
216    /// [`EvasionProfile::validate`](crate::EvasionProfile::validate) for what the
217    /// check covers.
218    #[error("{0}")]
219    Evasion(#[from] crate::evasion::EvasionError),
220
221    /// The process may hold too few file descriptors for a scan to keep a
222    /// socket for its connections beside what the rest of the process needs,
223    /// counting what it holds open when the scan starts where that can be
224    /// counted.
225    ///
226    /// Checked before anything is sent, since the scan's connections and the
227    /// process's other files, a journal among them, would otherwise run out of
228    /// descriptors partway through. The engine never raises the limit; a caller
229    /// raises its own soft limit, within the hard one, before starting a scan.
230    #[error("file descriptor limit {limit} is below the {needed} a scan needs")]
231    TooFewDescriptors {
232        /// The soft limit the process has.
233        limit: usize,
234        /// The least limit a scan needs, beside what the process holds open.
235        needed: usize,
236    },
237}
238
239/// Runs a journalled phase's up-front checks, and gives the journal up if they
240/// refuse, so a scan that never started leaves no record of itself.
241///
242/// Every check a journalled entry point makes before it starts belongs in
243/// `checks`, so no refusal leaves a record behind. See [`Journal::withdraw`](crate::journal::Journal::withdraw) for
244/// which records go.
245#[cfg(feature = "journal-format")]
246fn accepted(
247    journal: crate::journal::Journal,
248    checks: impl FnOnce(&crate::journal::Journal) -> Result<(), ScanError>,
249) -> Result<crate::journal::Journal, ScanError> {
250    match checks(&journal) {
251        Ok(()) => Ok(journal),
252        Err(refused) => {
253            journal.withdraw();
254            Err(refused)
255        }
256    }
257}
258
259/// Refuses a sitting that asks what the job it continues did not; see
260/// [`JobOptions`](crate::journal::manifest::JobOptions) for which options
261/// those are.
262///
263/// A journal that recorded none is continued under `cfg` as it stands, since
264/// nothing says what its options were.
265#[cfg(feature = "journal-format")]
266fn under_the_recorded_options(
267    journal: &crate::journal::Journal,
268    cfg: &ZondConfig,
269) -> Result<(), ScanError> {
270    match journal.options() {
271        Some(options) => Ok(options.check(cfg)?),
272        None => Ok(()),
273    }
274}
275
276/// `cfg` with the TCP technique a port scan's journal was counted under, where
277/// the journal recorded no options to hold the sitting to.
278///
279/// The technique is part of the plan's fingerprint, so a journal that resumed
280/// was counted under the one its manifest names. A job with recorded options is
281/// held to it by [`under_the_recorded_options`]. One without has only the
282/// manifest, so the sitting runs under the manifest's technique, with a note
283/// when that differs from `cfg`, to keep its segments of the same kind.
284#[cfg(feature = "journal-format")]
285fn under_the_recorded_technique(journal: &crate::journal::Journal, cfg: &ZondConfig) -> ZondConfig {
286    let recorded = journal.manifest().technique();
287    if journal.options().is_some() || recorded == cfg.tcp_technique {
288        return cfg.clone();
289    }
290    crate::info!(
291        verbosity = 1,
292        "{recorded} scan, as the job recorded (not {})",
293        cfg.tcp_technique
294    );
295    ZondConfig {
296        tcp_technique: recorded,
297        ..cfg.clone()
298    }
299}
300
301/// Writes down the options a journal's first sitting runs under, so every
302/// later sitting can be held to them.
303///
304/// A journal that cannot take them still scans, with a warning. A later sitting
305/// is then continued under whatever options its caller passes.
306#[cfg(feature = "journal-format")]
307fn recording_options(
308    mut journal: crate::journal::Journal,
309    cfg: &ZondConfig,
310) -> crate::journal::Journal {
311    use crate::journal::manifest::JobOptions;
312
313    if let Err(e) = journal.record_options(JobOptions::of(cfg)) {
314        crate::warn!("options not recorded ({e})");
315    }
316    journal
317}
318
319/// The links a scan probing `addresses` captures on, once it is known that
320/// the process has the descriptors for them; see
321/// [`capture_links_toward`](crate::transport::probe::capture_links_toward)
322/// and [`enough_descriptors`].
323///
324/// The same set is handed to the context the scan's captures read, so the
325/// up-front check counts what the scan opens. Counting every link would refuse
326/// scans that need a device or two on a machine with dozens of links.
327fn capture_plan(addresses: &IpSet, cfg: &ZondConfig) -> Result<Vec<Zone>, ScanError> {
328    let mut addresses = addresses.clone();
329    cfg.exclusions.withhold(&mut addresses);
330    let links = crate::transport::probe::capture_links_toward(&addresses, &cfg.send_source);
331    enough_descriptors(captures_needed(Privilege::current(), &links))?;
332    Ok(links)
333}
334
335/// How many capture devices a process holding `privilege` opens for a scan
336/// capturing on `links`: one a link where it may choose its own packets, and
337/// none where it probes by connect.
338///
339/// A raw process whose every target is loopback probes by connect and opens
340/// nothing, but is still counted its link: the need is read before the phases
341/// decide, and one extra device costs nothing.
342fn captures_needed(privilege: Privilege, links: &[Zone]) -> usize {
343    match privilege.is_raw() {
344        true => links.len(),
345        false => 0,
346    }
347}
348
349/// Refuses a scan in a process whose descriptor limit, or whose table as it
350/// stands, leaves its connections no socket once its `captures` capture
351/// devices are open; see [`ScanError::TooFewDescriptors`].
352fn enough_descriptors(captures: usize) -> Result<(), ScanError> {
353    match crate::system::descriptors::too_few(captures) {
354        Some((limit, needed)) => Err(ScanError::TooFewDescriptors { limit, needed }),
355        None => Ok(()),
356    }
357}
358
359/// Every address `target_map` names a port at.
360fn plan_addresses(target_map: &TargetMap) -> IpSet {
361    orchestrator::unsettled_ips(target_map, &Checkpoint::default())
362}
363
364/// Refuses a sitting that would not count its targets as its journal did.
365///
366/// `this_run` is the plan this sitting numbers: what it was handed, less what
367/// its exclusion policy withholds. A position is an index into that
368/// enumeration, so a different plan would read every settled position as a
369/// different target and skip ground nothing asked about. A caller continuing
370/// from the recorded plan passes that, and the test is then of the policy
371/// alone: one that withholds nothing further leaves the same fingerprint.
372///
373/// A policy that withholds *less* than the first sitting's passes when applied
374/// to the recorded plan. That plan is what is being continued; widening the
375/// scope is a new scan.
376///
377/// The privilege checked is what this process can send, because it decides
378/// which question the probes answer; see
379/// [`PlanFingerprint::of`](crate::journal::manifest::PlanFingerprint::of).
380#[cfg(feature = "journal-format")]
381fn counted_as_recorded(
382    journal: &crate::journal::Journal,
383    this_run: &crate::journal::manifest::Plan,
384) -> Result<(), ScanError> {
385    journal.manifest().covers(this_run, Privilege::current())?;
386    Ok(())
387}
388
389/// What a `JoinError` was, in a form a consumer can act on.
390///
391/// `tokio` hands back the panic payload as `Box<dyn Any>`. The two shapes a
392/// `panic!` produces are read out, and any other payload is reported as one
393/// without a message.
394fn panic_or_cancellation(error: tokio::task::JoinError) -> ScanError {
395    if !error.is_panic() {
396        return ScanError::TaskFailed {
397            panicked: false,
398            detail: "the runtime shut down before the scan finished".to_string(),
399        };
400    }
401
402    let payload = error.into_panic();
403    let detail = payload
404        .downcast_ref::<&'static str>()
405        .map(|message| (*message).to_string())
406        .or_else(|| payload.downcast_ref::<String>().cloned())
407        .unwrap_or_else(|| "a panic carrying no message".to_string());
408
409    ScanError::TaskFailed {
410        panicked: true,
411        detail,
412    }
413}
414
415/// A handle to a running scan.
416///
417/// Discovered hosts arrive live through the paired [`ScanSession`]. Await this
418/// handle, or call [`ScanTask::join`], to wait for the whole scan to finish and
419/// receive the [`ScanReport`] describing it. To stop a scan early, call
420/// [`ScanHandle::abort`](crate::scanner::handle::ScanHandle::abort) on the
421/// session's handle; the report still arrives, describing however far the scan
422/// got.
423///
424/// A scan given
425/// [`ZondConfig::scan_timeout`](crate::config::ZondConfig::scan_timeout) stops
426/// itself the same way when its budget runs out.
427///
428/// # Dropping it stops the scan
429///
430/// This is the scan's owner and the only way to its report. Dropped before the
431/// scan has finished, or while being awaited, it stops the scan as
432/// [`abort`](crate::scanner::handle::ScanHandle::abort) would; otherwise a
433/// listener scan would keep its sockets, captures and probes going forever. The
434/// scan winds down through the usual checks, so a journal it writes gets its last
435/// checkpoint and keeps its lock until then, and no resume can take the job while
436/// this one is still probing. That last write needs the scan's runtime: a task
437/// dropped after the runtime has shut down leaves the journal at its last timed
438/// checkpoint.
439///
440/// Dropping the [`ScanSession`] stops nothing, so a caller that wants only the
441/// report may let it go and await this.
442pub struct ScanTask {
443    /// The scan, until it is joined or dropped.
444    handle: Option<JoinHandle<ScanReport>>,
445    /// The scan's stop, which dropping this pulls.
446    stop: handle::ScanHandle,
447    /// The journal this scan writes to, given its last checkpoint and released
448    /// once the scan ends.
449    #[cfg(feature = "journal-format")]
450    journal: Option<checkpoint::Checkpointing>,
451    /// What earlier sittings of this job did, restored from the journal.
452    ///
453    /// Folded in front of this run's own phases when the task is joined, so the
454    /// report describes the whole job.
455    #[cfg(feature = "journal-format")]
456    earlier: Vec<ScanPhase>,
457}
458
459impl ScanTask {
460    fn new(handle: JoinHandle<ScanReport>, stop: handle::ScanHandle) -> Self {
461        Self {
462            handle: Some(handle),
463            stop,
464            #[cfg(feature = "journal-format")]
465            journal: None,
466            #[cfg(feature = "journal-format")]
467            earlier: Vec::new(),
468        }
469    }
470
471    /// A task that closes `journal` once the scan it describes has finished.
472    #[cfg(feature = "journal-format")]
473    fn journalling(
474        handle: JoinHandle<ScanReport>,
475        stop: handle::ScanHandle,
476        journal: checkpoint::Checkpointing,
477        earlier: Vec<ScanPhase>,
478    ) -> Self {
479        Self {
480            handle: Some(handle),
481            stop,
482            journal: Some(journal),
483            earlier,
484        }
485    }
486
487    /// Waits for the scan to finish and returns its report.
488    ///
489    /// An error here means the scan never ran to completion. A strategy that
490    /// failed part way through is recorded in the report's
491    /// [`failures`](ScanReport::failures) and announced on the [`ScanSession`]
492    /// event stream, and the report keeps what the other strategies found.
493    ///
494    /// Dropped while it waits, the scan is stopped; see
495    /// [the type](ScanTask#dropping-it-stops-the-scan).
496    pub async fn join(mut self) -> Result<ScanReport, ScanError> {
497        // Awaited in place, so a join dropped part way still drops the task
498        // with its handle and stops the scan.
499        let running = self.handle.as_mut().expect("a task is joined at most once");
500        let report = running.await.map_err(panic_or_cancellation);
501        self.handle = None;
502
503        // After the scan, so the last checkpoint sees everything it settled and
504        // records only this sitting's phases. A failed scan gets one too, since
505        // a resume needs to know how far it got.
506        #[cfg(feature = "journal-format")]
507        if let Some(journal) = self.journal.take() {
508            let phases = report.as_ref().map(ScanReport::phases).unwrap_or_default();
509            journal.finish(phases).await;
510        }
511
512        // Earlier sittings in front of this one, in the order they ran.
513        #[cfg(feature = "journal-format")]
514        if !self.earlier.is_empty() {
515            let earlier = std::mem::take(&mut self.earlier);
516            return report.map(|report| {
517                let mut whole = ScanReport::from_phases(earlier, []);
518                whole.merge(report);
519                whole
520            });
521        }
522
523        report
524    }
525}
526
527impl Drop for ScanTask {
528    fn drop(&mut self) {
529        let Some(scan) = self.handle.take() else {
530            return;
531        };
532        self.stop.abort();
533
534        // A drop cannot wait, so the journal is closed from a task of its own
535        // once the scan has wound down. Without a runtime there is no scan left
536        // to wait for.
537        #[cfg(feature = "journal-format")]
538        if let Some(journal) = self.journal.take()
539            && let Ok(runtime) = tokio::runtime::Handle::try_current()
540        {
541            runtime.spawn(async move {
542                let phases = match scan.await {
543                    Ok(report) => report.phases().to_vec(),
544                    Err(_) => Vec::new(),
545                };
546                journal.finish(&phases).await;
547            });
548        }
549        #[cfg(not(feature = "journal-format"))]
550        drop(scan);
551    }
552}
553
554impl IntoFuture for ScanTask {
555    type Output = Result<ScanReport, ScanError>;
556    type IntoFuture = Pin<Box<dyn Future<Output = Self::Output> + Send>>;
557
558    fn into_future(self) -> Self::IntoFuture {
559        Box::pin(self.join())
560    }
561}
562
563/// Finds which hosts, among a set of target addresses, are alive.
564///
565/// The first phase of a scan: it finds hosts, without probing their ports.
566///
567/// With root privileges, targets are grouped by the interface that reaches them
568/// and each group gets its own strategy:
569/// [`LocalScanner`](strategy::local::LocalScanner) uses ARP and ICMP for hosts
570/// on the same segment, and [`RoutedScanner`](strategy::routed::RoutedScanner)
571/// uses TCP SYN for anything behind a gateway. Without root, and for any target
572/// that maps to no interface such as a loopback address, probes fall back to
573/// TCP connect against a handful of common ports.
574///
575/// Hosts are written to the returned [`ScanSession`]'s store as they are found,
576/// and each write fires a [`ScanEvent`](crate::scanner::session::ScanEvent).
577/// Unless `cfg.no_dns` is set, hostnames are resolved in the background: by
578/// sniffing DNS and mDNS when privileged, and by reverse lookup otherwise. With
579/// it set, hosts are named from the hosts file alone.
580///
581/// The returned [`ScanTask`] resolves once every strategy and the resolver, if
582/// started, have finished, and yields the [`ScanReport`]. To stop a scan early,
583/// call [`ScanHandle::abort`](crate::scanner::handle::ScanHandle::abort) on the
584/// session's handle. Every phase checks that signal regularly, also within a
585/// target, and the same check ends a sweep that outlived
586/// [`ZondConfig::scan_timeout`](crate::config::ZondConfig::scan_timeout).
587pub async fn discover(
588    targets: IpSet,
589    cfg: &ZondConfig,
590) -> Result<(ScanSession, ScanTask), ScanError> {
591    cfg.evasion.validate()?;
592    let capture_links = capture_plan(&targets, cfg)?;
593
594    // Numbered over what the exclusions leave, as a journal numbers a sweep.
595    // Progress figures read the settlements, so an unnumbered sweep would
596    // report no work at all.
597    let mut numbered = targets.clone();
598    cfg.exclusions.withhold(&mut numbered);
599    numbered.canonicalize();
600    let positions = numbered.positions();
601    let planned = planned_addresses(&positions);
602
603    let (session, ctx) = ScanSession::builder()
604        .excluding(cfg.exclusions.clone())
605        .naming(cfg.target_names.clone())
606        .host_timeout(cfg.host_timeout)
607        .scan_timeout(cfg.scan_timeout)
608        .host_probe_interval(cfg.host_probe_interval)
609        .probe_interval(cfg.probe_interval)
610        .send_source(cfg.send_source.clone())
611        .listening_only_to(cfg.listen_only_ports.clone())
612        .counting(positions)
613        .planning(Stage::Discovery, planned)
614        .staging(discovery_stages(cfg))
615        .build();
616    let handle = spawn_discovery(targets, capture_links, cfg, ctx);
617    let stop = session.handle().clone();
618    Ok((session, ScanTask::new(handle, stop)))
619}
620
621/// [`discover`], writing down how far it got, so that a sweep cut short can be
622/// continued.
623///
624/// As with [`scan_with_journal`], journalling is the caller's choice: hand this
625/// a journal and the sweep is recorded; [`discover`] writes nothing to disk.
626///
627/// # The numbering comes from the journal
628///
629/// A journal holds the plan it is counted in, with the exclusion policy
630/// applied: [`Plan`](crate::journal::manifest::Plan) applies it, and
631/// [`Journal::resume`](crate::journal::Journal::resume) checks it has not moved.
632/// Positions are read back from there, so nothing passed here can disagree with
633/// what the first sitting counted.
634///
635/// `targets` is what the *first* sitting sweeps, as the caller named it, before
636/// exclusions. The engine subtracts the exclusions itself and records how many
637/// they withheld, which a caller cannot recover afterwards; a set already
638/// narrowed would make every report say the policy withheld nothing. A later
639/// sitting ignores `targets` and sweeps what earlier ones did not settle.
640///
641/// # What a sweep settles
642///
643/// An address. It is settled when it answers, or when its probes have been sent
644/// as many times as the policy allows with no answer. An address whose probes
645/// never left, one still mid-schedule when the sweep stopped, and one with no
646/// route carry no position and are asked again; see
647/// [`settle`](crate::journal::settle) for why.
648///
649/// The findings and the phase are recorded alongside the progress, so a resumed
650/// sweep starts from what earlier sittings found and its report describes the
651/// whole job: one phase per sitting, each with its own timings, settings and
652/// statistics.
653#[cfg(feature = "journal-format")]
654pub async fn discover_with_journal(
655    targets: IpSet,
656    cfg: &ZondConfig,
657    journal: crate::journal::Journal,
658) -> Result<(ScanSession, ScanTask), ScanError> {
659    let mut capture_links = Vec::new();
660    let journal = accepted(journal, |journal| {
661        cfg.evasion.validate()?;
662        if journal.manifest().kind() != ScanKind::Discovery {
663            return Err(ScanError::WrongPhase);
664        }
665        let recorded = journal.manifest().recorded();
666        let Some(addresses) = recorded.addresses() else {
667            return Err(ScanError::WrongPhase);
668        };
669        // What this sitting sweeps: the caller's set for a first sitting, and
670        // what the recorded plan leaves for a later one.
671        let swept = if *journal.resume_point() == Checkpoint::default() {
672            &targets
673        } else {
674            addresses
675        };
676        // A later sitting plans over the whole job, which holds what it has left.
677        capture_links = capture_plan(swept, cfg)?;
678        let this_run = crate::journal::manifest::Plan::discovery(
679            swept,
680            &cfg.exclusions,
681            recorded.sweeps_the_segment(),
682        );
683        counted_as_recorded(journal, &this_run)?;
684        under_the_recorded_options(journal, cfg)
685    })?;
686    let journal = recording_options(journal, cfg);
687
688    let recorded = journal.manifest().recorded();
689    let Some(addresses) = recorded.addresses() else {
690        return Err(ScanError::WrongPhase);
691    };
692
693    // Numbered over the whole plan, whichever part this sitting sweeps, so
694    // every sitting gives an address the same position.
695    let positions = addresses.positions();
696    let resume_point = journal.resume_point().clone();
697    // The first sitting's sweep order. A fresh order halfway through would
698    // change the shape of the run, which is a signature of its own.
699    let order_seed = journal.manifest().order_seed;
700
701    let sweep = if resume_point == Checkpoint::default() {
702        targets
703    } else {
704        resume_point.remaining_addresses(&positions)
705    };
706
707    let planned = planned_addresses(&positions);
708    let finished = journal.finished_hosts().unwrap_or_else(|e| {
709        crate::warn!("passes rerun for every host ({e})");
710        Default::default()
711    });
712
713    let (session, ctx) = ScanSession::builder()
714        .excluding(cfg.exclusions.clone())
715        .naming(cfg.target_names.clone())
716        .host_timeout(cfg.host_timeout)
717        .scan_timeout(cfg.scan_timeout)
718        .host_probe_interval(cfg.host_probe_interval)
719        .probe_interval(cfg.probe_interval)
720        .send_source(cfg.send_source.clone())
721        .listening_only_to(cfg.listen_only_ports.clone())
722        .resuming(&resume_point)
723        .finished(finished, sweep.clone())
724        .counting(positions)
725        .planning(Stage::Discovery, planned)
726        .staging(discovery_stages(cfg))
727        .ordering(order_seed)
728        .build();
729
730    ctx.restore_hosts(journal.restored());
731    let earlier = journal.earlier_phases().to_vec();
732
733    let ticker = checkpoint::spawn_checkpoints(journal, ctx.progress());
734    let handle = spawn_discovery(sweep, capture_links, cfg, ctx);
735
736    let stop = session.handle().clone();
737    Ok((
738        session,
739        ScanTask::journalling(handle, stop, ticker, earlier),
740    ))
741}
742
743/// How many addresses a sweep plans to ask about, or `None` where they cannot
744/// all be numbered.
745///
746/// The numbering is the one a journal settles positions against, so a fraction
747/// built from this counts what
748/// [`Progress::settled`](crate::scanner::session::Progress::settled) counts. A
749/// range too wide to number could never be scanned to the end anyway.
750fn planned_addresses(positions: &Positions) -> Option<u64> {
751    positions.unnumbered().is_empty().then(|| positions.total())
752}
753
754/// The stages a sweep under `cfg` expects to run, in the order it runs them.
755fn discovery_stages(cfg: &ZondConfig) -> Vec<Stage> {
756    let mut stages = vec![Stage::Discovery];
757
758    if cfg.os_detection.is_active() {
759        stages.push(Stage::Os);
760    }
761    if cfg.traceroute {
762        stages.push(Stage::Traceroute);
763    }
764    if cfg.characterise {
765        stages.push(Stage::Filters);
766    }
767    if !cfg.ip_protocols.is_empty() {
768        stages.push(Stage::IpProtocols);
769    }
770
771    stages
772}
773
774/// The stages a port scan under `cfg` expects to run, in the order it runs them.
775///
776/// A superset. Whether service detection, the detection corpus and the TLS pass
777/// find anything to do depends on which ports turn out to be open, so each is
778/// listed whenever the settings permit it and stepped over if it comes to
779/// nothing.
780///
781/// [`Stage::Finishing`] is left out: it sends nothing and is over as soon as it
782/// begins.
783///
784/// Read through [`running_under`], so an idle scan lists only the stages it will
785/// run and no progress bar waits for a stage the scan declines.
786///
787/// `runs_liveness` is [`liveness_earns_its_place`]'s verdict, passed in so the
788/// plan it may build is built once per scan.
789fn scan_stages(cfg: &ZondConfig, runs_liveness: bool) -> Vec<Stage> {
790    let cfg = &running_under(cfg);
791    let mut stages = Vec::new();
792
793    if runs_liveness {
794        stages.push(Stage::Discovery);
795    }
796    stages.push(Stage::Ports);
797
798    if cfg.service_detection.connects() {
799        stages.push(Stage::Services);
800    }
801    if cfg.service_detection != crate::config::ServiceDetection::Off
802        && cfg.detection.ceiling().is_some()
803    {
804        stages.push(Stage::Detections);
805    }
806    if cfg.tls_enumeration {
807        stages.push(Stage::Tls);
808    }
809    if cfg.os_detection.is_active() {
810        stages.push(Stage::Os);
811    }
812    if cfg.traceroute {
813        stages.push(Stage::Traceroute);
814    }
815    if cfg.characterise {
816        stages.push(Stage::Filters);
817    }
818    if !cfg.ip_protocols.is_empty() {
819        stages.push(Stage::IpProtocols);
820    }
821
822    stages
823}
824
825/// Whether a port scan under `cfg` asks its targets whether they are there
826/// before it probes their ports.
827///
828/// False where the caller declined it with [`ZondConfig::assume_up`], and under
829/// an [idle scan](ZondConfig::idle_scan), which forges every probe from its
830/// zombie so the target never hears from this host. A liveness probe cannot be
831/// forged from the zombie either, since it needs its answer and the answer
832/// would go to the zombie.
833fn asks_liveness(cfg: &ZondConfig) -> bool {
834    !cfg.assume_up && cfg.idle_scan.is_none()
835}
836
837/// Whether a port scan's liveness pass earns the probes it costs, so that the
838/// port phase runs behind it.
839///
840/// A dead address costs the pass a handful of probes and the port scan one per
841/// port, so the pass only saves anything when the port scan is the dearer of the
842/// two. The pass asks each address a fixed set (the common five, up to a few of
843/// the scan's own ports, and one SCTP probe where the scan names SCTP; see
844/// [`SynPorts`]), so a scan naming no more ports per address than that drops the
845/// pass and lets the port probes stand in for it. An answer on any port, open or
846/// closed, is the host answering, and an address that answers nothing is left
847/// [`Unknown`](crate::model::host::HostStatus::Unknown) with its targets settled
848/// by the port scan, as [`ZondConfig::assume_up`] leaves them.
849///
850/// Three things keep the pass even for a small scan:
851///
852/// - **A TCP technique other than SYN.** Only a SYN draws an answer from every
853///   port of a live host: a SYN+ACK where it listens, a reset where it does not.
854///   FIN, null and Christmas-tree probes draw nothing from an open port, so a
855///   host with only open ports would read as silent, and those techniques have
856///   no connect form to fall back on where no raw socket or frame reaches.
857/// - **A scan that names a UDP port.** A UDP probe to a dead address waits out a
858///   rate-limited ICMP unreachable or a full timeout, while the pass settles the
859///   address with cheap TCP or link-layer probes.
860/// - **A target on this host's own segment.** The pass reaches it with one ARP
861///   or neighbour-discovery packet, which a live stack answers whatever it
862///   filters above the link, so it finds hosts a port scan of a few silent ports
863///   would miss. Whether any target is on-link is read from the discovery plan,
864///   which sends nothing.
865///
866/// `false` for an [idle scan](ZondConfig::idle_scan) and for
867/// [`assume_up`](ZondConfig::assume_up); see [`asks_liveness`]. `false` too where
868/// the [excluded ports](ZondConfig::excluded_ports) leave the pass no port to
869/// ask, since it would then leave every address it reaches by TCP unscanned.
870fn liveness_earns_its_place(cfg: &ZondConfig, map: &TargetMap) -> bool {
871    use crate::model::port::Protocol;
872
873    if !asks_liveness(cfg) {
874        return false;
875    }
876
877    let asked = SynPorts::for_scan(&tcp_ports_of(map))
878        .excluding(&cfg.excluded_ports)
879        .len()
880        + usize::from(orchestrator::sctp_discovery_port(map, &cfg.excluded_ports).is_some());
881    if asked == 0 {
882        return false;
883    }
884
885    if !cfg.tcp_technique.has_connect_fallback() {
886        return true;
887    }
888
889    if map.names(Protocol::Udp) {
890        return true;
891    }
892
893    // The pass pays as soon as one unit asks more ports than the pass would.
894    let per_address = map
895        .units
896        .iter()
897        .map(crate::model::target::TargetSet::port_count)
898        .max()
899        .unwrap_or(0);
900    if per_address > asked {
901        return true;
902    }
903
904    reaches_a_local_segment(cfg, map)
905}
906
907/// Why a port scan under `cfg` runs with no liveness pass, or `None` where it
908/// runs one; `runs_liveness` is [`liveness_earns_its_place`]'s verdict.
909///
910/// An idle scan first, since it forbids the pass whatever else was set; then
911/// the caller's [`assume_up`](ZondConfig::assume_up); otherwise the port probes
912/// cost no more than asking first.
913fn liveness_skip(cfg: &ZondConfig, runs_liveness: bool) -> Option<LivenessSkip> {
914    if runs_liveness {
915        None
916    } else if cfg.idle_scan.is_some() {
917        Some(LivenessSkip::IdleScan)
918    } else if cfg.assume_up {
919        Some(LivenessSkip::AssumeUp)
920    } else {
921        Some(LivenessSkip::PortsNoDearer)
922    }
923}
924
925/// The most addresses a scan is checked for on-link targets across.
926///
927/// A `/23` is already a large segment, and this leaves generous room past that.
928/// Building the discovery plan classifies every address, so a wide routed range
929/// skips that walk.
930const ON_LINK_CHECK_CEILING: u128 = 1 << 13;
931
932/// Whether the discovery plan for `map` reaches any target at the link layer,
933/// where liveness is one exact ARP or neighbour-discovery packet.
934///
935/// Builds the plan, which sends nothing, and reads it. False for an
936/// unprivileged run, which has no link-layer strategy, and for one whose
937/// targets are all behind a gateway or on loopback.
938///
939/// A range wider than a segment could be is taken as routed without building
940/// the plan; see [`ON_LINK_CHECK_CEILING`].
941fn reaches_a_local_segment(cfg: &ZondConfig, map: &TargetMap) -> bool {
942    match map.gross_ips() {
943        Ok(count) if count <= ON_LINK_CHECK_CEILING => {}
944        _ => return false,
945    }
946
947    let mut ips = IpSet::new();
948    for unit in &map.units {
949        for range in unit.ips().v4() {
950            ips.push_v4_range(*range);
951        }
952        for range in unit.ips().v6() {
953            ips.push_v6_range(*range);
954        }
955    }
956    ips.canonicalize();
957
958    let plan = plan::DiscoveryPlan::build(ips, Scope::Targeted, &cfg.exclusions, &cfg.send_source);
959    plan.steps()
960        .iter()
961        .any(|step| matches!(step, plan::DiscoveryStep::Local { .. }))
962}
963
964/// The configuration a scan actually runs under, given that an idle scan sends
965/// the target nothing from this host.
966///
967/// Service detection, the detection corpus, active OS probing, the route trace,
968/// filter characterisation, IP-protocol probing and TLS enumeration all contact
969/// the target from this host, which an idle scan exists to avoid. Under an idle
970/// scan each is turned down to the level that sends the target nothing: service
971/// detection off, the detection ceiling and OS level held to gathered evidence,
972/// and the rest cleared. The target then sees only the forged probes.
973///
974/// [`record_idle_refusals`] files a refusal for each muted pass the caller
975/// asked for, so the report says why it was declined. Returned unchanged for a
976/// scan that is not an idle one.
977fn running_under(cfg: &ZondConfig) -> ZondConfig {
978    if cfg.idle_scan.is_none() {
979        return cfg.clone();
980    }
981
982    let mut muted = cfg.clone();
983    muted.service_detection = crate::config::ServiceDetection::Off;
984    if muted.detection.ceiling() > Some(crate::model::finding::DetectionClass::Passive) {
985        muted.detection =
986            crate::config::DetectionEnvelope::up_to(crate::model::finding::DetectionClass::Passive);
987    }
988    if muted.os_detection.is_active() {
989        muted.os_detection = crate::config::OsDetection::Passive;
990    }
991    muted.traceroute = false;
992    muted.characterise = false;
993    muted.ip_protocols.clear();
994    muted.tls_enumeration = false;
995    muted
996}
997
998/// Records, once, why each after-port pass an idle scan turns off was turned
999/// off, reading `cfg` as the caller set it.
1000///
1001/// Each pass the caller asked for that would contact the target directly is
1002/// filed as a refusal; see
1003/// [`RefusedStep::pass_not_in_an_idle_scan`](plan::RefusedStep::pass_not_in_an_idle_scan).
1004/// Service detection is on by default, and a level the caller set cannot be
1005/// told from the default, so it gets a line at verbosity one in place of a
1006/// refusal.
1007fn record_idle_refusals(cfg: &ZondConfig, ctx: &ScanContext) {
1008    use crate::model::finding::DetectionClass;
1009    use crate::report::ScannerKind;
1010    use plan::RefusedStep;
1011
1012    if cfg.idle_scan.is_none() {
1013        return;
1014    }
1015
1016    if cfg.service_detection.connects() {
1017        crate::info!(verbosity = 1, "service detection skipped (idle scan)");
1018    }
1019    if cfg.detection.ceiling() > Some(DetectionClass::Passive) {
1020        ctx.record_refusal(
1021            RefusedStep::pass_not_in_an_idle_scan(ScannerKind::Detection, "active detection")
1022                .into(),
1023        );
1024    }
1025    if cfg.os_detection.is_active() {
1026        ctx.record_refusal(
1027            RefusedStep::pass_not_in_an_idle_scan(ScannerKind::OsSeries, "OS probing").into(),
1028        );
1029    }
1030    if cfg.traceroute {
1031        ctx.record_refusal(
1032            RefusedStep::pass_not_in_an_idle_scan(ScannerKind::Routed, "route trace").into(),
1033        );
1034    }
1035    if cfg.characterise {
1036        ctx.record_refusal(
1037            RefusedStep::pass_not_in_an_idle_scan(ScannerKind::Routed, "filter characterisation")
1038                .into(),
1039        );
1040    }
1041    if !cfg.ip_protocols.is_empty() {
1042        ctx.record_refusal(
1043            RefusedStep::pass_not_in_an_idle_scan(ScannerKind::Routed, "IP-protocol probe").into(),
1044        );
1045    }
1046    if cfg.tls_enumeration {
1047        ctx.record_refusal(
1048            RefusedStep::pass_not_in_an_idle_scan(ScannerKind::Service, "TLS enumeration").into(),
1049        );
1050    }
1051}
1052
1053/// How many address-and-port pairs a port scan plans to probe, or `None` where
1054/// they cannot all be numbered.
1055///
1056/// [`TargetIndex`] stops numbering at the first unit it cannot count whole, so
1057/// its total is used only when it reports the numbering complete.
1058fn planned_targets(map: &TargetMap) -> Option<u64> {
1059    let index = TargetIndex::of(map);
1060    index.is_complete().then(|| index.total())
1061}
1062
1063/// Runs a discovery sweep against an existing context.
1064///
1065/// The body of [`discover`]. It takes a context so that a caller journalling
1066/// the sweep can seed it and keep a handle on it.
1067fn spawn_discovery(
1068    mut targets: IpSet,
1069    capture_links: Vec<Zone>,
1070    cfg: &ZondConfig,
1071    ctx: ScanContext,
1072) -> JoinHandle<ScanReport> {
1073    // A sitting with no address left sends nothing, unless it sweeps a
1074    // segment; see `sitting_probes`.
1075    let sends = !targets.is_empty() || cfg.segment_sweep;
1076    let caps = ScanCapabilities::resolve(
1077        cfg,
1078        sends.then(orchestrator::Probing::sweep),
1079        &targets,
1080        interface::FrameSender::Sweep,
1081    );
1082
1083    // Narrows `targets` as it records them, so nothing below can probe an
1084    // excluded address. Addresses a sweep finds for itself are gated on the
1085    // context.
1086    let scope = address_scope(&mut targets, &ctx);
1087    let recorder =
1088        PhaseRecorder::start(ScanKind::Discovery, caps.privilege, scope, cfg).opening_in(&ctx);
1089
1090    let reach = if cfg.segment_sweep {
1091        Scope::Sweep
1092    } else {
1093        Scope::Targeted
1094    };
1095    let cfg = cfg.clone();
1096    let held_back = crate::system::descriptors::hold_back();
1097
1098    tokio::spawn(async move {
1099        // Held for as long as the sweep runs; see `descriptors::hold_back`.
1100        let _held_back = held_back;
1101        // Before the sweep opens a capture, so each listens only where a
1102        // reply to it can arrive.
1103        ctx.capture_on(capture_links);
1104        ctx.enter_stage(Stage::Discovery, None);
1105        // A sweep has no ports of its own, so only the common ones and no SCTP.
1106        run_discovery(targets, reach, caps, &cfg, &ctx, SynPorts::common(), None).await;
1107        // Only the echo probe: the series probe needs a port of known state.
1108        orchestrator::run_active_os_probe(&ctx, cfg.os_detection, cfg.probe_tuning(), caps).await;
1109        // With no known ports, every trace here is made of echoes.
1110        orchestrator::run_traceroute(&ctx, &cfg, caps).await;
1111        orchestrator::run_characterise(&ctx, &cfg, caps).await;
1112        orchestrator::run_ip_protocols(&ctx, &cfg).await;
1113        ctx.enter_stage(Stage::Finishing, None);
1114        // After every strategy that could add an address.
1115        vantage::attribute(&ctx);
1116        orchestrator::correlate(&ctx, cfg.service_detection).await;
1117        recorder.finish_last(ctx)
1118    })
1119}
1120
1121/// The exclusions `ctx` holds a phase's targets to: the addresses written,
1122/// and every address a machine they name answers at, as far as the scan has
1123/// learned it. See
1124/// [the machine an address names](crate::model::exclusion#an-address-names-a-machine).
1125fn machine_policy(ctx: &ScanContext) -> crate::model::exclusion::Exclusions {
1126    ctx.exclusions.widened(ctx.withheld_by_hardware())
1127}
1128
1129/// Narrows `targets`, the addresses a phase was handed, to what the
1130/// exclusions let it ask, and records what that cost as the phase's scope.
1131///
1132/// Held to [`machine_policy`], so an address the neighbour tables tie to an
1133/// excluded machine is sent nothing and listed among the excluded. One the plan
1134/// numbers is settled as withheld, or every later sitting would owe it and drop
1135/// it again.
1136fn address_scope(targets: &mut IpSet, ctx: &ScanContext) -> TargetScope {
1137    let tied = ctx.withheld_by_hardware();
1138    for address in &tied {
1139        if targets.contains(address) {
1140            ctx.settle_withheld(*address);
1141        }
1142    }
1143    TargetScope::from_ip_set(targets, &ctx.exclusions.widened(tied))
1144}
1145
1146/// Runs one discovery pass over `targets` to completion, against an existing
1147/// context.
1148///
1149/// Shared by [`discover`] and by the liveness phase of [`scan`], so both
1150/// establish presence the same way.
1151///
1152/// `reach` is the difference between the two: a sweep may go beyond the
1153/// addresses it was given, and a port scan's liveness check never does.
1154///
1155/// `syn_ports` is what every address a TCP probe reaches is asked about, by a
1156/// routed SYN sweep and a connect sweep alike: the common five for a sweep, and
1157/// those plus some of the scan's own ports for a port scan's liveness pass. See
1158/// [`SynPorts`] for why a host behind a filter needs the second. Held here to
1159/// [`ZondConfig::excluded_ports`], so no liveness probe goes to a port the scan
1160/// may not probe.
1161///
1162/// `sctp_port` adds an INIT sweep beside the SYN one, for a port scan whose
1163/// ports name SCTP. `None` otherwise, since an SCTP sweep costs a second raw
1164/// socket and a second capture.
1165///
1166/// A raw sweep still reaches some targets by connect: loopback and anything
1167/// nothing routes to, and with frames only, whatever a frame cannot reach. The
1168/// phase records which, since its privilege reads as raw and the evidence at
1169/// those addresses is not.
1170async fn run_discovery(
1171    targets: IpSet,
1172    reach: Scope,
1173    caps: ScanCapabilities,
1174    cfg: &ZondConfig,
1175    ctx: &ScanContext,
1176    syn_ports: SynPorts,
1177    sctp_port: Option<u16>,
1178) {
1179    let syn_ports = syn_ports.excluding(&cfg.excluded_ports);
1180    if caps.privilege.is_raw() {
1181        let unframed =
1182            caps.beyond_frames(&targets, &cfg.send_source, interface::FrameSender::Sweep);
1183        let mut plan =
1184            plan::DiscoveryPlan::build(targets, reach, &cfg.exclusions, &cfg.send_source);
1185        plan.connect_instead(&unframed.targets);
1186        plan.asking_tcp(syn_ports);
1187        for address in plan.refused_by_route().iter() {
1188            ctx.note_refused_by_route(address);
1189        }
1190        for address in plan.withheld().iter() {
1191            ctx.note_withheld_neighbour(address);
1192        }
1193        if let Some(port) = sctp_port {
1194            plan.also_over_sctp(port);
1195        }
1196        orchestrator::reached_by_connect(&plan, unframed, ctx);
1197        let enrichment = Enrichment::spawn(plan, ctx, caps, cfg.probe_tuning()).await;
1198        finish_enrichment(Some(enrichment), caps, ctx, rdns::Unheard::Skipped).await;
1199    } else {
1200        let targets = orchestrator::walkable(targets, ctx);
1201        if syn_ports.is_empty() {
1202            ctx.record_refusal(
1203                plan::RefusedStep::every_discovery_port_excluded(ScannerKind::Connect).into(),
1204            );
1205        } else if let Err(error) =
1206            strategy::connect::discover_on(targets, ctx.clone(), &cfg.evasion, syn_ports).await
1207        {
1208            ctx.record_failure(ScannerKind::Connect, error.to_string());
1209        }
1210        finish_enrichment(None, caps, ctx, rdns::Unheard::Skipped).await;
1211    }
1212
1213    orchestrator::run_passive_os_identification(ctx, cfg.os_detection);
1214}
1215
1216/// Every TCP port any unit of `map` names, as one set.
1217///
1218/// One set for the whole liveness pass, because one sweep asks every address
1219/// the same ports. The SCTP sweep's port is chosen the same way.
1220fn tcp_ports_of(map: &TargetMap) -> PortSet {
1221    map.units
1222        .iter()
1223        .fold(PortSet::new(), |named, unit| named.union(unit.ports()))
1224}
1225
1226/// What a listening phase reads, and for how long.
1227///
1228/// A listener is aimed at a **link**, and cannot narrow what it hears, so the
1229/// scope controls what may be recorded.
1230///
1231/// A caller who wants every link names them; see
1232/// [`system::interface`](crate::system::interface) for how to find them.
1233#[must_use]
1234#[derive(Debug, Clone)]
1235pub struct ListenScope {
1236    links: Vec<crate::model::ip::scoped::Zone>,
1237    recording: strategy::passive::Recording,
1238    until: Until,
1239}
1240
1241/// When a listening phase stops.
1242///
1243/// A listener asks nothing and so is never finished on its own; this decides
1244/// when it ends.
1245#[non_exhaustive]
1246#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
1247pub enum Until {
1248    /// It runs until the caller stops it through
1249    /// [`ScanHandle::abort`](crate::scanner::handle::ScanHandle::abort).
1250    ///
1251    /// The default, suited to a sensor that runs as a service.
1252    #[default]
1253    Stopped,
1254    /// It runs for this long and then closes.
1255    ///
1256    /// For a bounded sample, such as an inventory of what a segment says over
1257    /// ten minutes.
1258    Elapsed(std::time::Duration),
1259}
1260
1261impl ListenScope {
1262    /// Listens on `links` until stopped, recording the machines attached to
1263    /// them.
1264    ///
1265    /// A link carries evidence about every remote host its traffic reaches: on a
1266    /// mirror port, every server a laptop connects to is a real host with an
1267    /// open port, and on a busy uplink that would be most of the report.
1268    /// [`recording_everything`](Self::recording_everything) records those too.
1269    pub fn on(links: Vec<crate::model::ip::scoped::Zone>) -> Self {
1270        Self {
1271            links,
1272            recording: strategy::passive::Recording::Attached,
1273            until: Until::Stopped,
1274        }
1275    }
1276
1277    /// Records every machine heard, wherever it lives.
1278    ///
1279    /// Shows which machines elsewhere this network depends on, and what they
1280    /// answer. Nothing extra is captured; only what reaches the report changes.
1281    pub fn recording_everything(mut self) -> Self {
1282        self.recording = strategy::passive::Recording::Everything;
1283        self
1284    }
1285
1286    /// Records findings only about `addresses`.
1287    ///
1288    /// Everything on the link is still heard; anything outside `addresses` is
1289    /// dropped before it reaches the store.
1290    pub fn recording_only(mut self, addresses: IpSet) -> Self {
1291        self.recording = strategy::passive::Recording::Only(addresses);
1292        self
1293    }
1294
1295    /// Stops after `span`.
1296    pub fn for_at_most(mut self, span: std::time::Duration) -> Self {
1297        self.until = Until::Elapsed(span);
1298        self
1299    }
1300
1301    /// The links this phase reads.
1302    pub fn links(&self) -> &[crate::model::ip::scoped::Zone] {
1303        &self.links
1304    }
1305
1306    /// When it stops.
1307    pub fn until(&self) -> Until {
1308        self.until
1309    }
1310}
1311
1312/// Reads what a link already carries, and concludes from it. Sends nothing.
1313///
1314/// The third phase, beside [`discover`] and [`scan`]. It is for networks that
1315/// may not be probed (industrial and clinical segments, production under change
1316/// control, engagements without an authorised scan window) and for findings no
1317/// probe can obtain: which switch port this machine is on, which VLANs a link
1318/// carries, what a device says about itself while asking for an address.
1319///
1320/// # What it may conclude
1321///
1322/// Only positive claims. With nothing sent, nothing can time out, so an address
1323/// it never heard from may be absent, silent, behind a switch that never
1324/// forwarded this way, or on a VLAN this link does not carry. It records hosts
1325/// as up and never as down, adds roles and never removes them, and its phase
1326/// covers **no address at all**, so a [`diff`](crate::diff) cannot read a host
1327/// that stayed quiet as one that went away.
1328///
1329/// # What it will not see
1330///
1331/// On a switched network an unmirrored listener sees broadcast and multicast in
1332/// full and very little unicast, since the switch forwards a conversation only
1333/// out the ports that lead to its hosts. ARP, DHCP, mDNS, router advertisements,
1334/// LLDP and CDP are enough for an asset and topology inventory; endpoints and
1335/// flows need a mirror port, a tap, or a position traffic transits.
1336///
1337/// A wide filter on a busy link drops frames, and the report gives the drop
1338/// count.
1339///
1340/// # Stopping
1341///
1342/// [`Until::Stopped`] runs until
1343/// [`ScanHandle::abort`](crate::scanner::handle::ScanHandle::abort) is called on
1344/// the session's handle. The returned [`ScanTask`] resolves when it stops, with
1345/// the [`ScanReport`] describing what was heard.
1346///
1347/// [`ZondConfig::scan_timeout`](crate::config::ZondConfig::scan_timeout) also
1348/// applies; the watch ends at whichever of it and the scope's [`Until`] comes
1349/// first.
1350pub async fn listen(
1351    scope: ListenScope,
1352    cfg: &ZondConfig,
1353) -> Result<(ScanSession, ScanTask), ScanError> {
1354    let (session, ctx) = ScanSession::builder()
1355        .excluding(cfg.exclusions.clone())
1356        .naming(cfg.target_names.clone())
1357        .host_timeout(cfg.host_timeout)
1358        .scan_timeout(cfg.scan_timeout)
1359        .host_probe_interval(cfg.host_probe_interval)
1360        .probe_interval(cfg.probe_interval)
1361        .staging(vec![Stage::Listening])
1362        .build();
1363    let handle = spawn_listen(scope, cfg, ctx);
1364    let stop = session.handle().clone();
1365    Ok((session, ScanTask::new(handle, stop)))
1366}
1367
1368/// [`listen`], writing down what it hears, so that a watch cut short keeps what
1369/// it found.
1370///
1371/// As with [`scan_with_journal`], journalling is the caller's choice: hand this
1372/// a journal and the watch is recorded; [`listen`] writes nothing to disk.
1373///
1374/// # Resuming a watch appends a sitting
1375///
1376/// A sweep and a port scan enumerate their targets, and continuing one skips
1377/// what is settled. A listener enumerates nothing, so there is no cursor and
1378/// nothing to skip. Resuming restores the findings of every earlier sitting
1379/// before this one starts, and the report describes the whole watch: a listener
1380/// left running for a week across three restarts produces one record of the
1381/// week.
1382///
1383/// [`Plan::listen`](crate::journal::manifest::Plan::listen) explains why the
1384/// links alone identify the job.
1385///
1386/// # A watch records no options
1387///
1388/// A scan's journal holds every sitting to the options its first ran under;
1389/// see [`JobOptions`](crate::journal::manifest::JobOptions). A watch sends no
1390/// probe, so no technique, retry policy, evasion profile or probing pass
1391/// affects what it hears. Its settings (OS reading of heard traffic, service
1392/// correlation) only decide how the traffic is read, and each sitting's phase
1393/// records them, so a resumed watch is not held to earlier options.
1394#[cfg(feature = "journal-format")]
1395pub async fn listen_with_journal(
1396    scope: ListenScope,
1397    cfg: &ZondConfig,
1398    journal: crate::journal::Journal,
1399) -> Result<(ScanSession, ScanTask), ScanError> {
1400    let journal = accepted(journal, |journal| {
1401        if journal.manifest().kind() != ScanKind::Listen {
1402            return Err(ScanError::WrongPhase);
1403        }
1404        Ok(())
1405    })?;
1406
1407    let (session, ctx) = ScanSession::builder()
1408        .excluding(cfg.exclusions.clone())
1409        .naming(cfg.target_names.clone())
1410        .host_timeout(cfg.host_timeout)
1411        .scan_timeout(cfg.scan_timeout)
1412        .host_probe_interval(cfg.host_probe_interval)
1413        .probe_interval(cfg.probe_interval)
1414        .staging(vec![Stage::Listening])
1415        .build();
1416
1417    // Before the watch starts, so a caller reading the session sees every
1418    // earlier sitting's hosts immediately and the report describes the job.
1419    ctx.restore_hosts(journal.restored());
1420    let earlier = journal.earlier_phases().to_vec();
1421
1422    let ticker = checkpoint::spawn_checkpoints(journal, ctx.progress());
1423    let handle = spawn_listen(scope, cfg, ctx);
1424
1425    let stop = session.handle().clone();
1426    Ok((
1427        session,
1428        ScanTask::journalling(handle, stop, ticker, earlier),
1429    ))
1430}
1431
1432/// Runs a listening phase against an existing context.
1433fn spawn_listen(scope: ListenScope, cfg: &ZondConfig, ctx: ScanContext) -> JoinHandle<ScanReport> {
1434    let cfg = cfg.clone();
1435
1436    tokio::spawn(async move {
1437        // The capture opens before the phase does, because whether it opened
1438        // decides the phase's privilege field. That is not the same as running
1439        // as root: `pcap` reads a link for a user in the `access_bpf` group on
1440        // macOS and for a binary with `cap_net_raw` on Linux. See
1441        // `listening_privilege`. A listener has no connect fallback.
1442        ctx.enter_stage(Stage::Listening, None);
1443
1444        let opened =
1445            strategy::passive::PassiveListener::open(&scope.links, scope.recording, ctx.clone());
1446
1447        // After the open, so the phase's clock covers only the listening.
1448        let recorder = PhaseRecorder::start(
1449            ScanKind::Listen,
1450            listening_privilege(opened.as_ref().err()),
1451            TargetScope::listening_on(scope.links.clone(), &cfg.exclusions),
1452            &cfg,
1453        )
1454        .opening_in(&ctx);
1455
1456        match opened {
1457            Ok(listener) => {
1458                let mut listener = listener.detecting_os(cfg.os_detection);
1459                if let Until::Elapsed(span) = scope.until {
1460                    // Not through the abort signal, which means a caller asked
1461                    // and tells a front end the run was cut short.
1462                    listener = listener.stopping_after(span);
1463                }
1464
1465                if let Err(error) = listener.observe().await {
1466                    ctx.record_failure(ScannerKind::Passive, error.to_string());
1467                }
1468            }
1469            Err(error) => ctx.record_failure(ScannerKind::Passive, error.to_string()),
1470        }
1471
1472        vantage::attribute(&ctx);
1473        orchestrator::correlate(&ctx, cfg.service_detection).await;
1474        recorder.finish_last(ctx)
1475    })
1476}
1477
1478/// The privilege a listener held, read off what its capture was told, with
1479/// `refusal` being why no link could be captured on.
1480///
1481/// A listener that opened a capture held what it needed; one refused for want
1482/// of privilege did not. Any other refusal (a link that would not compile the
1483/// filter, is down or carries framing nothing here parses, or a reader thread
1484/// that would not start) comes after the permission check `libpcap` makes
1485/// before binding a link, so the process held the privilege. Where no link was
1486/// tried at all, the process's own privilege is recorded, as for a scan phase.
1487fn listening_privilege(refusal: Option<&strategy::StrategyError>) -> Privilege {
1488    use crate::transport::capture::CaptureError;
1489
1490    match refusal {
1491        None => Privilege::Raw,
1492        Some(strategy::StrategyError::Capture(CaptureError::NoInterface { refused }))
1493            if refused.is_empty() =>
1494        {
1495            Privilege::current()
1496        }
1497        Some(strategy::StrategyError::Capture(error)) if error.is_denied() => Privilege::Connect,
1498        Some(strategy::StrategyError::Capture(_)) => Privilege::Raw,
1499        Some(_) => Privilege::current(),
1500    }
1501}
1502
1503/// Takes out of `target_map` every target [`scan`] withholds: a link-local
1504/// range that names no interface, an address two link-local ranges name on two
1505/// different interfaces, and an IPv6 range too wide to walk one address at a
1506/// time.
1507///
1508/// A scan takes these out before it numbers its plan and names each in its
1509/// report as refused. To measure what a scan will cost before starting it, apply
1510/// this to a copy, as with [`TargetMap::withhold_ports`].
1511pub fn withhold_unprobeable(target_map: &mut TargetMap) {
1512    target_map.take_unprobeable(&[], interface::is_enumerable);
1513}
1514
1515/// Probes a known set of targets for open ports.
1516///
1517/// Every address is first probed for liveness as [`discover`] would probe it,
1518/// and only the addresses that answer are port-scanned, so an address with
1519/// nothing at it costs a handful of probes. The pass is skipped where the port
1520/// probes would cost no more.
1521///
1522/// The liveness phase probes only the addresses it was given
1523/// ([`Scope::Targeted`]), so scanning one host does not wake its neighbours.
1524/// `cfg.segment_sweep` is ignored here.
1525///
1526/// [`ZondConfig::assume_up`] skips the phase and scans every target, which a
1527/// host behind a firewall that answers nothing needs. An
1528/// [idle scan](ZondConfig::idle_scan) skips it too, along with every later pass
1529/// that would contact the target directly (service detection through TLS
1530/// enumeration), so the target hears nothing from this host but the forged
1531/// probes. The report says which passes were declined and why.
1532///
1533/// The [`ScanReport`] carries a phase for each: the liveness pass as
1534/// [`ScanKind::Discovery`] and the ports as [`ScanKind::PortScan`].
1535///
1536/// With root privileges, every probe is a raw TCP SYN sent from the source
1537/// address this host would route the target through, and
1538/// [`TcpPortScanner`](strategy::ports::TcpPortScanner) reads the port's state
1539/// from a single reply. Without root, or with no address to probe from, probes
1540/// fall back to one TCP connect attempt per target.
1541///
1542/// `detections` is the corpus the detection phase runs. Pass
1543/// [`Detections::embedded`](crate::detect::Detections::embedded) for the ones this
1544/// build ships, or a [`Detections::builder`](crate::detect::Detections::builder)
1545/// result to add your own. The [envelope](ZondConfig::detection) still decides
1546/// what each detection may do to the target. A [`Detections`] is cheap to clone,
1547/// so one corpus serves many scans.
1548pub async fn scan(
1549    target_map: TargetMap,
1550    cfg: &ZondConfig,
1551    detections: Detections,
1552) -> Result<(ScanSession, ScanTask), ScanError> {
1553    cfg.evasion.validate()?;
1554
1555    let mut target_map = target_map;
1556    target_map.withhold_ports(&cfg.excluded_ports);
1557    let withheld = orchestrator::withhold_unprobeable_targets(&mut target_map);
1558    let capture_links = capture_plan(&plan_addresses(&target_map), cfg)?;
1559    let planned = planned_targets(&target_map);
1560    let runs_liveness = liveness_earns_its_place(cfg, &target_map);
1561
1562    let (session, ctx) = ScanSession::builder()
1563        .excluding(cfg.exclusions.clone())
1564        .naming(cfg.target_names.clone())
1565        .host_timeout(cfg.host_timeout)
1566        .scan_timeout(cfg.scan_timeout)
1567        .host_probe_interval(cfg.host_probe_interval)
1568        .probe_interval(cfg.probe_interval)
1569        .send_source(cfg.send_source.clone())
1570        .listening_only_to(cfg.listen_only_ports.clone())
1571        .detections(detections)
1572        .planning(Stage::Ports, planned)
1573        .staging(scan_stages(cfg, runs_liveness))
1574        .build();
1575    let handle = spawn_scan(
1576        target_map,
1577        withheld,
1578        capture_links,
1579        cfg,
1580        ctx,
1581        Checkpoint::default(),
1582        runs_liveness,
1583    );
1584    let stop = session.handle().clone();
1585    Ok((session, ScanTask::new(handle, stop)))
1586}
1587
1588/// [`scan`], recording its progress so that an interrupted run can be continued.
1589///
1590/// Journalling is the caller's choice: the engine touches no filesystem it was
1591/// not pointed at (see `import::settings`). A front end that wants every scan
1592/// resumable opens a journal for every scan.
1593///
1594/// A journal from [`Journal::resume`](crate::journal::Journal::resume) knows
1595/// what an earlier run settled, and this scan skips it. The dispatcher still
1596/// walks the whole plan and keeps each target's original position, emitting
1597/// only what is left, so both runs count the same targets.
1598///
1599/// So `target_map`, less what `cfg`'s exclusions withhold, has to be the plan
1600/// the journal was counted in, and this process has to hold the privilege it
1601/// was counted under. Anything else is refused as [`ScanError::PlanChanged`]
1602/// before anything is sent. The recorded plan,
1603/// [`JournalManifest::recorded`](crate::journal::manifest::JournalManifest::recorded),
1604/// always matches.
1605///
1606/// Progress is checkpointed on a timer, and once more when the returned
1607/// [`ScanTask`] is joined, which also releases the journal's lock.
1608/// [`Checkpoint::write_atomically`](crate::journal::cursor::Checkpoint::write_atomically)
1609/// documents what that survives.
1610///
1611/// Findings and phases are recorded alongside the progress, so a resumed scan
1612/// starts from what earlier runs found and its report describes the whole job:
1613/// one phase per sitting, each with its own timings, settings and statistics.
1614///
1615/// `detections` is the corpus to run, as for [`scan`].
1616#[cfg(feature = "journal-format")]
1617pub async fn scan_with_journal(
1618    target_map: TargetMap,
1619    cfg: &ZondConfig,
1620    detections: Detections,
1621    journal: crate::journal::Journal,
1622) -> Result<(ScanSession, ScanTask), ScanError> {
1623    let mut capture_links = Vec::new();
1624    let journal = accepted(journal, |journal| {
1625        cfg.evasion.validate()?;
1626        // Over the plan as the sitting will number it, the same in every
1627        // sitting.
1628        let mut probed = target_map.clone();
1629        probed.withhold_ports(&cfg.excluded_ports);
1630        orchestrator::withhold_unprobeable_targets(&mut probed);
1631        capture_links = capture_plan(&plan_addresses(&probed), cfg)?;
1632        if journal.manifest().kind() != ScanKind::PortScan {
1633            return Err(ScanError::WrongPhase);
1634        }
1635        let technique = journal.manifest().technique();
1636        let this_run =
1637            crate::journal::manifest::Plan::port_scan(&target_map, &cfg.exclusions, technique);
1638        counted_as_recorded(journal, &this_run)?;
1639        under_the_recorded_options(journal, cfg)
1640    })?;
1641    let cfg = &under_the_recorded_technique(&journal, cfg);
1642    let journal = recording_options(journal, cfg);
1643    // Numbered without the ports the job excluded, so every sitting numbers
1644    // alike; ports this sitting adds are passed over in place. See `JobOptions`.
1645    let numbered_without = journal.options().map_or_else(
1646        || cfg.excluded_ports.clone(),
1647        crate::journal::manifest::JobOptions::excluded_ports,
1648    );
1649    let withheld_ports = cfg.excluded_ports.difference(&numbered_without);
1650    let mut target_map = target_map;
1651    target_map.withhold_ports(&numbered_without);
1652    let withheld = orchestrator::withhold_unprobeable_targets(&mut target_map);
1653    let runs_liveness = liveness_earns_its_place(cfg, &target_map);
1654    let finished = journal.finished_hosts().unwrap_or_else(|e| {
1655        crate::warn!("passes rerun for every host ({e})");
1656        Default::default()
1657    });
1658    // Numbered as the port phase numbers it, in what the exclusions leave.
1659    let mut numbered = target_map.clone();
1660    cfg.exclusions.withhold_targets(&mut numbered);
1661    let asked = orchestrator::unsettled_ips(&numbered, journal.resume_point());
1662
1663    let (session, ctx) = ScanSession::builder()
1664        .excluding(cfg.exclusions.clone())
1665        .naming(cfg.target_names.clone())
1666        .host_timeout(cfg.host_timeout)
1667        .scan_timeout(cfg.scan_timeout)
1668        .host_probe_interval(cfg.host_probe_interval)
1669        .probe_interval(cfg.probe_interval)
1670        .send_source(cfg.send_source.clone())
1671        .listening_only_to(cfg.listen_only_ports.clone())
1672        .withholding_ports(withheld_ports)
1673        .resuming(journal.resume_point())
1674        .finished(finished, asked)
1675        .detections(detections)
1676        .planning(Stage::Ports, planned_targets(&target_map))
1677        .staging(scan_stages(cfg, runs_liveness))
1678        // The job's order, from the manifest; see `discover_with_journal`.
1679        .ordering(journal.manifest().order_seed)
1680        .build();
1681
1682    // Before the scan starts, so a caller watching the session sees the earlier
1683    // sittings' hosts immediately.
1684    ctx.restore_hosts(journal.restored());
1685
1686    let earlier = journal.earlier_phases().to_vec();
1687    let resume_point = journal.resume_point().clone();
1688
1689    // A narrow handle: a checkpoint task holding the event sender would keep
1690    // the stream open after the scan ended. See `ScanContext::progress`.
1691    let ticker = checkpoint::spawn_checkpoints(journal, ctx.progress());
1692    let handle = spawn_scan(
1693        target_map,
1694        withheld,
1695        capture_links,
1696        cfg,
1697        ctx,
1698        resume_point,
1699        runs_liveness,
1700    );
1701
1702    let stop = session.handle().clone();
1703    Ok((
1704        session,
1705        ScanTask::journalling(handle, stop, ticker, earlier),
1706    ))
1707}
1708
1709/// What a port scan's sitting probes with, or `None` for one an earlier
1710/// sitting left nothing to ask.
1711///
1712/// `numbered` is `target_map` less what the exclusions withhold, which is what
1713/// `settled` counts. A sitting with no target left sends nothing, so it names
1714/// no probes and no privilege.
1715fn sitting_probes(
1716    cfg: &ZondConfig,
1717    target_map: &TargetMap,
1718    numbered: &TargetMap,
1719    settled: &Checkpoint,
1720) -> Option<orchestrator::Probing> {
1721    (!orchestrator::unsettled_ips(numbered, settled).is_empty())
1722        .then(|| orchestrator::Probing::ports(cfg, target_map))
1723}
1724
1725/// Runs both phases of a port scan against an existing context.
1726///
1727/// The body of [`scan`]. It takes a context so that a caller journalling the
1728/// scan can seed it from an earlier run and keep a handle on it.
1729///
1730/// `settled` is what an earlier sitting already covered, empty for a fresh
1731/// scan. `withheld` is what
1732/// [`orchestrator::withhold_unprobeable_targets`] took out of `target_map`,
1733/// refused in the port phase's record. `capture_links` is where its captures
1734/// listen, as [`capture_plan`] counted them.
1735#[allow(clippy::too_many_arguments)]
1736fn spawn_scan(
1737    target_map: TargetMap,
1738    withheld: orchestrator::Withheld,
1739    capture_links: Vec<Zone>,
1740    cfg: &ZondConfig,
1741    ctx: ScanContext,
1742    settled: Checkpoint,
1743    runs_liveness: bool,
1744) -> JoinHandle<ScanReport> {
1745    // The plan the port phase walks, less what the exclusions withhold.
1746    let mut numbered = target_map.clone();
1747    cfg.exclusions.withhold_targets(&mut numbered);
1748    let caps = ScanCapabilities::resolve(
1749        cfg,
1750        sitting_probes(cfg, &target_map, &numbered, &settled),
1751        &orchestrator::unsettled_ips(&numbered, &settled),
1752        interface::FrameSender::Probe,
1753    );
1754    // What the caller set is kept so the passes an idle scan turns off can be
1755    // named as declined.
1756    let requested = cfg.clone();
1757    let cfg = running_under(&requested);
1758    let held_back = crate::system::descriptors::hold_back();
1759
1760    tokio::spawn(async move {
1761        // Held for as long as the scan runs; see `descriptors::hold_back`.
1762        let _held_back = held_back;
1763        crate::fingerprint::start_loading_corpus();
1764        // Numbered before either phase runs, so an address either one files
1765        // as unreachable settles every target at it.
1766        ctx.number_targets(TargetIndex::of(&numbered));
1767        // Before any phase opens a capture, so each listens only where a
1768        // reply to this plan can arrive.
1769        ctx.capture_on(capture_links);
1770
1771        // Phase one: which of these addresses has anything at it.
1772        //
1773        // The answer narrows what is probed, not what is counted: the
1774        // dispatcher settles the targets of a silent host at their own
1775        // positions. See `Outcome::Skipped`, and `Outcome::Undecided` for a
1776        // host with no verdict.
1777        let skipped = liveness_skip(&cfg, runs_liveness);
1778        let (liveness, live) = if let Some(why) = skipped {
1779            match why {
1780                LivenessSkip::IdleScan => {
1781                    crate::info!(verbosity = 1, "liveness pass skipped (idle scan)");
1782                }
1783                LivenessSkip::PortsNoDearer => {
1784                    crate::info!(verbosity = 1, "liveness pass skipped (port scan no dearer)");
1785                }
1786                // The caller chose it; no line needed.
1787                _ => {}
1788            }
1789            (None, None)
1790        } else {
1791            // Over the addresses this sitting still has a target at, so a
1792            // resumed one skips hosts an earlier sitting finished. Taken from
1793            // the plan as asked, so the scope still counts what the policy
1794            // withheld.
1795            let unnumbered = Checkpoint::default();
1796            let mut finished = orchestrator::unsettled_ips(&numbered, &unnumbered);
1797            finished.subtract(&orchestrator::unsettled_ips(&numbered, &settled));
1798            let mut ips = orchestrator::unsettled_ips(&target_map, &unnumbered);
1799            ips.subtract(&finished);
1800            let scope = address_scope(&mut ips, &ctx);
1801            let recorder = PhaseRecorder::start(ScanKind::Discovery, caps.privilege, scope, &cfg)
1802                .opening_in(&ctx);
1803
1804            // Targeted: a port scan asks only about its own addresses. Some of
1805            // the scan's own TCP ports join the common five, since a host that
1806            // drops SYNs to anything it does not serve answers on nothing else,
1807            // and SCTP is asked where the scan names an SCTP port, so an
1808            // SCTP-only host is not called down.
1809            ctx.enter_stage(Stage::Discovery, None);
1810            let syn_ports = SynPorts::for_scan(&tcp_ports_of(&target_map));
1811            let sctp = orchestrator::sctp_discovery_port(&target_map, &cfg.excluded_ports);
1812            run_discovery(ips, Scope::Targeted, caps, &cfg, &ctx, syn_ports, sctp).await;
1813
1814            orchestrator::correlate(&ctx, cfg.service_detection).await;
1815            let (report, liveness) = recorder.close(&ctx);
1816            (Some(report), liveness)
1817        };
1818
1819        // Phase two: the ports. The exclusion policy is applied again, since
1820        // phase one does not always run.
1821        //
1822        // The scope is what this phase covered, taken over the live subset, so
1823        // a reader can compare it with phase one's. The dispatcher is handed
1824        // the whole plan, because its positions are counted in that.
1825        let mut covered = match &live {
1826            Some(live) => probed_subset(&target_map, &live.live),
1827            None => target_map.clone(),
1828        };
1829        // Held to the machines the policy names as well as its addresses, so
1830        // the scope does not count what the walk will not ask. The plan itself
1831        // is narrowed by address alone, since a machine's addresses can differ
1832        // between sittings; the walk withholds the rest by position.
1833        let scope = TargetScope::from_target_map(&mut covered, &machine_policy(&ctx));
1834        let mut recorder = PhaseRecorder::start(ScanKind::PortScan, caps.privilege, scope, &cfg);
1835        if let Some(why) = skipped {
1836            recorder = recorder.skipping_liveness(why);
1837        }
1838        let recorder = recorder.opening_in(&ctx);
1839
1840        ctx.enter_stage(Stage::Ports, None);
1841        // Filed against the port phase, the only phase an idle scan has.
1842        record_idle_refusals(&requested, &ctx);
1843        let port_scanner = match caps.privilege.is_raw() {
1844            true => ScannerKind::SynPort,
1845            false => ScannerKind::Connect,
1846        };
1847        withheld.refuse(&ctx, port_scanner);
1848        let stands_in = skipped == Some(LivenessSkip::PortsNoDearer);
1849        run_port_phase(
1850            numbered,
1851            withheld.zones(),
1852            live,
1853            &ctx,
1854            caps,
1855            &cfg,
1856            settled,
1857            stands_in,
1858        )
1859        .await;
1860
1861        // Needs the ports a handshake completed against, which the service pass
1862        // produces.
1863        orchestrator::run_tls_enumeration(&ctx, &cfg).await;
1864
1865        // The series probe takes every host with a TCP answer, leaving the echo
1866        // probe the machines that answered nothing.
1867        orchestrator::run_active_os_series(&ctx, cfg.os_detection, cfg.probe_tuning(), caps).await;
1868        orchestrator::run_active_os_snmp(&ctx, cfg.os_detection, &cfg.excluded_ports).await;
1869        // Asks only named hosts. macOS and iOS share a kernel and look alike
1870        // to a stack probe; a device-info record names the model.
1871        orchestrator::run_active_os_mdns(&ctx, cfg.os_detection, !cfg.no_dns, &cfg.excluded_ports)
1872            .await;
1873        orchestrator::run_active_os_probe(&ctx, cfg.os_detection, cfg.probe_tuning(), caps).await;
1874        // After the ports, which decide a trace's shape.
1875        orchestrator::run_traceroute(&ctx, &cfg, caps).await;
1876        orchestrator::run_characterise(&ctx, &cfg, caps).await;
1877        orchestrator::run_ip_protocols(&ctx, &cfg).await;
1878        ctx.enter_stage(Stage::Finishing, None);
1879        vantage::attribute(&ctx);
1880        orchestrator::correlate(&ctx, cfg.service_detection).await;
1881        orchestrator::run_cert_posture(&ctx);
1882        let report = recorder.finish_last(ctx);
1883
1884        // Both closed against this scan's one store, so the port phase's
1885        // hosts are later copies of the liveness phase's.
1886        match liveness {
1887            Some(mut first) => {
1888                first.merge_later_copy(report);
1889                first
1890            }
1891            None => report,
1892        }
1893    })
1894}
1895
1896// ╔════════════════════════════════════════════╗
1897// ║ ████████╗███████╗███████╗████████╗███████╗ ║
1898// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
1899// ║    ██║   █████╗  ███████╗   ██║   ███████╗ ║
1900// ║    ██║   ██╔══╝  ╚════██║   ██║   ╚════██║ ║
1901// ║    ██║   ███████╗███████║   ██║   ███████║ ║
1902// ║    ╚═╝   ╚══════╝╚══════╝   ╚═╝   ╚══════╝ ║
1903// ╚════════════════════════════════════════════╝
1904
1905#[cfg(test)]
1906mod tests {
1907    use super::*;
1908    use crate::testing::loopback::accept_from_this_process;
1909
1910    /// A sitting with nothing left to ask names no probes, and one with a
1911    /// target left names them.
1912    #[test]
1913    fn a_sitting_with_nothing_left_to_ask_names_no_probes() {
1914        let mut map = TargetMap::new();
1915        map.add_unit(crate::model::target::TargetSet::new(
1916            "192.0.2.1".parse().expect("an address"),
1917            "80".parse().expect("a port"),
1918        ));
1919        let cfg = ZondConfig::default();
1920
1921        let everything = Checkpoint::new(1, []);
1922        assert_eq!(sitting_probes(&cfg, &map, &map, &everything), None);
1923        assert!(
1924            sitting_probes(&cfg, &map, &map, &Checkpoint::default()).is_some(),
1925            "a sitting with its target left to ask probes it"
1926        );
1927    }
1928
1929    /// A scratch journal root, removed and made again for each test that
1930    /// names it.
1931    #[cfg(feature = "journal-format")]
1932    fn journal_root(name: &str) -> std::path::PathBuf {
1933        let root = std::env::temp_dir().join(format!("zond-{name}-{}", std::process::id()));
1934        let _ = std::fs::remove_dir_all(&root);
1935        std::fs::create_dir_all(&root).expect("a scratch root");
1936        root
1937    }
1938
1939    /// A named address the neighbour tables tie to an excluded machine is
1940    /// withheld from a sweep's targets, counted and listed like the excluded
1941    /// address, and settled so no later sitting owes it.
1942    #[test]
1943    fn a_named_address_of_an_excluded_machine_leaves_the_sweeps_scope() {
1944        use crate::journal::settle::Outcome;
1945        use crate::model::exclusion::Exclusions;
1946        use crate::model::ip::set::{IpSet, Positions};
1947        use crate::model::mac::MacAddr;
1948        use std::net::IpAddr;
1949
1950        let machine = MacAddr::new(0x02, 0, 0, 0, 0, 0x30);
1951        let excluded: IpAddr = "192.0.2.30".parse().expect("literal");
1952        let other: IpAddr = "192.0.2.40".parse().expect("literal");
1953        let mut policy = IpSet::new();
1954        policy.insert(excluded);
1955        let mut targets: IpSet = "192.0.2.39-192.0.2.41".parse().expect("a range");
1956        let (_session, ctx) = ScanSession::builder()
1957            .excluding(Exclusions::new(policy))
1958            .with_neighbours(vec![(excluded, Some(machine)), (other, Some(machine))])
1959            .counting(Positions::of(&targets))
1960            .build();
1961
1962        let scope = address_scope(&mut targets, &ctx);
1963
1964        assert!(!targets.contains(&other), "it is still a target");
1965        assert_eq!(targets.len(), 2);
1966        assert_eq!((scope.addresses(), scope.withheld()), (2, 1));
1967        let excluded_starts: Vec<IpAddr> = scope
1968            .excluded()
1969            .iter()
1970            .map(|range| range.start_addr())
1971            .collect();
1972        assert!(excluded_starts.contains(&other), "{excluded_starts:?}");
1973        assert!(excluded_starts.contains(&excluded), "{excluded_starts:?}");
1974        assert_eq!(
1975            ctx.settlements().count(Outcome::Withheld { position: 0 }),
1976            1
1977        );
1978        assert_eq!(ctx.settlements().checkpoint().settled_count(), 1);
1979    }
1980
1981    /// A configuration every scan refuses before it sends anything.
1982    fn refused_up_front() -> ZondConfig {
1983        ZondConfig {
1984            evasion: crate::evasion::EvasionProfile::default().with_ttl(0),
1985            ..ZondConfig::default()
1986        }
1987    }
1988
1989    /// A scan refused before it starts leaves no record of itself.
1990    ///
1991    /// Otherwise the journal would stay behind as a resumable job with nothing
1992    /// done, and the caller cannot tidy it, since the journal was moved into
1993    /// the call.
1994    #[cfg(feature = "journal-format")]
1995    #[tokio::test]
1996    async fn a_journalled_scan_refused_up_front_leaves_no_record() {
1997        use crate::journal::Journal;
1998        use crate::journal::manifest::Plan;
1999        use crate::model::ip::set::IpSet;
2000        use crate::model::target::TargetSet;
2001
2002        let root = journal_root("refused");
2003        let addresses: IpSet = "192.0.2.1".parse().expect("an address");
2004        let mut map = TargetMap::new();
2005        map.add_unit(TargetSet::new(
2006            addresses.clone(),
2007            "22".parse().expect("ports"),
2008        ));
2009        let cfg = refused_up_front();
2010
2011        let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2012        let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2013        let directory = journal.directory().to_path_buf();
2014        let refused = scan_with_journal(map, &cfg, Detections::embedded(), journal).await;
2015        assert!(
2016            matches!(refused, Err(ScanError::Evasion(_))),
2017            "{:?}",
2018            refused.err()
2019        );
2020        assert!(
2021            !directory.exists(),
2022            "a port scan that never ran left a record"
2023        );
2024
2025        let plan = Plan::discovery(&addresses, &cfg.exclusions, false);
2026        let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2027        let directory = journal.directory().to_path_buf();
2028        let refused = discover_with_journal(addresses, &cfg, journal).await;
2029        assert!(
2030            matches!(refused, Err(ScanError::Evasion(_))),
2031            "{:?}",
2032            refused.err()
2033        );
2034        assert!(!directory.exists(), "a sweep that never ran left a record");
2035
2036        std::fs::remove_dir_all(&root).ok();
2037    }
2038
2039    /// A raw scan's up-front need counts a capture device for every link it
2040    /// will capture on, and a scan by connect counts none.
2041    #[test]
2042    fn a_raw_scan_needs_a_capture_device_for_each_link_it_captures_on() {
2043        use crate::model::ip::scoped::Zone;
2044
2045        let links = [Zone::new(1, "lo0"), Zone::new(4, "en0")];
2046        assert_eq!(captures_needed(Privilege::Raw, &links), 2);
2047        assert_eq!(captures_needed(Privilege::Connect, &links), 0);
2048    }
2049
2050    /// A scan of loopback counts, and captures on, loopback's link and no
2051    /// other, whatever else the machine has up.
2052    #[test]
2053    fn a_scan_of_loopback_plans_its_captures_on_loopback_alone() {
2054        let cfg = ZondConfig::default();
2055        let links =
2056            capture_plan(&"127.0.0.1".parse().expect("an address"), &cfg).expect("room for it");
2057
2058        let loopback: Vec<_> = crate::system::interface::interfaces()
2059            .expect("this machine's interfaces")
2060            .into_iter()
2061            .filter(crate::system::interface::Link::is_loopback)
2062            .map(|link| link.zone())
2063            .collect();
2064        assert_eq!(links, loopback);
2065    }
2066
2067    /// A port scan of a range too wide to walk refuses it in its port phase
2068    /// and ends, without trying to settle its targets one at a time.
2069    #[tokio::test]
2070    async fn a_port_scan_of_a_range_too_wide_to_walk_refuses_it_and_ends() {
2071        use crate::model::target::TargetSet;
2072
2073        let mut map = TargetMap::new();
2074        map.add_unit(TargetSet::new(
2075            "2001:db8::/64".parse().expect("a prefix"),
2076            "80,443".parse().expect("ports"),
2077        ));
2078        let cfg = ZondConfig {
2079            no_dns: true,
2080            ..ZondConfig::default()
2081        };
2082
2083        let (_session, task) = scan(map, &cfg, Detections::embedded())
2084            .await
2085            .expect("the scan starts");
2086        // Generous: the scan should end at once, and the failure never ends.
2087        let report = tokio::time::timeout(std::time::Duration::from_secs(120), task)
2088            .await
2089            .expect("the scan ended")
2090            .expect("the scan ran");
2091
2092        let refused: Vec<_> = report
2093            .phases()
2094            .iter()
2095            .filter(|phase| phase.kind() == ScanKind::PortScan)
2096            .flat_map(|phase| phase.refusals().iter())
2097            .filter(|refusal| refusal.reason().contains("too large to walk"))
2098            .collect();
2099        assert_eq!(refused.len(), 1, "{:?}", report.phases());
2100    }
2101
2102    /// A job naming a link-local target with no interface ahead of others
2103    /// numbers its plan once, and a finished sitting leaves nothing owed.
2104    ///
2105    /// The refused target must be out of the plan the positions count, or
2106    /// every target after it would have two positions.
2107    #[cfg(feature = "journal-format")]
2108    #[tokio::test]
2109    async fn a_withheld_link_local_target_leaves_one_numbering_across_sittings() {
2110        use crate::journal::Journal;
2111        use crate::journal::manifest::Plan;
2112        use crate::model::ip::set::IpSet;
2113        use crate::model::target::TargetSet;
2114        use crate::testing::loopback::SilentPort;
2115
2116        let peer = SilentPort::open();
2117        let mut map = TargetMap::new();
2118        map.add_unit(TargetSet::new(
2119            "fe80::1-fe80::2".parse::<IpSet>().expect("addresses"),
2120            "80".parse().expect("ports"),
2121        ));
2122        map.add_unit(TargetSet::new(
2123            IpSet::from(peer.addr().ip()),
2124            peer.addr().port().to_string().parse().expect("ports"),
2125        ));
2126        let cfg = ZondConfig {
2127            no_dns: true,
2128            assume_up: true,
2129            service_detection: crate::config::ServiceDetection::Off,
2130            ..ZondConfig::default()
2131        };
2132        let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2133        let root = journal_root("withheld-link-local");
2134        let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2135        let directory = journal.directory().to_path_buf();
2136
2137        let (session, task) = scan_with_journal(map.clone(), &cfg, Detections::embedded(), journal)
2138            .await
2139            .expect("the first sitting starts");
2140        let report = task.join().await.expect("it finishes");
2141        assert!(
2142            report
2143                .phases()
2144                .iter()
2145                .flat_map(|phase| phase.refusals())
2146                .any(|refusal| refusal.reason().contains("link-local, name the interface")),
2147            "the unscoped targets are refused: {:?}",
2148            report.phases()
2149        );
2150        let progress = session.progress();
2151        assert_eq!(progress.planned(), Some(1), "the plan walked is one target");
2152        assert_eq!(
2153            progress.remaining(),
2154            Some(0),
2155            "and a finished sitting owes none"
2156        );
2157
2158        let (journal, settled) =
2159            Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2160        assert_eq!(settled.settled_count(), 1, "the job recorded it settled");
2161        let (session, task) = scan_with_journal(map, &cfg, Detections::embedded(), journal)
2162            .await
2163            .expect("the second sitting starts");
2164        let _report = task.join().await.expect("it finishes");
2165        assert_eq!(
2166            session.progress().remaining(),
2167            Some(0),
2168            "a resume walks the plan the first sitting numbered"
2169        );
2170
2171        std::fs::remove_dir_all(&root).ok();
2172    }
2173
2174    /// A sweep counts what it settles, so its progress reflects its work.
2175    #[tokio::test]
2176    async fn a_sweep_counts_the_addresses_it_settles() {
2177        let cfg = ZondConfig {
2178            no_dns: true,
2179            ..ZondConfig::default()
2180        };
2181        let (session, task) = discover("127.0.0.1".parse().expect("an address"), &cfg)
2182            .await
2183            .expect("the sweep starts");
2184        let _report = task.await.expect("the sweep ran");
2185
2186        let progress = session.progress();
2187        assert_eq!(progress.planned(), Some(1));
2188        assert_eq!(progress.settled(), 1, "the one address answered");
2189    }
2190
2191    /// Dropping the task stops the scan, and the session's stream still ends
2192    /// as it does for any finished scan.
2193    #[tokio::test]
2194    async fn dropping_the_task_stops_the_scan() {
2195        use crate::model::target::TargetSet;
2196
2197        let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
2198            .await
2199            .expect("a free port");
2200        let port = listener.local_addr().expect("its address").port();
2201        // Takes every connection and says nothing, for as long as the test runs.
2202        tokio::spawn(async move {
2203            let mut held = Vec::new();
2204            while let Ok(stream) = accept_from_this_process(&listener).await {
2205                held.push(stream);
2206            }
2207        });
2208
2209        let mut map = TargetMap::new();
2210        map.add_unit(TargetSet::new(
2211            "127.0.0.1".parse().expect("an address"),
2212            port.to_string().parse().expect("a port"),
2213        ));
2214        let cfg = ZondConfig {
2215            no_dns: true,
2216            service_detection: crate::config::ServiceDetection::Thorough,
2217            ..ZondConfig::default()
2218        };
2219        let (mut session, task) = scan(map, &cfg, Detections::embedded())
2220            .await
2221            .expect("the scan starts");
2222        drop(task);
2223
2224        assert_eq!(
2225            session.handle().stopped(),
2226            Some(handle::StopCause::Aborted),
2227            "the scan runs on with nobody to collect it"
2228        );
2229        while session.events().recv().await.is_some() {}
2230    }
2231
2232    /// A scan stopped before it reached its ports starts none of the passes
2233    /// that follow them. Each pass announces its stage before it sends
2234    /// anything, so the stage events show which ones started.
2235    #[tokio::test]
2236    async fn a_scan_stopped_before_its_ports_starts_no_later_pass() {
2237        use crate::model::target::TargetSet;
2238        use crate::scanner::session::ScanEvent;
2239
2240        let mut map = TargetMap::new();
2241        map.add_unit(TargetSet::new(
2242            "127.0.0.1".parse().expect("an address"),
2243            "1-16".parse().expect("ports"),
2244        ));
2245        let cfg = ZondConfig {
2246            no_dns: true,
2247            os_detection: crate::config::OsDetection::Active,
2248            traceroute: true,
2249            tls_enumeration: true,
2250            ..ZondConfig::default()
2251        };
2252
2253        let (mut session, task) = scan(map, &cfg, Detections::embedded())
2254            .await
2255            .expect("the scan starts");
2256        session.handle().abort();
2257        let _report = task.await.expect("the scan ran");
2258
2259        let mut stages = Vec::new();
2260        while let Some(event) = session.events().try_recv() {
2261            if let ScanEvent::StageChanged { stage } = event {
2262                stages.push(stage);
2263            }
2264        }
2265        assert!(
2266            stages
2267                .iter()
2268                .all(|stage| matches!(stage, Stage::Discovery | Stage::Ports | Stage::Finishing)),
2269            "a pass began after the stop: {stages:?}"
2270        );
2271    }
2272
2273    /// A resumed sitting that asks something its job did not is refused by the
2274    /// option it changed, before anything is sent, and the record of the
2275    /// sitting before it is kept.
2276    #[cfg(feature = "journal-format")]
2277    #[tokio::test]
2278    async fn a_resume_asking_what_its_job_did_not_is_refused_and_keeps_its_record() {
2279        use crate::journal::Journal;
2280        use crate::journal::manifest::{JobOptions, OptionChanged, Plan};
2281        use crate::journal::settle::{Outcome, Settlements};
2282        use crate::model::ip::set::IpSet;
2283
2284        let root = journal_root("option-changed");
2285        let addresses: IpSet = "192.0.2.1-192.0.2.4".parse().expect("addresses");
2286        let first = ZondConfig {
2287            traceroute: true,
2288            ..ZondConfig::default()
2289        };
2290        let plan = Plan::discovery(&addresses, &first.exclusions, false);
2291
2292        let mut journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2293        journal
2294            .record_options(JobOptions::of(&first))
2295            .expect("records");
2296        let settlements = Settlements::default();
2297        settlements.record(Outcome::Answered { position: 0 });
2298        journal.checkpoint(&settlements).expect("checkpoints");
2299        let directory = journal.directory().to_path_buf();
2300        journal.close().expect("closes");
2301
2302        let (journal, _) =
2303            Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2304        let refused = discover_with_journal(addresses, &ZondConfig::default(), journal).await;
2305        assert!(
2306            matches!(
2307                refused,
2308                Err(ScanError::OptionChanged(OptionChanged {
2309                    option: "traceroute"
2310                }))
2311            ),
2312            "{:?}",
2313            refused.err()
2314        );
2315        assert!(directory.join("manifest.json").exists(), "the record went");
2316
2317        std::fs::remove_dir_all(&root).ok();
2318    }
2319
2320    /// A job with no recorded options resumes under the technique its manifest
2321    /// names, whatever this sitting was handed.
2322    #[cfg(feature = "journal-format")]
2323    #[tokio::test]
2324    async fn a_job_recorded_without_options_resumes_under_its_manifests_technique() {
2325        use crate::journal::Journal;
2326        use crate::journal::manifest::Plan;
2327        use crate::model::ip::set::IpSet;
2328        use crate::model::target::TargetSet;
2329        use crate::model::technique::TcpScanTechnique;
2330
2331        let root = journal_root("recorded-technique");
2332        let mut map = TargetMap::new();
2333        map.add_unit(TargetSet::new(
2334            "127.0.0.1".parse::<IpSet>().expect("an address"),
2335            "9".parse().expect("ports"),
2336        ));
2337        let cfg = ZondConfig {
2338            no_dns: true,
2339            assume_up: true,
2340            ..ZondConfig::default()
2341        };
2342        assert_ne!(cfg.tcp_technique, TcpScanTechnique::Ack, "test premise");
2343
2344        let plan = Plan::port_scan(&map, &cfg.exclusions, TcpScanTechnique::Ack);
2345        let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2346        let directory = journal.directory().to_path_buf();
2347        journal.close().expect("closes");
2348        let (journal, _) =
2349            Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2350        assert!(journal.options().is_none(), "test premise: no options");
2351
2352        let (_session, task) = scan_with_journal(map, &cfg, Detections::embedded(), journal)
2353            .await
2354            .expect("the sitting starts");
2355        let report = task.join().await.expect("it finishes");
2356
2357        let ports = report
2358            .phases()
2359            .iter()
2360            .find(|phase| phase.kind() == ScanKind::PortScan)
2361            .expect("a port phase");
2362        assert_eq!(ports.settings().tcp_technique, TcpScanTechnique::Ack);
2363
2364        std::fs::remove_dir_all(&root).ok();
2365    }
2366
2367    /// A watch's journal records no options, so a watch resumed under other
2368    /// settings continues.
2369    #[cfg(feature = "journal-format")]
2370    #[tokio::test]
2371    async fn a_watch_records_no_options_to_hold_a_later_sitting_to() {
2372        use crate::journal::Journal;
2373        use crate::journal::manifest::Plan;
2374        use crate::model::ip::scoped::Zone;
2375
2376        let root = journal_root("watch-options");
2377        // A link no machine has, so the watch ends as soon as its capture is
2378        // refused.
2379        let links = vec![Zone::new(u32::MAX, "zond-no-such-link")];
2380        let plan = Plan::listen(links.clone());
2381        let scope =
2382            || ListenScope::on(links.clone()).for_at_most(std::time::Duration::from_millis(1));
2383
2384        let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2385        let directory = journal.directory().to_path_buf();
2386        let (_session, task) = listen_with_journal(scope(), &ZondConfig::default(), journal)
2387            .await
2388            .expect("the watch starts");
2389        let _ = task.join().await.expect("it ends");
2390        assert!(
2391            !directory.join("options.json").exists(),
2392            "a watch recorded options"
2393        );
2394
2395        let (journal, _) =
2396            Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2397        let other = ZondConfig {
2398            traceroute: true,
2399            tcp_technique: crate::model::technique::TcpScanTechnique::Fin,
2400            ..ZondConfig::default()
2401        };
2402        let (_session, task) = listen_with_journal(scope(), &other, journal)
2403            .await
2404            .expect("a watch resumed under other settings continues");
2405        let _ = task.join().await.expect("it ends");
2406
2407        std::fs::remove_dir_all(&root).ok();
2408    }
2409
2410    /// A sweep's journal handed to a port scan is refused as the other phase,
2411    /// and withdrawn with the rest of the up-front refusals.
2412    ///
2413    /// The exclusion check alone cannot catch this: it rebuilds the recorded
2414    /// plan in its own shape and finds it unchanged.
2415    #[cfg(feature = "journal-format")]
2416    #[tokio::test]
2417    async fn a_sweeps_journal_is_refused_to_a_port_scan() {
2418        use crate::journal::Journal;
2419        use crate::journal::manifest::Plan;
2420        use crate::model::ip::set::IpSet;
2421        use crate::model::target::TargetSet;
2422
2423        let root = journal_root("other-phase");
2424        let addresses: IpSet = "127.0.0.1".parse().expect("an address");
2425        let mut map = TargetMap::new();
2426        map.add_unit(TargetSet::new(
2427            addresses.clone(),
2428            "9".parse().expect("ports"),
2429        ));
2430        let cfg = ZondConfig::default();
2431
2432        let plan = Plan::discovery(&addresses, &cfg.exclusions, false);
2433        let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2434        let refused = scan_with_journal(map, &cfg, Detections::embedded(), journal).await;
2435        assert!(
2436            matches!(refused, Err(ScanError::WrongPhase)),
2437            "{:?}",
2438            refused.err()
2439        );
2440
2441        std::fs::remove_dir_all(&root).ok();
2442    }
2443
2444    /// A resumed sitting handed the plan as it was named, beside the policy
2445    /// that withholds part of it, asks the liveness pass about exactly the
2446    /// addresses the job has a target left at.
2447    ///
2448    /// Positions count what the policy leaves; read against the plan before
2449    /// the policy, the pass would ask again about an address the first sitting
2450    /// settled.
2451    #[cfg(feature = "journal-format")]
2452    #[tokio::test]
2453    async fn a_resumed_liveness_pass_counts_what_the_policy_leaves() {
2454        use crate::journal::Journal;
2455        use crate::journal::manifest::Plan;
2456        use crate::journal::settle::{Outcome, Settlements};
2457        use crate::model::exclusion::Exclusions;
2458        use crate::model::target::TargetSet;
2459
2460        let mut map = TargetMap::new();
2461        map.add_unit(TargetSet::new(
2462            "127.0.0.1-127.0.0.4".parse().expect("addresses"),
2463            // More than the pass asks, so it earns its place.
2464            "1-100".parse().expect("ports"),
2465        ));
2466        let cfg = ZondConfig {
2467            no_dns: true,
2468            // The asserted scope is fixed before anything is sent, and the
2469            // addresses past 127.0.0.1 answer nothing.
2470            scan_timeout: Some(std::time::Duration::from_secs(1)),
2471            exclusions: Exclusions::new("127.0.0.1".parse().expect("an address")),
2472            ..ZondConfig::default()
2473        };
2474        let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2475
2476        let root = journal_root("liveness-numbering");
2477        let mut journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2478        // Every target at 127.0.0.2 and .3, the first two addresses the policy
2479        // leaves (.1 and .2 if counted before the policy).
2480        let settlements = Settlements::default();
2481        for position in 0..200 {
2482            settlements.record(Outcome::Answered { position });
2483        }
2484        journal.checkpoint(&settlements).expect("checkpoints");
2485        let directory = journal.directory().to_path_buf();
2486        journal.close().expect("closes");
2487
2488        let (journal, _) =
2489            Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2490        let (_session, task) = scan_with_journal(map, &cfg, Detections::embedded(), journal)
2491            .await
2492            .expect("the sitting starts");
2493        let report = task.join().await.expect("the sitting ends");
2494
2495        let liveness = report
2496            .phases()
2497            .iter()
2498            .find(|phase| phase.kind() == ScanKind::Discovery)
2499            .expect("a liveness pass ran");
2500        assert_eq!(
2501            liveness.targets().addresses(),
2502            1,
2503            "{:?}",
2504            liveness.targets().ranges()
2505        );
2506        assert_eq!(liveness.targets().withheld(), 1, "the policy's cost went");
2507        std::fs::remove_dir_all(&root).ok();
2508    }
2509
2510    /// A sitting killed after a checkpoint leaves its hosts owed every pass.
2511    ///
2512    /// Its checkpoints write its phases as they stand, so a resume reads the
2513    /// killed sitting's phase back. Only a sitting's own close says it ran to
2514    /// its end, so its hosts must not be taken for finished.
2515    #[cfg(feature = "journal-format")]
2516    #[tokio::test]
2517    async fn a_sitting_killed_after_a_checkpoint_leaves_its_hosts_owed() {
2518        use crate::journal::Journal;
2519        use crate::journal::manifest::Plan;
2520        use crate::model::exclusion::Exclusions;
2521        use crate::model::host::HostStatus;
2522        use crate::model::ip::set::IpSet;
2523        use crate::model::target::TargetSet;
2524        use crate::scanner::checkpoint::spawn_checkpoints;
2525
2526        let address: std::net::IpAddr = "127.0.0.1".parse().expect("an address");
2527        let mut map = TargetMap::new();
2528        map.add_unit(TargetSet::new(
2529            IpSet::from(address),
2530            "80".parse().expect("ports"),
2531        ));
2532        let cfg = ZondConfig::default();
2533        let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2534        let root = journal_root("killed-owed");
2535        let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2536        let directory = journal.directory().to_path_buf();
2537
2538        // A sitting with its port phase open and a host found, killed once one
2539        // checkpoint has landed.
2540        let (_session, ctx) = ScanSession::new();
2541        let mut scope = IpSet::from(address);
2542        let _open = PhaseRecorder::start(
2543            ScanKind::PortScan,
2544            Privilege::current(),
2545            TargetScope::from_ip_set(&mut scope, &Exclusions::none()),
2546            &cfg,
2547        )
2548        .opening_in(&ctx);
2549        ctx.update_host(address, |host| host.set_status(HostStatus::Up));
2550        let mut ticker = spawn_checkpoints(journal, ctx.progress());
2551        ticker.checkpointed().await;
2552        ticker.kill().await;
2553
2554        let (journal, _) =
2555            Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2556        assert!(
2557            journal
2558                .earlier_phases()
2559                .iter()
2560                .any(|phase| phase.stopped().is_none()),
2561            "the killed sitting's standing phase is read back"
2562        );
2563        let finished = journal.finished_hosts().expect("reads");
2564        let (_resumed, resumed) = ScanSession::builder()
2565            .finished(finished.clone(), IpSet::new())
2566            .build();
2567        resumed.restore_hosts(journal.restored());
2568        let owed = resumed
2569            .read_host(address, |host| resumed.owes_passes(host))
2570            .expect("the host came back");
2571        assert!(
2572            owed,
2573            "a killed sitting's host was taken as finished: {finished:?}"
2574        );
2575
2576        journal.close().expect("closes");
2577        std::fs::remove_dir_all(&root).ok();
2578    }
2579
2580    /// A sitting that ran to its end writes down every host it held as
2581    /// finished, and one that was stopped writes down none, since its passes
2582    /// may not have reached them.
2583    #[cfg(feature = "journal-format")]
2584    #[tokio::test]
2585    async fn only_a_sitting_that_ran_to_its_end_records_its_hosts_finished() {
2586        use crate::journal::Journal;
2587        use crate::journal::manifest::Plan;
2588        use crate::model::target::TargetSet;
2589
2590        let mut map = TargetMap::new();
2591        map.add_unit(TargetSet::new(
2592            "127.0.0.1".parse().expect("an address"),
2593            "9".parse().expect("ports"),
2594        ));
2595        let cfg = ZondConfig {
2596            no_dns: true,
2597            assume_up: true,
2598            ..ZondConfig::default()
2599        };
2600        let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2601
2602        for stopped in [false, true] {
2603            let root = journal_root(&format!("records-finished-{stopped}"));
2604            let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2605            let directory = journal.directory().to_path_buf();
2606            let (session, task) =
2607                scan_with_journal(map.clone(), &cfg, Detections::embedded(), journal)
2608                    .await
2609                    .expect("the sitting starts");
2610            if stopped {
2611                session.handle().abort();
2612            }
2613            let report = task.join().await.expect("the sitting ends");
2614            assert!(report.host_count() > 0 || stopped, "the host was not found");
2615
2616            let (journal, _) =
2617                Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2618            let finished = journal.finished_hosts().expect("reads");
2619            assert_eq!(
2620                finished.contains("127.0.0.1"),
2621                !stopped,
2622                "stopped: {stopped}, finished: {finished:?}"
2623            );
2624            drop(journal);
2625            std::fs::remove_dir_all(&root).ok();
2626        }
2627    }
2628
2629    /// A resumed sitting runs the passes after the probes (here the
2630    /// detections) over a host an earlier sitting finished only where it has
2631    /// something left to ask there, and over a host no sitting finished in
2632    /// full. A finished host is neither asked again nor rewritten.
2633    #[cfg(feature = "journal-format")]
2634    #[tokio::test]
2635    async fn a_resumed_job_asks_a_host_a_sitting_finished_nothing_it_already_asked() {
2636        use crate::journal::Journal;
2637        use crate::journal::manifest::Plan;
2638        use crate::journal::settle::{Outcome, Settlements};
2639        use crate::model::host::{Host, HostStatus};
2640        use crate::model::port::{Port, PortState, Protocol, Service};
2641        use crate::model::target::TargetSet;
2642
2643        let mut map = TargetMap::new();
2644        map.add_unit(TargetSet::new(
2645            "127.0.0.1".parse().expect("an address"),
2646            "80".parse().expect("ports"),
2647        ));
2648        let cfg = ZondConfig {
2649            no_dns: true,
2650            ..ZondConfig::default()
2651        };
2652        let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2653
2654        // A job whose one target an earlier sitting settled, finding a web
2655        // server; `finished` says whether that sitting ran to its end.
2656        let resumed = |finished: bool| {
2657            let (root, map, cfg, plan) = (
2658                journal_root(&format!("finished-{finished}")),
2659                map.clone(),
2660                cfg.clone(),
2661                plan.clone(),
2662            );
2663            async move {
2664                let mut journal =
2665                    Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2666                let mut host = Host::new("127.0.0.1".parse().expect("an address"));
2667                host.set_status(HostStatus::Up);
2668                host.add_port(
2669                    Port::new(80, Protocol::Tcp, PortState::Open)
2670                        .with_service(Service::new("http", 100)),
2671                );
2672                journal.record_hosts(&[host]).expect("records the host");
2673                let settlements = Settlements::default();
2674                settlements.record(Outcome::Answered { position: 0 });
2675                journal.checkpoint(&settlements).expect("checkpoints");
2676                if finished {
2677                    journal
2678                        .record_finished(["127.0.0.1".to_string()])
2679                        .expect("records the sitting's end");
2680                }
2681                let directory = journal.directory().to_path_buf();
2682                journal.close().expect("closes");
2683
2684                let written = |directory: &std::path::Path| {
2685                    std::fs::metadata(directory.join("hosts.jsonl")).map_or(0, |file| file.len())
2686                };
2687                let before = written(&directory);
2688                let (journal, _) =
2689                    Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2690                let (_session, task) =
2691                    scan_with_journal(map, &cfg, Detections::embedded(), journal)
2692                        .await
2693                        .expect("the sitting starts");
2694                let _report = task.join().await.expect("the sitting ends");
2695
2696                let runs = crate::journal::store::read_detections(&directory).expect("reads");
2697                let rewritten = written(&directory) > before;
2698                std::fs::remove_dir_all(&root).ok();
2699                (runs.len(), rewritten)
2700            }
2701        };
2702
2703        let (runs, _) = resumed(false).await;
2704        assert!(
2705            runs > 0,
2706            "a host no sitting finished is owed its detections"
2707        );
2708        let (runs, rewritten) = resumed(true).await;
2709        assert_eq!(runs, 0, "a finished host was asked its detections again");
2710        assert!(!rewritten, "a finished host was written down again");
2711    }
2712
2713    /// A resumed sitting reports each round trip its job recorded once, as
2714    /// reading the job back does.
2715    ///
2716    /// The two phases' reports hold one host twice, the later copy with every
2717    /// round trip the earlier held, so folding them as two accounts would count
2718    /// each restored round trip twice.
2719    #[cfg(feature = "journal-format")]
2720    #[tokio::test]
2721    async fn a_resumed_sitting_reports_each_recorded_round_trip_once() {
2722        use crate::journal::Journal;
2723        use crate::journal::manifest::Plan;
2724        use crate::journal::settle::{Outcome, Settlements};
2725        use crate::model::host::{Host, HostStatus};
2726        use crate::model::target::TargetSet;
2727        use std::time::Duration;
2728
2729        // Ports enough that a liveness pass is worth its probes; see
2730        // `liveness_earns_its_place`.
2731        let mut map = TargetMap::new();
2732        map.add_unit(TargetSet::new(
2733            "127.0.0.1".parse().expect("an address"),
2734            "20000-20015".parse().expect("ports"),
2735        ));
2736        let cfg = ZondConfig {
2737            no_dns: true,
2738            ..ZondConfig::default()
2739        };
2740        assert!(liveness_earns_its_place(&cfg, &map), "the pass runs");
2741        let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2742
2743        // A job an earlier sitting ran to its end, its one host answering in
2744        // round trips no loopback reply takes.
2745        let root = journal_root("round-trips-once");
2746        let mut journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2747        let recorded: Vec<Duration> = (91..=96).map(Duration::from_millis).collect();
2748        let mut host = Host::new("127.0.0.1".parse().expect("an address"));
2749        host.set_status(HostStatus::Up);
2750        host.add_rtts(recorded.iter().copied());
2751        journal.record_hosts(&[host]).expect("records the host");
2752        let settlements = Settlements::default();
2753        for position in 0..16 {
2754            settlements.record(Outcome::Answered { position });
2755        }
2756        journal.checkpoint(&settlements).expect("checkpoints");
2757        journal
2758            .record_finished(["127.0.0.1".to_string()])
2759            .expect("records the sitting's end");
2760        let directory = journal.directory().to_path_buf();
2761        journal.close().expect("closes");
2762
2763        let (journal, _) =
2764            Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2765        let (_session, task) = scan_with_journal(map, &cfg, Detections::embedded(), journal)
2766            .await
2767            .expect("the sitting starts");
2768        let report = task.join().await.expect("the sitting ends");
2769        std::fs::remove_dir_all(&root).ok();
2770
2771        let [host] = report.hosts().collect::<Vec<_>>()[..] else {
2772            panic!("one host reported");
2773        };
2774        let held: Vec<Duration> = host
2775            .telemetry()
2776            .history()
2777            .iter()
2778            .map(|sample| sample.rtt)
2779            .collect();
2780        for rtt in &recorded {
2781            assert_eq!(
2782                held.iter().filter(|held| *held == rtt).count(),
2783                1,
2784                "{rtt:?} is reported other than once: {held:?}"
2785            );
2786        }
2787    }
2788
2789    /// A port an earlier sitting found open and identified, and was killed
2790    /// before its detections ran, is given the findings a sitting that ran to
2791    /// its end draws there.
2792    ///
2793    /// A passive detection reads what identifying the port drew, which a
2794    /// sitting keeps only in memory. The resume probes nothing there, since
2795    /// the target is settled, so the port must be identified again or those
2796    /// detections have nothing to read.
2797    #[cfg(feature = "journal-format")]
2798    #[tokio::test]
2799    async fn a_resume_draws_the_detections_a_killed_sitting_owed_a_port_it_settled() {
2800        use crate::journal::Journal;
2801        use crate::journal::manifest::Plan;
2802        use crate::journal::settle::{Outcome, Settlements};
2803        use crate::model::host::{Host, HostStatus};
2804        use crate::model::port::{Port, PortState, Protocol, Service};
2805        use crate::model::target::TargetSet;
2806        use crate::testing::loopback::accept_from_this_process;
2807        use tokio::io::{AsyncReadExt, AsyncWriteExt};
2808
2809        // A web server that sends none of the headers a browser is told to
2810        // enforce, which a passive detection reads off its reply.
2811        let web_server = || async {
2812            let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
2813                .await
2814                .expect("binds loopback");
2815            let addr = listener.local_addr().expect("a local address");
2816            tokio::spawn(async move {
2817                while let Ok(mut sock) = accept_from_this_process(&listener).await {
2818                    tokio::spawn(async move {
2819                        let mut buffer = [0u8; 1024];
2820                        if !matches!(sock.read(&mut buffer).await, Ok(n) if n > 0) {
2821                            return;
2822                        }
2823                        let _ = sock
2824                            .write_all(
2825                                b"HTTP/1.1 200 OK\r\nServer: nginx/1.24.0\r\n\
2826                                  Content-Type: text/html\r\nContent-Length: 0\r\n\
2827                                  Connection: close\r\n\r\n",
2828                            )
2829                            .await;
2830                    });
2831                }
2832            });
2833            addr
2834        };
2835        let addr = web_server().await;
2836        // Another the killed sitting had not reached, so the resume has a
2837        // target left at the address and runs as a sitting mid-job does.
2838        let unreached = web_server().await.port();
2839        let mut map = TargetMap::new();
2840        map.add_unit(TargetSet::new(
2841            addr.ip().into(),
2842            format!("{},{unreached}", addr.port())
2843                .parse()
2844                .expect("ports"),
2845        ));
2846        let cfg = ZondConfig {
2847            no_dns: true,
2848            ..ZondConfig::default()
2849        };
2850        let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2851        let settled = map
2852            .iter()
2853            .position(|target| target.port == addr.port())
2854            .expect("the server's port is planned") as u64;
2855        let findings = |report: &ScanReport| {
2856            report
2857                .hosts()
2858                .flat_map(Host::ports)
2859                .flat_map(Port::findings)
2860                .count()
2861        };
2862
2863        let root = journal_root("owed-detections-whole");
2864        let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2865        let (_session, task) =
2866            scan_with_journal(map.clone(), &cfg, Detections::embedded(), journal)
2867                .await
2868                .expect("the sitting starts");
2869        let whole = findings(&task.join().await.expect("the sitting ends"));
2870        std::fs::remove_dir_all(&root).ok();
2871        assert!(whole > 0, "the server draws no finding to lose");
2872
2873        // A sitting killed between identifying the port and detecting on it.
2874        let root = journal_root("owed-detections-killed");
2875        let mut journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2876        let mut host = Host::new(addr.ip());
2877        host.set_status(HostStatus::Up);
2878        host.add_port(
2879            Port::new(addr.port(), Protocol::Tcp, PortState::Open)
2880                .with_service(Service::new("http", 90)),
2881        );
2882        journal.record_hosts(&[host]).expect("records the host");
2883        let settlements = Settlements::default();
2884        settlements.record(Outcome::Answered { position: settled });
2885        journal.checkpoint(&settlements).expect("checkpoints");
2886        let directory = journal.directory().to_path_buf();
2887        journal.close().expect("closes");
2888
2889        let (journal, _) =
2890            Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2891        let (_session, task) = scan_with_journal(map, &cfg, Detections::embedded(), journal)
2892            .await
2893            .expect("the sitting starts");
2894        let resumed = findings(&task.join().await.expect("the sitting ends"));
2895        std::fs::remove_dir_all(&root).ok();
2896        assert_eq!(
2897            resumed, whole,
2898            "the resume drew other findings than one sitting"
2899        );
2900    }
2901
2902    /// A sitting that excludes a port the job did not is continued, sends the
2903    /// port nothing, neither its probe nor a pass over what an earlier sitting
2904    /// found open there, and still skips what the job had settled.
2905    ///
2906    /// An exclusion only narrows a scan, and is how a fragile device is spared
2907    /// a probe, so it must not cost the job. Taken into the numbering, it would
2908    /// shift every later target's position.
2909    #[cfg(feature = "journal-format")]
2910    #[tokio::test]
2911    async fn a_resume_excluding_another_port_sends_it_nothing_and_keeps_the_numbering() {
2912        use crate::journal::Journal;
2913        use crate::journal::manifest::{JobOptions, Plan};
2914        use crate::journal::settle::{Outcome, Settlements};
2915        use crate::model::host::{Host, HostStatus};
2916        use crate::model::port::{Port, PortSet, PortState, Protocol};
2917        use crate::model::target::TargetSet;
2918        use crate::testing::loopback::SilentPort;
2919
2920        let (first, second) = (SilentPort::open(), SilentPort::open());
2921        // The one excluded is walked first, so a numbering without it would
2922        // give the other its position.
2923        let (excluded, settled) = if first.addr().port() < second.addr().port() {
2924            (first, second)
2925        } else {
2926            (second, first)
2927        };
2928        let mut map = TargetMap::new();
2929        map.add_unit(TargetSet::new(
2930            "127.0.0.1".parse().expect("an address"),
2931            format!("{},{}", excluded.addr().port(), settled.addr().port())
2932                .parse()
2933                .expect("ports"),
2934        ));
2935        let recorded = ZondConfig {
2936            no_dns: true,
2937            assume_up: true,
2938            ..ZondConfig::default()
2939        };
2940        let plan = Plan::port_scan(&map, &recorded.exclusions, recorded.tcp_technique);
2941
2942        let root = journal_root("added-exclusion");
2943        let mut journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2944        journal
2945            .record_options(JobOptions::of(&recorded))
2946            .expect("records the options");
2947        // The port to be excluded is already on record as open.
2948        let mut host = Host::new("127.0.0.1".parse().expect("an address"));
2949        host.set_status(HostStatus::Up);
2950        host.add_port(Port::new(
2951            excluded.addr().port(),
2952            Protocol::Tcp,
2953            PortState::Open,
2954        ));
2955        journal.record_hosts(&[host]).expect("records the host");
2956        let settlements = Settlements::default();
2957        settlements.record(Outcome::Answered { position: 1 });
2958        journal.checkpoint(&settlements).expect("checkpoints");
2959        let directory = journal.directory().to_path_buf();
2960        journal.close().expect("closes");
2961
2962        let mut cfg = recorded.clone();
2963        cfg.excluded_ports =
2964            PortSet::try_from(excluded.addr().port().to_string().as_str()).expect("a port");
2965        let (journal, _) =
2966            Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2967        let (_session, task) = scan_with_journal(map, &cfg, Detections::embedded(), journal)
2968            .await
2969            .expect("a sitting excluding more is continued");
2970        let report = task.join().await.expect("the sitting ends");
2971        std::fs::remove_dir_all(&root).ok();
2972
2973        assert_eq!(
2974            crate::transport::dial::dialled::to(excluded.addr()),
2975            0,
2976            "the excluded port was asked"
2977        );
2978        assert_eq!(
2979            crate::transport::dial::dialled::to(settled.addr()),
2980            0,
2981            "a settled target was asked again"
2982        );
2983        assert!(
2984            report
2985                .hosts()
2986                .flat_map(Host::ports)
2987                .all(|port| port.number() != excluded.addr().port()),
2988            "the excluded port is still reported"
2989        );
2990        assert!(
2991            report
2992                .phases()
2993                .last()
2994                .expect("the sitting's phase")
2995                .settings()
2996                .excluded_ports
2997                .contains(excluded.addr().port(), Protocol::Tcp),
2998            "the report does not say the port was excluded"
2999        );
3000    }
3001
3002    /// A job that excludes a port is finished once one sitting has asked
3003    /// everything else, and its record says so.
3004    ///
3005    /// The ports a job excludes are never numbered, so no sitting asks or
3006    /// settles them, and they must not count in the job's total.
3007    #[cfg(feature = "journal-format")]
3008    #[tokio::test]
3009    async fn a_job_excluding_a_port_is_complete_once_it_has_asked_the_rest() {
3010        use crate::journal::Journal;
3011        use crate::journal::manifest::Plan;
3012        use crate::model::port::PortSet;
3013        use crate::model::target::TargetSet;
3014        use crate::testing::loopback::SilentPort;
3015
3016        let (excluded, asked) = (SilentPort::open(), SilentPort::open());
3017        let mut map = TargetMap::new();
3018        map.add_unit(TargetSet::new(
3019            "127.0.0.1".parse().expect("an address"),
3020            format!("{},{}", excluded.addr().port(), asked.addr().port())
3021                .parse()
3022                .expect("ports"),
3023        ));
3024        let cfg = ZondConfig {
3025            no_dns: true,
3026            assume_up: true,
3027            excluded_ports: PortSet::try_from(excluded.addr().port().to_string().as_str())
3028                .expect("a port"),
3029            ..ZondConfig::default()
3030        };
3031        let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
3032
3033        let root = journal_root("excluded-complete");
3034        let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
3035        let (_session, task) = scan_with_journal(map, &cfg, Detections::embedded(), journal)
3036            .await
3037            .expect("the sitting starts");
3038        let _report = task.join().await.expect("the sitting ends");
3039        let listed = crate::journal::store::list(&root).expect("lists").entries;
3040        std::fs::remove_dir_all(&root).ok();
3041
3042        assert_eq!(
3043            crate::transport::dial::dialled::to(excluded.addr()),
3044            0,
3045            "the excluded port was asked"
3046        );
3047        let [entry] = listed.as_slice() else {
3048            panic!("one job on record: {listed:?}");
3049        };
3050        assert_eq!(
3051            (entry.settled(), entry.manifest.total_targets),
3052            (Some(1), 1),
3053            "settled against the total"
3054        );
3055        assert!(entry.is_complete(), "the finished job reads as unfinished");
3056    }
3057
3058    /// A resumed sweep with nothing left to ask runs none of the passes that
3059    /// follow it over a host a sitting that ran to its end finished with.
3060    ///
3061    /// The route trace, OS and filter probes and the passes that write a
3062    /// conclusion back take the hosts the store holds, which a resume restores
3063    /// in full; the finished record keeps them from being probed and written
3064    /// again.
3065    #[cfg(feature = "journal-format")]
3066    #[tokio::test]
3067    async fn a_resumed_sweep_with_nothing_left_passes_nothing_over_what_it_finished() {
3068        use crate::journal::Journal;
3069        use crate::journal::manifest::Plan;
3070        use crate::model::ip::set::IpSet;
3071
3072        let addresses: IpSet = "127.0.0.1".parse().expect("an address");
3073        let cfg = ZondConfig {
3074            no_dns: true,
3075            traceroute: true,
3076            ..ZondConfig::default()
3077        };
3078        let plan = Plan::discovery(&addresses, &cfg.exclusions, false);
3079        let root = journal_root("finished-sweep");
3080        let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
3081        let directory = journal.directory().to_path_buf();
3082        let (_session, task) = discover_with_journal(addresses.clone(), &cfg, journal)
3083            .await
3084            .expect("the sitting starts");
3085        let first = task.join().await.expect("the sitting ends");
3086        assert!(first.host_count() > 0, "loopback was not found");
3087
3088        let written =
3089            || std::fs::metadata(directory.join("hosts.jsonl")).map_or(0, |file| file.len());
3090        let before = written();
3091        let (journal, _) =
3092            Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
3093        let (_session, task) = discover_with_journal(addresses, &cfg, journal)
3094            .await
3095            .expect("the sitting starts");
3096        let resumed = task.join().await.expect("the sitting ends");
3097        let after = written();
3098        std::fs::remove_dir_all(&root).ok();
3099
3100        // A sitting that owed a host the trace either traces it or, where it
3101        // may not, files a refusal.
3102        let traced = resumed
3103            .phases()
3104            .last()
3105            .expect("the sitting's phase")
3106            .refusals()
3107            .iter()
3108            .any(|refusal| refusal.reason().contains("route trace"));
3109        assert!(!traced, "the finished host was owed its route trace");
3110        assert_eq!(after, before, "the finished host was written down again");
3111    }
3112
3113    /// A port scan handed a journal counted over another plan, or under
3114    /// another privilege than this process sends with, is refused before it
3115    /// sends anything.
3116    ///
3117    /// Over another plan, every settled position would name a different
3118    /// target; under another privilege, answers would be filed as the other
3119    /// kind.
3120    #[cfg(feature = "journal-format")]
3121    #[tokio::test]
3122    async fn a_port_scan_handed_a_journal_of_another_plan_is_refused() {
3123        use crate::journal::Journal;
3124        use crate::journal::manifest::Plan;
3125        use crate::model::target::TargetSet;
3126
3127        let root = journal_root("other-plan");
3128        let map = |ports: &str| {
3129            let mut map = TargetMap::new();
3130            map.add_unit(TargetSet::new(
3131                "127.0.0.1".parse().expect("an address"),
3132                ports.parse().expect("ports"),
3133            ));
3134            map
3135        };
3136        let cfg = ZondConfig::default();
3137        let recorded = Plan::port_scan(&map("1-100"), &cfg.exclusions, cfg.tcp_technique);
3138
3139        let journal = Journal::create(&root, &recorded, Privilege::current(), "").expect("creates");
3140        let refused = scan_with_journal(map("1000-1100"), &cfg, Detections::embedded(), journal)
3141            .await
3142            .err();
3143        assert!(
3144            matches!(refused, Some(ScanError::PlanChanged(_))),
3145            "{refused:?}"
3146        );
3147
3148        let other = Privilege::from_raw(!Privilege::current().is_raw());
3149        let journal = Journal::create(&root, &recorded, other, "").expect("creates");
3150        let refused = scan_with_journal(map("1-100"), &cfg, Detections::embedded(), journal)
3151            .await
3152            .err();
3153        assert!(
3154            matches!(refused, Some(ScanError::PlanChanged(_))),
3155            "{refused:?}"
3156        );
3157
3158        std::fs::remove_dir_all(&root).ok();
3159    }
3160
3161    /// A resume refused up front keeps the record of the earlier sitting.
3162    #[cfg(feature = "journal-format")]
3163    #[tokio::test]
3164    async fn a_refused_resume_keeps_the_record_of_the_sitting_before_it() {
3165        use crate::journal::Journal;
3166        use crate::journal::manifest::Plan;
3167        use crate::journal::settle::{Outcome, Settlements};
3168        use crate::model::ip::set::IpSet;
3169
3170        let root = journal_root("refused-resume");
3171        let addresses: IpSet = "192.0.2.1-192.0.2.4".parse().expect("addresses");
3172        let cfg = refused_up_front();
3173        let plan = Plan::discovery(&addresses, &cfg.exclusions, false);
3174
3175        let mut journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
3176        let settlements = Settlements::default();
3177        settlements.record(Outcome::Answered { position: 0 });
3178        journal.checkpoint(&settlements).expect("checkpoints");
3179        let directory = journal.directory().to_path_buf();
3180        journal.close().expect("closes");
3181
3182        let (journal, _) =
3183            Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
3184        let refused = discover_with_journal(addresses, &cfg, journal).await;
3185        assert!(
3186            matches!(refused, Err(ScanError::Evasion(_))),
3187            "{:?}",
3188            refused.err()
3189        );
3190        assert!(directory.join("manifest.json").exists(), "the record went");
3191
3192        std::fs::remove_dir_all(&root).ok();
3193    }
3194
3195    /// A listener is recorded unprivileged only when privilege refused its
3196    /// capture. A link that refused the filter or carried unreadable framing
3197    /// was opened after the platform's permission check.
3198    #[test]
3199    fn a_listener_is_recorded_unprivileged_only_where_privilege_refused_it() {
3200        use crate::scanner::strategy::StrategyError;
3201        use crate::transport::capture::{CaptureError, LibraryError};
3202
3203        let denied = |link: &str| CaptureError::Denied {
3204            interface: link.into(),
3205            source: LibraryError::new(pcap::Error::PcapError("permission denied".into())),
3206        };
3207        let filter = CaptureError::Filter {
3208            filter: "ip6 and ether proto 0x86dd".into(),
3209            source: LibraryError::new(pcap::Error::PcapError("not an ethernet link".into())),
3210        };
3211        let refused = |refused| StrategyError::Capture(CaptureError::NoInterface { refused });
3212
3213        assert_eq!(
3214            listening_privilege(Some(&refused(vec![("en0".into(), denied("en0"))]))),
3215            Privilege::Connect,
3216            "the platform refused this process"
3217        );
3218        assert_eq!(
3219            listening_privilege(Some(&refused(vec![("utun4".into(), filter)]))),
3220            Privilege::Raw,
3221            "the link refused the filter, after the platform let it open"
3222        );
3223        assert_eq!(listening_privilege(None), Privilege::Raw, "it listened");
3224        assert_eq!(
3225            listening_privilege(Some(&refused(Vec::new()))),
3226            Privilege::current(),
3227            "no link was tried, so the process's own answer is all there is"
3228        );
3229    }
3230
3231    /// A panic's message survives, in both shapes `panic!` produces.
3232    #[tokio::test]
3233    async fn a_panicking_scan_reports_what_the_panic_said() {
3234        for spawned in [
3235            tokio::spawn(async { panic!("a literal message") }),
3236            tokio::spawn(async { panic!("a formatted {}", "message") }),
3237        ] {
3238            let error = panic_or_cancellation(spawned.await.expect_err("the task panicked"));
3239
3240            let ScanError::TaskFailed { panicked, detail } = error else {
3241                unreachable!("a panic is a TaskFailed")
3242            };
3243            assert!(panicked);
3244            assert!(detail.contains("message"), "the payload was lost: {detail}");
3245        }
3246    }
3247
3248    /// A task the runtime cancelled is told apart from one that panicked.
3249    #[tokio::test]
3250    async fn a_cancelled_scan_is_not_reported_as_a_panic() {
3251        let spawned = tokio::spawn(std::future::pending::<()>());
3252        spawned.abort();
3253
3254        let error = panic_or_cancellation(spawned.await.expect_err("the task was cancelled"));
3255
3256        let ScanError::TaskFailed { panicked, .. } = error else {
3257            unreachable!("a cancellation is a TaskFailed")
3258        };
3259        assert!(!panicked);
3260    }
3261
3262    /// Each pass an idle scan declines is said once, in a line that fits.
3263    ///
3264    /// A front end prints the report's refusals at every verbosity, so they
3265    /// are not logged on filing too, and `not covered: ` plus the reason fits
3266    /// in 64 characters.
3267    #[test]
3268    fn an_idle_scans_declined_passes_are_filed_once_each_in_a_short_line() {
3269        use crate::config::{DetectionEnvelope, OsDetection};
3270        use crate::model::finding::DetectionClass;
3271
3272        let cfg = ZondConfig {
3273            idle_scan: Some(crate::config::IdleScan::new(
3274                "192.0.2.9".parse().expect("an address"),
3275            )),
3276            os_detection: OsDetection::Active,
3277            traceroute: true,
3278            characterise: true,
3279            tls_enumeration: true,
3280            ip_protocols: [47].into_iter().collect(),
3281            detection: DetectionEnvelope::up_to(DetectionClass::ActiveBenign),
3282            ..ZondConfig::default()
3283        };
3284        let (_session, ctx) = ScanSession::new();
3285
3286        let said = crate::logging::logged(|| record_idle_refusals(&cfg, &ctx));
3287
3288        let refusals = ctx.take_refusals();
3289        assert_eq!(refusals.len(), 6, "{refusals:?}");
3290        for refusal in &refusals {
3291            let line = format!("not covered: {}", refusal.reason());
3292            assert!(line.len() <= 64, "{} characters: {line}", line.len());
3293        }
3294        assert!(
3295            said.iter()
3296                .all(|line| !line.message.contains("not covered")),
3297            "a refusal was said on filing as well as in the report: {said:?}"
3298        );
3299    }
3300}