zond-engine 0.18.0

The core networking library powering Zond. Raw packet injection, protocol parsing, service and OS fingerprinting, and asynchronous network scanning.
Documentation
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
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
// 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 report says it looked at
//!
//! One report's [`TargetScope`]s, flattened across its phases and turned into the
//! question a comparison asks: was this target covered? Every [`Coverage`] answer
//! in a diff comes from here.

use std::net::IpAddr;

use crate::diff::change::Coverage;
use crate::model::host::Host;
use crate::model::ip::set::IpSet;
use crate::model::port::Protocol;
use crate::report::{PortScope, ScanReport, TargetScope};

/// The ranges and port sets a report says it walked, gathered once so an address
/// can be placed without walking the phases again.
///
/// A set rather than a list. Held as two `Vec<IpRange>`, placing one address
/// asked every range of every phase in turn, once per address of every host, and
/// a report merged from a `/16` scanned in chunks carries hundreds of ranges
/// against tens of thousands of questions. [`IpSet`] canonicalises on
/// construction and answers by binary search over disjoint ranges.
pub(crate) struct ScopeIndex {
    covered: IpSet,
    /// What the report as a whole reached no verdict on; see
    /// [`ScanReport::undecided`].
    undecided: IpSet,
    withheld: IpSet,
    stated: bool,
    ports: Vec<PortScope>,
    /// The phases' scopes, kept whole because a link sweep is not a range and
    /// cannot be flattened into one.
    scopes: Vec<TargetScope>,
}

impl ScopeIndex {
    pub(crate) fn of(report: &ScanReport) -> Self {
        let mut covered = IpSet::new();
        let mut undecided = IpSet::new();
        let mut withheld = IpSet::new();
        let mut ports = Vec::new();
        let mut scopes = Vec::new();

        for phase in report.phases() {
            let scope = phase.targets();
            for range in scope.ranges() {
                covered.insert_range(*range);
            }
            for range in scope.excluded() {
                withheld.insert_range(*range);
            }
            ports.push(scope.ports().clone());
            scopes.push(scope.clone());
        }

        // Both are searched and never extended again, so the ordering the
        // search needs is established once here.
        // The report's own reading, so a comparison and the report's
        // `is_partial` agree about what is still open.
        for range in report.undecided() {
            undecided.insert_range(range);
        }
        covered.canonicalize();
        undecided.canonicalize();
        withheld.canonicalize();

        let stated = !covered.is_empty()
            || !withheld.is_empty()
            || scopes.iter().any(|scope| !scope.links().is_empty());
        Self {
            covered,
            undecided,
            withheld,
            stated,
            ports,
            scopes,
        }
    }

    /// Whether the report says anything about which addresses it walked.
    pub(crate) fn states_scope(&self) -> bool {
        self.stated
    }

    /// What the report says about having covered a host.
    ///
    /// Asked of every address the host is known at rather than only the one it
    /// is keyed by. A host is covered if the scan walked ground it was standing
    /// on, and which address a report keys it under is the report's business
    /// rather than the network's: a dual-stack machine keyed under IPv6 in one
    /// scan and IPv4 in the other was in reach of a sweep of the IPv4 range both
    /// times.
    ///
    /// The strongest answer over those addresses wins, on the same reasoning
    /// that makes covered beat withheld for one of them.
    pub(crate) fn of_host(&self, host: &Host) -> Coverage {
        // A sweep of the link the host was found on covers it whatever
        // addresses it holds, so this is asked first and once rather than per
        // address. See `TargetScope::swept`.
        if self.scopes.iter().any(|scope| scope.swept(host.zone())) {
            return Coverage::Covered;
        }

        let mut best = Coverage::Unstated;

        for ip in host.ips() {
            match self.address(ip) {
                Coverage::Covered => return Coverage::Covered,
                Coverage::Withheld => best = Coverage::Withheld,
                Coverage::OutOfScope if best != Coverage::Withheld => {
                    best = Coverage::OutOfScope;
                }
                _ => {}
            }
        }

        best
    }

    /// What the report says about having walked one address, on `zone`.
    ///
    /// Covered wins over withheld, since a job's two phases can disagree: a
    /// discovery sweep that walked an address and a port scan that was forbidden
    /// it still means somebody looked.
    ///
    /// An address the report left [`undecided`](ScanReport::undecided)
    /// answers [`Unreached`](Coverage::Unreached) instead. The scan set out to ask it
    /// and stopped short of an answer, so a host missing there is one nobody
    /// found out about rather than one that went away.
    ///
    /// Whether a link was swept is a separate question, asked by
    /// [`of_host`](Self::of_host), since it is about the host rather than about
    /// any one of its addresses.
    pub(crate) fn address(&self, ip: &IpAddr) -> Coverage {
        if self.undecided.contains(ip) {
            Coverage::Unreached
        } else if self.covered.contains(ip) {
            Coverage::Covered
        } else if self.withheld.contains(ip) {
            Coverage::Withheld
        } else if self.stated {
            Coverage::OutOfScope
        } else {
            Coverage::Unstated
        }
    }

    /// What the report says about having probed one endpoint of an address whose
    /// own coverage is `address`.
    ///
    /// An address nothing walked has no endpoint anything walked, so a withheld
    /// or out-of-scope address carries its answer straight down, and so does
    /// one the scan never reached a verdict on. Otherwise the
    /// phases decide and any phase that cannot say vetoes the rest: a job whose
    /// sweep walked no ports and whose port scan did not record which ports it
    /// walked knows nothing about this endpoint, and the sweep's certainty about
    /// its own half is not the job's.
    pub(crate) fn endpoint(&self, address: Coverage, port: u16, protocol: Protocol) -> Coverage {
        if address.is_excluded() || address == Coverage::Unreached {
            return address;
        }

        let mut stated = false;
        let mut cannot_say = false;

        for scope in &self.ports {
            match scope.covers(port, protocol) {
                Some(true) => return Coverage::Covered,
                Some(false) => stated = true,
                None => cannot_say = true,
            }
        }

        if cannot_say {
            Coverage::Unstated
        } else if stated {
            Coverage::OutOfScope
        } else {
            Coverage::Unstated
        }
    }
}

// ╔════════════════════════════════════════════╗
// ║ ████████╗███████╗███████╗████████╗███████╗ ║
// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
// ║    ██║   █████╗  ███████╗   ██║   ███████╗ ║
// ║    ██║   ██╔══╝  ╚════██║   ██║   ╚════██║ ║
// ║    ██║   ███████╗███████║   ██║   ███████║ ║
// ║    ╚═╝   ╚══════╝╚══════╝   ╚═╝   ╚══════╝ ║
// ╚════════════════════════════════════════════╝

#[cfg(test)]
mod tests {
    use crate::system::privilege::Privilege;
    use std::net::Ipv4Addr;
    use std::time::{Duration, SystemTime};

    use super::*;
    use crate::config::ZondConfig;
    use crate::model::exclusion::Exclusions;
    use crate::model::ip::range::IpRange;
    use crate::model::ip::set::IpSet;
    use crate::model::parse::ip::to_set;
    use crate::report::{PhaseParts, ScanKind, ScanPhase, ScanSettings, ScopeParts};

    fn ip(last: u8) -> IpAddr {
        IpAddr::V4(Ipv4Addr::new(203, 0, 113, last))
    }

    /// A report stating what it walked and what its policy withheld.
    ///
    /// Built through [`TargetScope::from_ip_set`] with real [`Exclusions`], so
    /// the withheld ranges are subtracted from the walked ones the way a scan
    /// subtracts them. Listing a range as both walked and excluded would make a
    /// fixture no scan can produce.
    fn report(covered: &[&str], excluded: &[&str], ports: PortScope) -> ScanReport {
        let exclusions = if excluded.is_empty() {
            Exclusions::none()
        } else {
            Exclusions::new(to_set(excluded, None, None).expect("parseable ranges"))
        };

        let mut targets = if covered.is_empty() {
            IpSet::new()
        } else {
            to_set(covered, None, None).expect("parseable ranges")
        };
        let walked = TargetScope::from_ip_set(&mut targets, &exclusions);

        let scope = TargetScope::from_parts(ScopeParts {
            listened: Vec::new(),
            ranges: walked.ranges().to_vec(),
            links: Vec::new(),
            addresses: walked.addresses(),
            probes: None,
            ports,
            protocols: Vec::new(),
            excluded: walked.excluded().to_vec(),
            withheld: walked.withheld(),
        });

        let phase = ScanPhase::from_parts(PhaseParts {
            open: false,
            attachments: Vec::new(),
            kind: ScanKind::Discovery,
            started_at: SystemTime::UNIX_EPOCH,
            elapsed: Duration::from_secs(1),
            privilege: Some(Privilege::Raw),
            targets: scope,
            settings: ScanSettings::from(&ZondConfig::default()),
            failures: Vec::new(),
            refusals: Vec::new(),
            unroutable: Vec::new(),
            refused_by_route: Vec::new(),
            timed_out: Vec::new(),
            icmp_rate_limited: Vec::new(),
            reached_by_connect: Vec::new(),
            undecided: Vec::new(),
            liveness_skipped: None,
            silent: Vec::new(),
            stopped: None,
            passes_cut: Vec::new(),
            unreached: 0,
            unheard_probes: 0,
            probes: Vec::new(),
            origin: None,
        });

        ScanReport::recorded("test", vec![phase], Vec::new())
    }

    /// A discovery phase over `walked` that reached no verdict on `open`.
    fn phase_leaving(walked: &str, open: &str) -> ScanPhase {
        let mut targets = to_set(&[walked], None, None).expect("a parseable range");
        let scope = TargetScope::from_ip_set(&mut targets, &Exclusions::none());
        let open = to_set(&[open], None, None).expect("a parseable range");

        ScanPhase::from_parts(PhaseParts {
            open: false,
            attachments: Vec::new(),
            kind: ScanKind::Discovery,
            started_at: SystemTime::UNIX_EPOCH,
            elapsed: Duration::from_secs(1),
            privilege: Some(Privilege::Raw),
            targets: scope,
            settings: ScanSettings::from(&ZondConfig::default()),
            failures: Vec::new(),
            refusals: Vec::new(),
            unroutable: Vec::new(),
            refused_by_route: Vec::new(),
            timed_out: Vec::new(),
            icmp_rate_limited: Vec::new(),
            reached_by_connect: Vec::new(),
            undecided: open.v4().iter().copied().map(IpRange::V4).collect(),
            liveness_skipped: None,
            silent: Vec::new(),
            stopped: None,
            passes_cut: Vec::new(),
            unreached: 0,
            unheard_probes: 0,
            probes: Vec::new(),
            origin: None,
        })
    }

    /// **An address a port phase asked and found silent is covered.** The phase
    /// stood in for a liveness pass and asked every port there, so a host last
    /// seen at that address and absent now reads as the liveness pass would
    /// have left it, gone from a place that was looked at, and never as ground
    /// the scan did not reach.
    #[test]
    fn an_address_a_port_phase_found_silent_is_covered() {
        let mut walked = to_set(&["203.0.113.0/24"], None, None).expect("a range");
        let silent = to_set(&["203.0.113.5"], None, None).expect("an address");
        let phase = ScanPhase::from_parts(PhaseParts {
            open: false,
            attachments: Vec::new(),
            kind: ScanKind::PortScan,
            started_at: SystemTime::UNIX_EPOCH,
            elapsed: Duration::from_secs(1),
            privilege: Some(Privilege::Raw),
            targets: TargetScope::from_ip_set(&mut walked, &Exclusions::none()),
            settings: ScanSettings::from(&ZondConfig::default()),
            failures: Vec::new(),
            refusals: Vec::new(),
            unroutable: Vec::new(),
            refused_by_route: Vec::new(),
            timed_out: Vec::new(),
            icmp_rate_limited: Vec::new(),
            reached_by_connect: Vec::new(),
            undecided: Vec::new(),
            liveness_skipped: Some(crate::report::LivenessSkip::PortsNoDearer),
            silent: silent.v4().iter().copied().map(IpRange::V4).collect(),
            stopped: None,
            passes_cut: Vec::new(),
            unreached: 0,
            unheard_probes: 0,
            probes: Vec::new(),
            origin: None,
        });
        let report = ScanReport::recorded("test", vec![phase], Vec::new());

        assert_eq!(
            ScopeIndex::of(&report).address(&ip(5)),
            Coverage::Covered,
            "asked and silent, not unreached"
        );
    }

    /// **An address a stopped sweep never decided is unreached, not covered.**
    /// Its scope says the sweep set out to ask, and its undecided list says it
    /// never got an answer, so a host last seen there is not one that went
    /// away. Read as covered, every host past the point a sweep was stopped
    /// would be reported gone.
    #[test]
    fn an_address_a_phase_left_undecided_is_unreached_and_so_are_its_ports() {
        let report = ScanReport::recorded(
            "test",
            vec![phase_leaving("203.0.113.0/24", "203.0.113.128/25")],
            Vec::new(),
        );
        let index = ScopeIndex::of(&report);

        assert_eq!(index.address(&ip(7)), Coverage::Covered, "decided");
        let open = index.address(&ip(200));
        assert_eq!(open, Coverage::Unreached, "walked, never decided");
        assert_eq!(
            index.endpoint(open, 443, Protocol::Tcp),
            Coverage::Unreached,
            "nothing was probed at an address nobody reached"
        );
    }

    /// One phase's gap is not the job's when another phase decided it: the
    /// second sitting of a resumed sweep asks what the first left open.
    #[test]
    fn an_address_another_phase_decided_is_covered() {
        let report = ScanReport::recorded(
            "test",
            vec![
                phase_leaving("203.0.113.0/24", "203.0.113.128/25"),
                phase_leaving("203.0.113.128/25", "203.0.113.250"),
            ],
            Vec::new(),
        );
        let index = ScopeIndex::of(&report);

        assert_eq!(index.address(&ip(200)), Coverage::Covered);
        assert_eq!(
            index.address(&ip(250)),
            Coverage::Unreached,
            "and one neither sitting decided is still open"
        );
    }

    #[test]
    fn an_address_inside_a_walked_range_is_covered() {
        let index = ScopeIndex::of(&report(&["203.0.113.0/24"], &[], PortScope::NoPorts));
        assert_eq!(index.address(&ip(7)), Coverage::Covered);
    }

    /// A range the policy withheld is not the same as one the scan never named:
    /// the report says it was told not to look.
    #[test]
    fn an_address_the_policy_withheld_is_reported_as_withheld() {
        let index = ScopeIndex::of(&report(
            &["203.0.113.0/24"],
            &["203.0.113.64/26"],
            PortScope::NoPorts,
        ));
        assert_eq!(index.address(&ip(100)), Coverage::Withheld);
        assert_eq!(index.address(&ip(7)), Coverage::Covered);
    }

    #[test]
    fn an_address_outside_a_stated_scope_is_out_of_scope() {
        let index = ScopeIndex::of(&report(&["203.0.113.0/25"], &[], PortScope::NoPorts));
        assert_eq!(index.address(&ip(200)), Coverage::OutOfScope);
    }

    /// A report that states no scope cannot answer the question, and says so
    /// rather than guessing.
    #[test]
    fn a_report_that_states_no_scope_answers_unstated() {
        let index = ScopeIndex::of(&report(&[], &[], PortScope::NoPorts));
        assert!(!index.states_scope());
        assert_eq!(index.address(&ip(7)), Coverage::Unstated);
    }

    #[test]
    fn an_endpoint_is_no_better_covered_than_its_address() {
        let index = ScopeIndex::of(&report(&["203.0.113.0/24"], &[], PortScope::NoPorts));
        assert_eq!(
            index.endpoint(Coverage::OutOfScope, 22, Protocol::Tcp),
            Coverage::OutOfScope,
            "a port on an address nobody walked is not covered"
        );
    }
}