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
// 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
//! # UDP Probe Payloads
//!
//! What to put *inside* a UDP probe so that the service on the other side has
//! a reason to answer it.
//!
//! ## Why an empty datagram is not enough
//!
//! A TCP scanner gets an answer for free: the handshake is part of the
//! transport, so a SYN is answered by a stack that knows nothing about the
//! service above it. UDP has no such layer. An open port answers only if the
//! *application* recognizes what arrived, and an application handed zero bytes
//! almost always discards them without a word.
//!
//! So a payload-free UDP scan can only ever observe the ICMP half - closed
//! ports - while every genuinely open port falls to the deadline and reports
//! [`OpenFiltered`](crate::model::port::PortState::OpenFiltered). That
//! is a correct verdict for what was asked, and a nearly useless one. Sending
//! something a service will recognize is what turns "no evidence" into
//! evidence.
//!
//! ## Where the payloads live
//!
//! In the fingerprint corpus, `assets/fingerprinting/**/*.toml`, as
//! `protocol = "udp"` entries beside each service's match rules - not in a
//! table of their own.
//!
//! They are the same artifact. A scan payload has to elicit *any* reply; a
//! fingerprint probe has to elicit a *distinguishing* one; and for these
//! services that is one packet, authored once. Keeping them together means
//! adding support for a protocol is one file rather than two, the corpus's
//! build-time validation covers them (`build.rs` rejects a malformed payload
//! outright), and - the part that matters next - the reply a probe draws is
//! already sitting next to the rules that could identify it. A `version.bind`
//! response carries the BIND version string; today the scan counts it as
//! evidence the port is open and discards it.
//!
//! This module is the seam. Scanners ask it what to send, and it answers from
//! the corpus, so the "which payload for this port" policy has one home and the
//! scanners keep no protocol knowledge of their own.
//!
//! ## And what an answer proves
//!
//! [`declared_role`] is the same seam read in the other direction. A reply is
//! already counted as evidence the port is open; for a handful of ports it is
//! also proof of what the host *is*, and that proof is in the reply's own
//! protocol rather than in the port number it came from. Both scanners that
//! send UDP probes — the raw one and the unprivileged fallback — ask here, so a
//! scan concludes the same roles whichever transport it had available.
use crateSignatureDb;
use crateNetworkRole;
use cratedns;
/// Where a name server answers. The rest of the vocabulary a role is read from
/// lives beside each protocol's own parser.
const DNS: u16 = 53;
/// The payload to send when probing `port`.
///
/// Returns an empty slice for a port no service registers a UDP probe for. The
/// scan still works there - a closed port answers with an ICMP error either
/// way - but an open one has nothing to react to and can only ever be reported
/// open-filtered.
///
/// Keyed on the destination port alone, because it is the only thing known
/// about a target before anything answers, which is the whole difficulty of UDP
/// scanning. Where a port registers several probes the first is used: sending
/// all of them would multiply the traffic for a question already answered by
/// any single reply.
/// What a reply to the probe for `port` proves the host *does*, if its own
/// protocol says so.
///
/// **The port is which question to ask, never the answer.** UDP/53 open means
/// something is bound there; a DNS response means a name server answered. The
/// first is a port verdict and already recorded as one, and promoting it to a
/// role would put an infrastructure marking on every host with a socket open.
///
/// One arm per role, and the arms that are missing are missing on purpose.
/// [`NtpServer`](NetworkRole::NtpServer) and [`SnmpAgent`](NetworkRole::SnmpAgent)
/// have probes in the corpus already — 123 and 161 are both sent — so each is
/// one validated reply away from being concluded here, and neither is concluded
/// until that reply is actually read.
// ╔════════════════════════════════════════════╗
// ║ ████████╗███████╗███████╗████████╗███████╗ ║
// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
// ║ ██║ █████╗ ███████╗ ██║ ███████╗ ║
// ║ ██║ ██╔══╝ ╚════██║ ██║ ╚════██║ ║
// ║ ██║ ███████╗███████║ ██║ ███████║ ║
// ║ ╚═╝ ╚══════╝╚══════╝ ╚═╝ ╚══════╝ ║
// ╚════════════════════════════════════════════╝