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
// 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
//! # Turning a response into the text the corpus is written against
//!
//! **A signature matches a field, not a reply.** Every rule declares the
//! `context` it reads — `ssh.banner`, `snmp.sys_description`,
//! `http.server_header` — and anchors its pattern on that field's text alone.
//! Something has to produce that field from what actually arrived, and this is
//! where that happens.
//!
//! ## The mistake this module exists to stop repeating
//!
//! It has been made twice, silently, and cost a working corpus both times.
//!
//! RFC 4253 §4.2 gives an SSH identification line as
//! `SSH-protoversion-softwareversion SP comments`, and the corpus anchors on the
//! software identifier: `^OpenSSH_(9\.2p1) (Debian-\d\d?\+deb12u\d+)$`. Fed the
//! whole line, that `^` can never match — so **every release-naming SSH rule was
//! unreachable**, and a host announcing `SSH-2.0-OpenSSH_9.2p1 Debian-2+deb12u10`
//! was reported as `Linux` while the corpus held a rule mapping that exact
//! string to Debian 12.
//!
//! SNMP is the same shape one protocol over: `sysDescr` is a BER-encoded octet
//! string inside a `GetResponse`, and the rules match the decoded text. A
//! datagram handed to them matches nothing.
//!
//! Both failures look identical from outside — a scan that names a family and
//! stops — and neither shows up as a broken test, because a test that feeds the
//! matcher a field directly passes while the engine feeds it a whole response.
//!
//! ## Keyed on the port, because that is what is known
//!
//! [`from_datagram`] selects a decoder by destination port, exactly as
//! [`payload`](crate::scanner::payload) selects a probe by one. It is the only
//! thing known about a UDP target before anything answers, which is the whole
//! difficulty of UDP scanning, and pairing the two on the same key keeps the
//! probe and the reading of its answer from drifting apart.
use crateProtocol;
/// The texts one banner should be matched against, most complete first.
///
/// Usually just the banner. A structured one also yields the field the corpus
/// anchors on, and **both are offered** rather than the field replacing the
/// line: a rule may legitimately be written against either, and which is more
/// specific is a question for the matcher's own ranking rather than for this.
pub
/// The text a UDP reply carries, where this engine knows how to read one.
///
/// `None` for a port whose replies it cannot decode, which is most of them: a
/// datagram nothing can read is still proof the port is open, and that is what
/// the scan already took from it.
///
/// Returns an owned string because decoding is not always a borrow — a value
/// lifted out of a binary encoding has no text in the datagram to point at.
pub
/// Whether this engine can read a reply from `port` over `protocol` at all.
///
/// What decides whether a UDP port is worth a second datagram: there is no
/// point dialling one whose answer nothing here could turn into text. A TCP
/// port always qualifies — every one of them can be read for a banner.
pub
/// The UDP ports [`from_datagram`] has a decoder for.
///
/// Stated rather than derived, because a decoder cannot be asked whether it
/// would succeed without a datagram to try it on, and this question is asked
/// before one has been drawn.
const DECODED_UDP_PORTS: & = &;
// ╔════════════════════════════════════════════╗
// ║ ████████╗███████╗███████╗████████╗███████╗ ║
// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
// ║ ██║ █████╗ ███████╗ ██║ ███████╗ ║
// ║ ██║ ██╔══╝ ╚════██║ ██║ ╚════██║ ║
// ║ ██║ ███████╗███████║ ██║ ███████║ ║
// ║ ╚═╝ ╚══════╝╚══════╝ ╚═╝ ╚══════╝ ║
// ╚════════════════════════════════════════════╝