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
// 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
//! # Forward name resolution
//!
//! Turns the names a person writes — `example.com`, `raspberrypi.local`, `nas`
//! — into the addresses a scan can probe. This is the half of resolution that
//! runs *before* a scan, deciding what it will cover; the reverse half, which
//! attaches names to hosts a scan has already found, lives in
//! [`crate::scanner::resolver`] and answers the opposite question.
//!
//! ## Three kinds of name, one entry point
//!
//! [`Resolver::resolve`] routes a name by how it is resolved, not by asking the
//! caller to know:
//!
//! - A `.local` name is a multicast name (RFC 6762): it is resolved by asking
//! the link over multicast DNS, not by asking a unicast server. A unicast
//! lookup of one fails everywhere the host has no mDNS-aware resolver — which
//! on Linux is the common case — so the engine speaks mDNS itself rather than
//! hope the system does.
//! - Any other name goes to the system's unicast resolver, which applies the
//! host's own search domains and returns A and AAAA records alike.
//! - A single-label name (`nas`) is tried unicast first, and if nothing answers
//! and mDNS is enabled, again as `nas.local` — which on a home network is
//! often what the author meant by it.
//!
//! ## Why a resolver, and not just the hook
//!
//! [`crate::model::parse`] already has the seam a name passes through: a
//! [`HostLookup`](crate::model::parse::target::HostLookup) supplied in a
//! [`TargetContext`](crate::model::parse::target::TargetContext). What it does
//! not have is anything to fill it with, because resolving a name means speaking
//! DNS and mDNS, which a target grammar must not do on its own behalf. This
//! module is what fills it, and it does so without the parse layer learning
//! anything about DNS: the engine resolves the names and hands the answers in.
//!
//! ## The synchronous seam, and the two passes
//!
//! That hook is synchronous — it is called once per name while a target
//! expression is parsed — and resolution is asynchronous and slow, mDNS
//! especially so. Blocking inside the hook would turn a file of two hundred
//! names into two hundred sequential round trips. So resolution is done in two
//! passes, and this module ships both rather than describing them:
//!
//! 1. [`resolve_names`] finds every name in a set of target expressions and
//! resolves them concurrently into a map.
//! 2. [`to_target_map`] and [`to_set`] then build with a hook that reads the
//! map, so the parse itself never waits on the network.
//!
//! A caller that only needs one name resolved can reach for [`Resolver::resolve`]
//! directly; a caller assembling a scan wants [`to_target_map`] or [`to_set`],
//! which do the whole of it.
//!
//! ## What it does not decide
//!
//! Whether a scan is *allowed* to resolve at all — the meaning of
//! [`ZondConfig::no_dns`](crate::config::ZondConfig::no_dns) at request time — is
//! the caller's policy, not this module's: a resolver that refused to run would
//! be a strange thing to hold. A front end that must not emit DNS supplies no
//! resolver, and the parse layer then refuses a name with
//! [`NoHostLookup`](crate::model::parse::target::TargetParseError::NoHostLookup)
//! rather than covering less than its input said.
pub use ;
use IpAddr;
use Duration;
use TokioResolver;
use cratewarn;
/// The default mDNS reply window. See [`ResolveConfig::mdns_timeout`] for why it
/// is a whole second.
const DEFAULT_MDNS_TIMEOUT: Duration = from_secs;
/// How a [`Resolver`] behaves, independent of the host it reads its unicast
/// configuration from.
/// Resolves names to addresses over unicast DNS and multicast DNS.
///
/// Cheap to clone — the unicast resolver it holds is reference-counted — so it
/// can be shared across the concurrent lookups [`resolve_names`] runs.
/// Builds the system unicast resolver, logging and swallowing the two failures
/// that leave a host unable to resolve global names.
/// Whether `name` is resolved over multicast: a multi-label name whose last
/// label is `local`.
///
/// A bare `local` is not one — it is a single-label name that the fallback path
/// may try as `local.local`, not a `.local` host in its own right.
/// Whether `name` is a single label, and so a candidate for the `.local`
/// fallback once unicast has had its say.
// ╔════════════════════════════════════════════╗
// ║ ████████╗███████╗███████╗████████╗███████╗ ║
// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
// ║ ██║ █████╗ ███████╗ ██║ ███████╗ ║
// ║ ██║ ██╔══╝ ╚════██║ ██║ ╚════██║ ║
// ║ ██║ ███████╗███████║ ██║ ███████║ ║
// ║ ╚═╝ ╚══════╝╚══════╝ ╚═╝ ╚══════╝ ║
// ╚════════════════════════════════════════════╝