1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
// Copyright (c) 2026 Erik Lening (hollowpointer) and Contributors
//
// This file is part of Zond Engine, licensed under the GNU Affero General
// Public License, version 3 or later. See the LICENSE file for details, or
// <https://www.gnu.org/licenses/agpl-3.0.html>.
//
// SPDX-License-Identifier: AGPL-3.0-or-later
//! # How fast to ask, and how long to wait
//!
//! Everything a scan uses to decide *when*. Not what it found, and not what it
//! was asked for: those are [`crate::model`] and [`crate::config`]. This is the
//! machinery in between: how long until a probe is repeated, how many times, how
//! long the whole run may take, and when silence has gone on long enough to be
//! an answer.
//!
//! - [`congestion`]: how many probes a scan may have outstanding at once,
//! grown and cut from what the targets are managing to answer. This is what
//! paces a raw port scan; everything else here decides how long to wait, not
//! how hard to push.
//! - [`retry`]: the schedule one probe is repeated on, and the ledger that
//! tracks every outstanding probe against it.
//! - [`deadline`]: how long the whole scan runs, widened or narrowed by what
//! the network is actually doing.
//! - [`rtt_window`]: the recent round trips both of those are sized from.
//! - [`timer`]: the budget a scan is given and the clock it is measured on.
//! - [`limits`](crate::config::limits): the fixed timeouts and ceilings the unprivileged paths run
//! against, which is the one part of this module that does not adapt.
//!
//! That last distinction is the reason [`limits`](crate::config::limits) is a module of its own rather
//! than constants scattered through the strategies. A raw scanner sizes its own
//! patience from round trips it measured; a connect probe cannot, because it
//! sends one SYN and the host stack's retransmission is the only second attempt
//! it gets. Its budget is therefore set against a number in RFC 6298 rather than
//! against the network, and a constant chosen for that reason wants saying once
//! with the reason attached.
//!
//! ## Why this is not part of the vocabulary
//!
//! [`crate::model`] holds what more than one module has to agree on, a host, a
//! port, an address set, and every one of these is agreed on by exactly one: the
//! scanner. A `ProbeLedger` is not something a scan *talks about*, it is how a
//! scan is *run*, and nothing outside this module needs to name one.
//!
//! The knobs a caller actually sets are the exception:
//! [`ScanEffort`](crate::config::ScanEffort) and
//! [`RetryConfig`](crate::config::RetryConfig) live in [`crate::config`],
//! because a person chooses those and a report records them. What they scale is
//! here.
//!
//! ## Why the timings are per path rather than global
//!
//! Every probing path has its own policy, tuned against what its protocol
//! actually requires: a SYN is answered as fast as the path allows, an ICMP
//! error only as fast as the host is permitted to send one, and an IPv6
//! neighbour answers when it next wakes. A single set of numbers describes none
//! of them. What a caller's effort setting does is *scale* each path's own
//! starting point, so asking for a fast scan cannot hand the UDP scanner a
//! schedule its protocol is incapable of satisfying.