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
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
// 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
//! # What a scanning strategy is
//!
//! Two traits, one per phase, and the error a strategy fails with.
//! [`discover`](crate::scanner::discover) and [`scan`](crate::scanner::scan)
//! know nothing about any strategy beyond these methods.
//!
//! ## How the submodules are arranged
//!
//! By the phase a strategy serves, which is the same axis
//! [`ScanKind`](crate::report::ScanKind) and
//! [`PhaseRecorder`](crate::scanner::recorder::PhaseRecorder) are written in.
//! Transport and privilege vary *inside* a category rather than naming one,
//! because varying over them is what these two traits are for.
//!
//! | module | what it is |
//! |---|---|
//! | [`local`], [`routed`], [`connect`] | which hosts are there: at the link layer, through a gateway, or by ordinary connect |
//! | [`ports`] | which ports are open |
//! | [`identify`] | what a machine is, asked of hosts already found |
//! | [`topology`] | what is between here and a host |
//! | [`passive`] | what a link already carries, having sent nothing |
//! | [`composite`] | routes each target to a strategy that covers its protocol |
//! | `raw`, `frames`, `icmp_error`, `sweep` | not strategies, and internal: what they are built from, what they read, and what they all keep track of |
//!
//! Arranged by the target's network position instead, the two axes cross:
//! `routed` would mean "reached through a gateway" for one strategy and "opens a
//! raw socket" for the ten others that would sit underneath it, including every
//! port scanner, both operating-system probes and the trace. What each of them
//! *is* decides where it sits.
//!
//! ## Findings go to the context, not to the return value
//!
//! Neither trait returns what it found. A strategy writes hosts and ports into
//! the [`ScanContext`] it was built with, and its run method reports only
//! whether the attempt itself got to the end. That is what makes an ARP sweep,
//! a raw SYN scan and a plain TCP connect interchangeable to a caller: build
//! one, run it, read the store, and it is what lets several unrelated
//! strategies write into a single live view while they are still running, which
//! a return value cannot do.
//!
//! It also draws the line between the two ways a scan goes wrong. A target that
//! did not answer is a *finding*, and it lands in the store. A strategy that
//! could not open its socket is a *failure*, and it comes back as
//! [`StrategyError`]. Only the second is an `Err`, because only the second means
//! the absence of hosts proves nothing.
//!
//! ## The two traits are the same shape
//!
//! Both carry a [`kind`](HostScanner::kind), both take `&mut self`, both return
//! `Result<(), StrategyError>`. Where they differ they differ for a reason:
//! a [`PortScanner`] is fed its targets on a channel and declares which
//! protocols it covers, because several of them run at once and something has
//! to route each target to one that can take it; a [`HostScanner`] owns its
//! targets from construction, because a sweep is aimed at a segment rather than
//! dispatched a target at a time.
//!
//! Neither consumes `self`. A strategy runs once in practice, but taking
//! `self: Box<Self>` to say so would force every caller to box a scanner it
//! already owns, and the orchestrator is not the only caller.
use async_trait;
use mpsc;
use crateOutcome;
use crate;
use cratePlannedTarget;
use crateScannerKind;
use crateScanContext;
/// Why one scanning strategy could not start, or could not finish.
///
/// This is not how a scan fails. A scan runs several strategies and carries
/// on with whatever survives, so one of these is recorded in the report's
/// [`failures`](crate::report::ScanReport::failures) and announced on
/// the event stream rather than returned from
/// [`discover`](crate::scanner::discover) or [`scan`](crate::scanner::scan). It
/// reaches a caller directly when they build and run a strategy themselves.
///
/// The variants are the layers a strategy is assembled from, because that is
/// what determines whether anything can be done about it. A [`Transport`],
/// [`Channel`] or [`Capture`] failure is most often missing privileges, which
/// the same unprivileged fallback answers for a scan, though not always, and
/// the capture error underneath says which; an [`Interface`] failure is about
/// one interface and the scan of every other one is unaffected.
///
/// [`Transport`]: StrategyError::Transport
/// [`Channel`]: StrategyError::Channel
/// [`Capture`]: StrategyError::Capture
/// [`Interface`]: StrategyError::Interface
/// A port scan's protocol in words, with its article, as
/// [`StrategyError::MismatchedTransport`] names the scan it was handed.
const
/// A strategy that finds which hosts, among the targets it was built with, are
/// reachable.
///
/// The discovery half of the pair. Implementations differ entirely in how they
/// ask, ARP and ICMPv6 on a local segment, raw TCP SYN through a gateway, an
/// ordinary connect attempt where neither is possible, and not at all in what a
/// caller does with them.
/// A strategy that classifies the ports of targets handed to it one at a time.
///
/// The port-scan half of the pair. Where a [`HostScanner`] is aimed at a segment
/// it owns, this consumes the shuffled [`PlannedTarget`] stream a
/// [`Dispatcher`](crate::scanner::dispatcher::Dispatcher) produces, so that
/// several strategies can share one stream of work and none of them has to know
/// how the targets were ordered.
/// Records `target`, which no scanner asked about, as a port nobody asked
/// about: on its host as [`PortState::Unasked`], and owed to a resume.
///
/// The one account of a port left unprobed that holds whoever leaves it: a
/// scanner stopped with it still queued, a scanner that refused its whole
/// plan, and a router with no scanner left to hand it to. Left off the host
/// instead, a truncated port list reads the same as a complete one, a host the
/// scan never reached is missing from the report altogether, and a port list
/// whose shape depends on how a run ended reads, compared with another scan's,
/// as the network moving. The outcome carries no position, so a resume asks
/// the question this sitting did not.
pub
// The reader two scanners share for what an ICMP error says: a UDP port scan
// reads a port's verdict out of one, and a trace reads a router's identity out
// of one. Neither owns it, and it is a parser rather than a strategy.
pub
// The readers two strategies share: a local sweep interprets the replies its
// probes draw with them, and a listener interprets frames nobody asked for with
// the same ones. A frame that proves a host is there proves it either way.
//
// Named for what it reads rather than for the phase that reads it: `discovery`
// collided with `scanner::discover` and `ScanKind::Discovery`, neither of which
// this is.
pub
// What a machine is, asked of hosts a scan has already found. Neither of these
// discovers anything: they revisit what the store holds and read a stack off
// what answers.
// Which ports are open, and the machinery all four raw port scanners share.
// Which IP protocols a host takes delivery of, one layer below the ports. Runs
// after them, and only against hosts that answered, for the reason `topology`
// gives about its own two passes.
// What every raw strategy is built from: how a probe reaches the wire, and the
// timings a probe over a routed path is held to.
pub
// What the three probing sweeps keep track of in common.
pub
// What is between here and a host, rather than what is at it. Both passes here
// run after the ports are known, because what reaches a host is what decides
// how to ask about the path to it.