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
// 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. Everything in
//! [`crate::scanner::strategy`]'s submodules implements one of them, and
//! [`discover`](crate::scanner::discover) and [`scan`](crate::scanner::scan)
//! know nothing about any strategy beyond these methods.
//!
//! ## 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 deliberately 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 any more.
use async_trait;
use mpsc;
use crateProtocol;
use cratePlannedTarget;
use crate;
/// 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::scanner::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`] or
/// [`Channel`] failure is almost always missing privileges and the same
/// unprivileged fallback answers all of them; an [`Interface`] failure is about
/// one interface and the scan of every other one is unaffected.
///
/// [`Transport`]: StrategyError::Transport
/// [`Channel`]: StrategyError::Channel
/// [`Interface`]: StrategyError::Interface
/// 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.