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
// 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
//! A network scanner, as a library.
//!
//! Give it addresses and it tells you which hosts are alive; give it hosts and
//! ports and it tells you which of those ports are open and what is listening on
//! them. Everything a front end needs is here — the scanning, the domain model,
//! the report and the file formats — so that a CLI, a web service and an
//! embedded consumer produce the same results and the same documents.
//!
//! # Two phases
//!
//! [`discover`] establishes which hosts exist. [`scan`] classifies the ports of
//! hosts already known. They are separate calls because they cost very different
//! amounts: a sweep of a `/24` is a few hundred packets, and port-scanning all of
//! it is a few hundred thousand. Run the cheap one first and spend the expensive
//! one only on what answered.
//!
//! Both are unprivileged-safe. With root they use raw sockets — ARP and ICMPv6
//! on the local segment, raw TCP and UDP elsewhere — and without it they fall
//! back to ordinary TCP connect attempts. The phase records which it was, so a
//! result can be read for what it is worth.
//!
//! # Live results, and the record afterwards
//!
//! Each call returns a pair. [`ScanSession`] is the live view: hosts appear in
//! its [`HostStore`] as they are found, and each change fires a [`ScanEvent`],
//! so a caller can render a scan in progress instead of waiting for it. The
//! [`ScanTask`] resolves when everything has finished and yields a
//! [`ScanReport`] — the durable record of what was asked for, what came back,
//! what failed on the way, and under which settings.
//!
//! The two answer different questions and both are needed. A bare list of hosts
//! cannot say whether the network is empty or the raw scanner never started;
//! only the report can.
//!
//! ```no_run
//! use zond_engine::{Resolver, ScanEvent, ZondConfig, discover, resolve};
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! // One call: the address grammar, this host's interface table for `lan` and
//! // `%en0`, any hostnames, and whether a segment sweep was asked for.
//! let resolver = Resolver::from_system();
//! let targets = resolve::for_discovery(&["192.168.1.0/24"], Some(&resolver)).await?;
//!
//! let mut cfg = ZondConfig::default();
//! targets.apply_to(&mut cfg);
//!
//! let (mut session, task) = discover(targets.into_ips(), &cfg).await?;
//!
//! // Hosts arrive as they are found.
//! while let Some(event) = session.events().recv().await {
//! if let ScanEvent::HostUpdated(ip) = event
//! && let Some(host) = session.hosts().get(&ip)
//! {
//! println!("{host}");
//! }
//! }
//!
//! // And the record of the sweep once it is over.
//! let report = task.join().await?;
//! println!("{} hosts up", report.summary().hosts_alive);
//! # Ok(())
//! # }
//! ```
//!
//! # Wrapping the engine, or being the orchestrator
//!
//! The example above is the whole API for a front end that wants results:
//! targets in, hosts and a report out, with privilege, interfaces, fallbacks and
//! retries all decided for it. Most callers want exactly that and should not
//! have to learn anything below it.
//!
//! Some callers want to be the one deciding. For them the same machinery is
//! available a layer at a time, and none of it is behind a cargo feature:
//!
//! - **The vocabulary alone.** [`model`] parses targets, holds hosts and ports,
//! and does arithmetic on address sets, without scanning anything. A caller
//! with their own probing code can use it as a domain model and stop there.
//! - **The plan.** [`scanner::plan`] works out which strategies would run
//! against a set of targets on this host, opening nothing. Inspect it, drop
//! steps, reorder them, or print it as a dry run.
//! - **One strategy at a time.** [`scanner::strategy`] holds every scanner the
//! engine uses behind two small traits, each constructible directly and each
//! able to run over a transport the caller opened. Aim one at one segment and
//! read the results out of a [`ScanSession`] you made yourself.
//!
//! The `test-support` feature is *not* the way in to any of this. It gates the
//! synthetic transports the crate's own tests use to fake a network, and nothing
//! else.
//!
//! # Reports out, targets in
//!
//! [`export`] writes a finished report as JSON, JSONL, CSV, a self-contained
//! HTML page, or nmap-compatible XML. [`import`] reads targets back — from a
//! plain list, a CSV, this engine's own JSON, or an nmap XML file somebody else
//! produced — and reads layered settings from TOML. Each format sits behind a
//! cargo feature; `export-json` is the only one on by default.
//!
//! [`import::report`] reads the other direction of the same documents: not the
//! targets to scan next, but what the scan that produced them found, rebuilt as
//! a [`ScanReport`]. That is what lets [`diff`] compare an archived file — this
//! engine's or nmap's — against a scan that just finished.
//!
//! Neither module opens a file or touches standard input. Export writes to a
//! `Write`, import reads from a `BufRead`, and choosing where the bytes come
//! from or go is the caller's business.
//!
//! # What changed since last time
//!
//! [`diff`] compares two [`ScanReport`]s and says what moved: a host that was
//! not there before, a port that opened, a service that changed version, a
//! certificate that rotated or is about to lapse. It is the other half of
//! scanning a network on a schedule, and it asks nothing about where either
//! report came from — one side can be a scan this process just ran, one can be
//! read back out of a [`journal`], and one can be another scanner's output that
//! something built a report from.
//!
//! Every appearance and disappearance carries what the other scan says about
//! whether it covered that target at all, so a narrowed scan does not read as a
//! network that emptied out.
//!
//! # Layout
//!
//! The names most consumers need are re-exported here at the root. The modules
//! below are the whole of it:
//!
//! The list is an order, not a set: each module depends only on the ones above
//! it, and that is a property the crate is arranged to keep rather than an
//! observation about how it happens to look today.
//!
//! - [`model`] — the vocabulary every other module names: [`Host`], [`Port`],
//! [`IpSet`], [`TargetMap`], and the grammars that construct them from what a
//! person wrote. It depends on nothing else here.
//! - [`config`] — what a caller asks for before a scan starts, including the
//! effort a scan is worth spending. Separate from [`model`] because a request
//! is not a finding, and separate from [`scanner`] because a report has to
//! record what was asked for whether or not a scan ever ran.
//! - [`protocols`] — building and parsing packets, as bytes and nothing else.
//! - [`transport`] — the sockets and captures that carry those bytes. Kept apart
//! from [`protocols`] because one half needs a NIC and root and the other half
//! needs neither, and a packet that cannot be built without a socket open is a
//! packet nobody can test. Both are public because crafting a probe is a
//! reasonable thing to want on its own; nothing in the two phases above
//! requires touching them.
//! - [`system`] — interfaces, routing, and whether the process may open raw
//! sockets. The one place the engine asks the host about itself.
//! - [`resolve`] — turning the names a person writes into the addresses a scan
//! probes, over unicast DNS and multicast DNS. It runs before a scan, deciding
//! what it covers; the reverse direction, naming hosts a scan has found, is the
//! scanner's own [`resolver`](scanner::resolver).
//! [`resolve::for_discovery`] is the one call a front end makes: it is where
//! the grammar, this host's interface table, hostname lookup and the
//! segment-sweep question are answered together, rather than being four things
//! for every consumer to remember separately.
//! - [`fingerprint`] — identifying the service behind an open port.
//! - [`scanner`] — the two entry points, the [`plan`](scanner::plan) behind
//! them, and the [`strategy`](scanner::strategy) implementations behind that,
//! together with what running one produces: the live
//! [`session`](scanner::session), the [`handle`](scanner::handle) that stops
//! it, and the [`report`](scanner::report) it leaves behind. Those are the
//! scanner's output rather than a foundation under it, and they live with it
//! for that reason.
//! - [`diff`] — what changed between two scans. It sits above [`scanner`]
//! because it reads the report the scanner leaves behind, and below the file
//! formats because it compares reports rather than documents: where either
//! report came from is not its business.
//! - [`format`](mod@crate::format) — what a reader and a writer of the same document have to agree
//! on, and nothing else. It sits below both so that reading a format never
//! requires compiling the code that writes it.
//! - [`export`], [`import`] — the file formats themselves, which sit above the
//! report because they describe it and it does not know they exist.
//!
//! # Platforms
//!
//! Linux and macOS. Windows is not currently supported.
// Nothing here is public: it is the five macros the engine emits its own
// diagnostics through, and a library that exported those would shadow
// `tracing`'s and `log`'s macros of the same names in any consumer that
// glob-imported it. See the module for the rest of the argument.
pub
// The names a consumer reaches for, at the root rather than four modules deep.
//
// Deliberately a short list. Everything here stays reachable at its full path as
// well, so this is a convenience and never the only way to name a type; what it
// costs is that each name is a commitment, which is why the crate's whole
// vocabulary is not re-exported wholesale.
pub use crate;
pub use crateExclusions;
pub use crate;
pub use crateIpSet;
pub use crate;
pub use crate;
pub use crateTcpScanTechnique;
pub use crate;
pub use crateScanHandle;
pub use crate;
pub use crate;
pub use crateStrategyError;
pub use crate;
pub use crate;
// The engine's own diagnostic macros, reachable as `crate::info!` and friends
// from anywhere in the crate. They are deliberately not part of the public API;
// see `logging` for what exporting them would cost a consumer.
pub use crate;