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
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
// 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 became of a target, and whether a resume may skip it
//!
//! A raw port scan gives the same verdict to a target whose retry budget ran out
//! and to one still mid-schedule when the scan stopped. Both were asked and
//! neither answered; how many times the question was repeated is the difference,
//! and a report reads them as one silence. A target no probe was sent to is
//! recorded [`PortState::Unasked`](crate::model::port::PortState::Unasked)
//! instead, since it is a fact about the scan rather than a reading of silence.
//!
//! A resume can afford neither blurring. A cursor advanced over a target nobody
//! probed produces a second sitting that skips it and a merged report claiming
//! coverage it never had.
//!
//! [`Outcome`] makes the distinction unforgeable. Only the settled variants carry
//! a position, and a position is the only thing a cursor can advance over.
//!
//! | Outcome | Decided at | Position |
//! |---|---|---|
//! | [`Answered`](Outcome::Answered) | `ledger.resolve(..) -> Some` | yes |
//! | [`Exhausted`](Outcome::Exhausted) | `Due::Exhausted` | yes |
//! | [`Skipped`](Outcome::Skipped) | the liveness pass heard silence | yes |
//! | [`Withheld`](Outcome::Withheld) | the exclusion policy names its machine | yes |
//! | [`Unreachable`](Outcome::Unreachable) | its address was filed as one no route leads to | yes |
//! | [`Interrupted`](Outcome::Interrupted) | `ledger.drain_unresolved()` | no |
//! | [`Unasked`](Outcome::Unasked) | no probe was sent | no |
//! | [`Undecided`](Outcome::Undecided) | the liveness pass reached no verdict | no |
//! | [`Unroutable`](Outcome::Unroutable) | no scanner for the protocol, or a send refused | no |
//!
//! Unsettled outcomes are counted, not stored. Their total is worth reporting;
//! which targets they were is not, since every one is re-probed anyway.

use std::sync::Mutex;
use std::sync::atomic::{AtomicU64, Ordering};

use super::cursor::{Checkpoint, Cursor};
use crate::model::order::Permutation;

/// The two outcomes a probe earns, before the position is attached.
///
/// A caller that has earned a verdict says which of these it earned, and
/// something that knows the plan attaches the position. See
/// [`ScanContext::settle_address`](crate::scanner::session::ScanContext::settle_address),
/// which is how a sweep settles an address it does not know the number of.
///
/// Not every settled outcome is here, since not every one is earned by a probe.
/// [`Skipped`](Outcome::Skipped) is the liveness pass deciding no probe was owed,
/// and whatever reaches that conclusion already knows the position, so it builds
/// the outcome directly. The unsettled outcomes carry no position, so there is
/// nothing to attach and they are recorded straight through
/// [`Settlements::record`].
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Settled {
    /// The target answered.
    Answered,
    /// Its retry budget was spent without an answer.
    Exhausted,
}

impl Settled {
    /// The outcome this settlement is, at `position`.
    pub fn at(self, position: u64) -> Outcome {
        match self {
            Settled::Answered => Outcome::Answered { position },
            Settled::Exhausted => Outcome::Exhausted { position },
        }
    }
}

/// What became of one target in one sitting.
///
/// Settled variants carry the target's position in the plan's enumeration; see
/// [`PlannedTarget`](crate::model::target::PlannedTarget).
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum Outcome {
    /// The target answered. Settled.
    Answered {
        /// Its position in the plan.
        position: u64,
    },

    /// The retry budget was spent without an answer: silence, asked for as many
    /// times as the policy allows. Settled, since waiting longer could not have
    /// changed it.
    Exhausted {
        /// Its position in the plan.
        position: u64,
    },

    /// Its host answered nothing in the liveness pass, so no probe was owed.
    ///
    /// Settled, and the one settled outcome no probe was sent for. The evidence
    /// is still earned: the scan asked whether the host was there as many
    /// times as its policy allows and heard nothing, so declining to spend a
    /// probe per port on it is work decided against rather than work missed.
    /// That is the difference between this and
    /// [`Undecided`](Outcome::Undecided), where the pass never reached that
    /// verdict.
    ///
    /// So a resumed scan does not revisit those ports even if the host answers
    /// next time. A resume continues one job, and that job's finding about the
    /// host was that it was down; asking again is a new scan, which is what
    /// [`JournalManifest`](crate::journal::manifest::JournalManifest) says about
    /// a plan that has moved.
    /// [`ZondConfig::assume_up`](crate::config::ZondConfig::assume_up) is how a
    /// caller declines the bargain.
    Skipped {
        /// Its position in the plan.
        position: u64,
    },

    /// Its address answers from the hardware of a machine the exclusion
    /// policy names, so no probe was allowed.
    ///
    /// Settled, and like [`Skipped`](Outcome::Skipped) sent nothing. The
    /// policy names an address and means the machine answering at it, and
    /// this host's neighbour tables tied the target's address to that machine
    /// before anything was sent; see
    /// [the machine an address names](crate::model::exclusion#an-address-names-a-machine).
    /// A resume does not ask it either, whatever the tables say by then,
    /// since the one direction an exclusion may err in is withholding more.
    Withheld {
        /// Its position in the plan.
        position: u64,
    },

    /// Its address was filed as one this machine cannot reach: no route or
    /// source address led there, a route refused by its type, or the
    /// neighbour never answered address resolution.
    ///
    /// Settled, though nothing was sent. The refusal is this machine's routing
    /// answering for the address, and asking again within the job would draw
    /// the same answer, as asking a silent host again would; left unsettled,
    /// every target at such an address kept a finished job resumable and was
    /// asked again by every sitting. A resume continues one job, so a route
    /// that appears later is a reason for a new scan, as a host that comes up
    /// is under [`Skipped`](Outcome::Skipped).
    ///
    /// Recorded when the address is filed, over every target the plan numbers
    /// at it, which is why it is apart from [`Unroutable`](Outcome::Unroutable):
    /// that is the one target a scanner could not send, counted as it happens.
    /// See
    /// [`ScanContext::record_unroutable`](crate::scanner::session::ScanContext::record_unroutable).
    Unreachable {
        /// Its position in the plan.
        position: u64,
    },

    /// Outstanding mid-retry-schedule when the scan stopped. The schedule was
    /// cut off rather than spent.
    Interrupted,

    /// No probe was sent: the target was still queued when the scan stopped, its
    /// host had already spent its own budget, or this machine's sender refused
    /// the send.
    Unasked,

    /// No scanner spoke its protocol, or this machine refused to send the
    /// probe. Usually a missing privilege or a local fault rather than a fact
    /// about the target, and those can differ between sittings. A target whose
    /// address the scan then files as one no route leads to is settled over
    /// this, as [`Unreachable`](Outcome::Unreachable).
    Unroutable,

    /// The liveness pass reached no verdict on its host, so it was neither
    /// probed nor written off.
    ///
    /// The pass stopped before it asked, stopped while it was still asking, had
    /// no strategy that could ask, or was refused the range. None of those is
    /// silence, and settling one as [`Skipped`](Outcome::Skipped) would have a
    /// resume skip a host nobody asked about and report it down. Unsettled, so
    /// the next sitting's liveness pass asks about the host again.
    Undecided,
}

impl Outcome {
    /// The position a resume may skip, or `None` where the scan did not earn
    /// one.
    pub fn settled_position(self) -> Option<u64> {
        match self {
            Outcome::Answered { position }
            | Outcome::Exhausted { position }
            | Outcome::Skipped { position }
            | Outcome::Withheld { position }
            | Outcome::Unreachable { position } => Some(position),
            Outcome::Interrupted | Outcome::Unasked | Outcome::Unroutable | Outcome::Undecided => {
                None
            }
        }
    }

    /// Whether a resume may skip this target.
    pub fn is_settled(self) -> bool {
        self.settled_position().is_some()
    }

    /// The wire name, for diagnostics and for reporting a sitting's shape.
    pub fn name(self) -> &'static str {
        match self {
            Outcome::Answered { .. } => "answered",
            Outcome::Exhausted { .. } => "exhausted",
            Outcome::Skipped { .. } => "skipped",
            Outcome::Withheld { .. } => "withheld",
            Outcome::Unreachable { .. } => "unreachable",
            Outcome::Interrupted => "interrupted",
            Outcome::Unasked => "unasked",
            Outcome::Unroutable => "unroutable",
            Outcome::Undecided => "undecided",
        }
    }
}

/// How a sitting ended for each of its targets: a cursor over what settled, and
/// counts of what did not.
///
/// Memory follows how far out of order the scan settled, never how many targets
/// it had: a handful of positions for a plan settled in plan order or in the
/// order it was walked. See [`cursor`](super::cursor).
#[derive(Debug, Default)]
pub struct Settlements {
    cursor: Mutex<Cursor>,
    answered: AtomicU64,
    exhausted: AtomicU64,
    skipped: AtomicU64,
    withheld: AtomicU64,
    unreachable: AtomicU64,
    interrupted: AtomicU64,
    unasked: AtomicU64,
    unroutable: AtomicU64,
    undecided: AtomicU64,
}

impl Settlements {
    /// Begins from a checkpoint, so a resumed sitting keeps what the first
    /// settled.
    pub fn resuming(checkpoint: &Checkpoint) -> Self {
        Self {
            cursor: Mutex::new(Cursor::from_checkpoint(checkpoint)),
            ..Self::default()
        }
    }

    /// Begins from a checkpoint, counting along `order` as well where the
    /// scan asks its targets in one. See [`Cursor::walking`] for what that
    /// saves.
    pub(crate) fn walking(checkpoint: &Checkpoint, order: Option<Permutation>) -> Self {
        let cursor = Cursor::from_checkpoint(checkpoint);
        Self {
            cursor: Mutex::new(match order {
                Some(order) => cursor.along(order),
                None => cursor,
            }),
            ..Self::default()
        }
    }

    /// Counts along `order` as well, from here on, where nothing has given
    /// this count a walk yet.
    ///
    /// For the stream that takes the walk to name it. A session built without
    /// a plan cannot know the walk its dispatcher will take, and a count kept
    /// in plan order alone of targets asked along a walk holds nearly every
    /// settled position above its watermark: half the plan at the halfway
    /// mark. A count that already has a walk keeps it; see [`Cursor::along`].
    pub(crate) fn walk_along(&self, order: Permutation) {
        self.with_cursor(|cursor| *cursor = std::mem::take(cursor).along(order));
    }

    /// Records what became of one target.
    pub fn record(&self, outcome: Outcome) {
        self.counter(outcome).fetch_add(1, Ordering::Relaxed);

        if let Some(position) = outcome.settled_position() {
            self.with_cursor(|cursor| cursor.settle(position));
        }
    }

    /// Whether the target at `position` is settled, by this sitting or an
    /// earlier one.
    pub(crate) fn is_settled(&self, position: u64) -> bool {
        self.with_cursor(|cursor| cursor.is_settled(position))
    }

    /// Records `outcome`, a settled one, unless its target is settled
    /// already.
    ///
    /// For an account given after the fact over every target at an address,
    /// some of which earned a verdict of their own first: those keep it, and
    /// are not counted twice.
    pub(crate) fn record_unsettled(&self, outcome: Outcome) {
        let Some(position) = outcome.settled_position() else {
            return;
        };
        let fresh = self.with_cursor(|cursor| {
            let fresh = !cursor.is_settled(position);
            cursor.settle(position);
            fresh
        });
        if fresh {
            self.counter(outcome).fetch_add(1, Ordering::Relaxed);
        }
    }

    /// Records `count` targets ending the same way.
    ///
    /// For the unsettled outcomes, which are counted rather than stored. A sweep
    /// cut short can leave millions of addresses unasked, and they are one fact
    /// rather than a million. A settled outcome names one position, so repeating
    /// it here would count one target many times; those go through
    /// [`record`](Self::record) one at a time.
    pub fn record_many(&self, outcome: Outcome, count: u64) {
        debug_assert!(
            !outcome.is_settled(),
            "a settled outcome names one position and cannot stand for many"
        );
        self.counter(outcome).fetch_add(count, Ordering::Relaxed);
    }

    /// A snapshot to write down.
    pub fn checkpoint(&self) -> Checkpoint {
        self.with_cursor(|cursor| cursor.checkpoint())
    }

    /// How many targets are settled in total, this sitting and any it resumed.
    pub fn settled_count(&self) -> u64 {
        self.with_cursor(|cursor| cursor.settled_count())
    }

    /// How many targets ended in `outcome`'s variant this sitting. The position
    /// of a settled variant is ignored, so any will do.
    pub fn count(&self, outcome: Outcome) -> u64 {
        self.counter(outcome).load(Ordering::Relaxed)
    }

    fn counter(&self, outcome: Outcome) -> &AtomicU64 {
        match outcome {
            Outcome::Answered { .. } => &self.answered,
            Outcome::Exhausted { .. } => &self.exhausted,
            Outcome::Skipped { .. } => &self.skipped,
            Outcome::Withheld { .. } => &self.withheld,
            Outcome::Unreachable { .. } => &self.unreachable,
            Outcome::Interrupted => &self.interrupted,
            Outcome::Unasked => &self.unasked,
            Outcome::Unroutable => &self.unroutable,
            Outcome::Undecided => &self.undecided,
        }
    }

    fn with_cursor<R>(&self, read: impl FnOnce(&mut Cursor) -> R) -> R {
        let mut cursor = self.cursor.lock().unwrap_or_else(|e| e.into_inner());
        read(&mut cursor)
    }
}

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

#[cfg(test)]
mod tests {
    use super::*;

    /// The rule the type exists to enforce.
    #[test]
    fn only_an_earned_outcome_carries_a_position() {
        assert_eq!(
            Outcome::Answered { position: 7 }.settled_position(),
            Some(7)
        );
        assert_eq!(
            Outcome::Exhausted { position: 7 }.settled_position(),
            Some(7)
        );

        assert_eq!(Outcome::Skipped { position: 7 }.settled_position(), Some(7));
        assert_eq!(
            Outcome::Withheld { position: 7 }.settled_position(),
            Some(7)
        );
        assert_eq!(
            Outcome::Unreachable { position: 7 }.settled_position(),
            Some(7)
        );

        for assigned in [
            Outcome::Interrupted,
            Outcome::Unasked,
            Outcome::Unroutable,
            Outcome::Undecided,
        ] {
            assert_eq!(assigned.settled_position(), None, "{}", assigned.name());
            assert!(!assigned.is_settled());
        }
    }

    /// A sitting cut short gives every outstanding and unasked target the same
    /// verdict as an exhausted one, and advances the cursor over none.
    #[test]
    fn a_cut_short_sitting_settles_only_what_it_earned() {
        let settlements = Settlements::default();

        settlements.record(Outcome::Answered { position: 0 });
        settlements.record(Outcome::Exhausted { position: 1 });
        for _ in 0..500 {
            settlements.record(Outcome::Interrupted);
            settlements.record(Outcome::Unasked);
        }

        let checkpoint = settlements.checkpoint();
        assert_eq!(checkpoint.watermark, 2);
        assert!(checkpoint.settled_above.is_empty());
        assert_eq!(settlements.settled_count(), 2);
        assert_eq!(settlements.count(Outcome::Interrupted), 500);
    }

    /// Unsettled outcomes cost a counter each, whatever their number, so a scan
    /// that abandons millions of targets pays no memory for them.
    #[test]
    fn unsettled_outcomes_are_counted_rather_than_stored() {
        let settlements = Settlements::default();
        for _ in 0..100_000 {
            settlements.record(Outcome::Unasked);
        }

        assert_eq!(settlements.count(Outcome::Unasked), 100_000);
        assert_eq!(settlements.settled_count(), 0);
        assert_eq!(settlements.checkpoint(), Checkpoint::default());
    }

    /// One unearned position holds the watermark however much settles above it.
    #[test]
    fn one_unearned_position_stalls_the_watermark() {
        let settlements = Settlements::default();

        settlements.record(Outcome::Answered { position: 0 });
        // Position 1 was interrupted: it carries no position, so it is re-probed.
        settlements.record(Outcome::Interrupted);
        for position in 2..1_000 {
            settlements.record(Outcome::Answered { position });
        }

        assert_eq!(settlements.checkpoint().watermark, 1);
        assert_eq!(settlements.settled_count(), 999);
    }

    /// A resumed sitting starts from what the first settled, and counts only its
    /// own work.
    #[test]
    fn resuming_keeps_the_earlier_sittings_progress() {
        let first = Settlements::default();
        for position in 0..10 {
            first.record(Outcome::Answered { position });
        }

        let second = Settlements::resuming(&first.checkpoint());
        assert_eq!(second.settled_count(), 10);
        assert_eq!(second.count(Outcome::Answered { position: 0 }), 0);

        second.record(Outcome::Exhausted { position: 10 });
        assert_eq!(second.checkpoint().watermark, 11);
    }
}