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