zond-engine 0.14.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
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
// 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

//! # Composite Port Scanner
//!
//! A port scanner that multiplexes targets across several underlying scanners.
//!
//! Rather than forcing consumers of the scanning subsystem to juggle multiple
//! scanner instances for different protocols (e.g., TCP SYN vs. raw UDP vs.
//! connect fallbacks), the [`CompositePortScanner`] acts as a single router.
//! It accepts a unified stream of targets, consults each internal scanner's
//! [`PortScanner::supported_protocols`] capability, and routes the target to the
//! correct protocol-specific engine.
//!
//! This design allows the engine to handle targets across different protocols
//! concurrently without modifying the `PortScanner` consumer interface, and
//! is what let SCTP arrive as one more scanner rather than as a branch at every
//! call site.

use async_trait::async_trait;
use tokio::sync::mpsc;

use crate::journal::settle::Outcome;
use crate::model::port::Protocol;
use crate::model::target::PlannedTarget;
use crate::report::ScannerKind;
use crate::scanner::session::ScanContext;
use crate::scanner::strategy::{PortScanner, StrategyError};
use crate::{counted, info};

/// How many targets one route holds while its scanner is busy.
///
/// A buffer per protocol rather than a shared one, so a slow scanner cannot
/// stall the router for the others. Deep enough to absorb a dispatcher batch
/// arriving while a scanner is mid-send, and shallow enough that the memory is
/// a function of the protocol count rather than of the plan.
const ROUTE_DEPTH: usize = 1024;

/// A port scanner that multiplexes targets by protocol.
pub struct CompositePortScanner {
    scanners: Vec<Box<dyn PortScanner>>,
    /// Where targets that never reached a scanner are reported.
    ///
    /// The router is the one place in a scan that can drop work without any
    /// strategy noticing, so it is the one place that has to be able to say so
    /// through the same channel every other narrowing uses.
    ctx: ScanContext,
}

impl CompositePortScanner {
    /// Constructs a composite scanner from a collection of existing scanners.
    pub fn new(scanners: Vec<Box<dyn PortScanner>>, ctx: ScanContext) -> Self {
        Self { scanners, ctx }
    }
}

#[async_trait]
impl PortScanner for CompositePortScanner {
    fn kind(&self) -> ScannerKind {
        ScannerKind::Composite
    }

    fn supported_protocols(&self) -> Vec<Protocol> {
        let mut protocols = Vec::new();
        for scanner in &self.scanners {
            for proto in scanner.supported_protocols() {
                if !protocols.contains(&proto) {
                    protocols.push(proto);
                }
            }
        }
        protocols
    }

    async fn scan(
        &mut self,
        mut targets: mpsc::Receiver<PlannedTarget>,
    ) -> Result<(), StrategyError> {
        struct Route {
            supported_protocols: Vec<Protocol>,
            tx: mpsc::Sender<PlannedTarget>,
        }

        let mut routes = Vec::new();
        let mut handles = Vec::new();

        // Spin up an independent task for every scanner we own.
        for mut scanner in self.scanners.drain(..) {
            let (tx, rx) = mpsc::channel(ROUTE_DEPTH);
            let supported_protocols = scanner.supported_protocols();
            let kind = scanner.kind();

            let handle = tokio::spawn(async move {
                let res = scanner.scan(rx).await;
                (scanner, res)
            });

            handles.push((kind, handle));
            routes.push(Route {
                supported_protocols,
                tx,
            });
        }

        // Route targets from the unified stream to the first scanner that
        // claims support. A target that finds no route, or whose scanner has
        // already stopped listening, is counted rather than dropped in silence:
        // either means ports the caller asked about are missing from the
        // results, and a scan that quietly answers a narrower question than it
        // was asked is worse than one that says so.
        let mut unroutable = 0usize;
        let mut undeliverable = 0usize;

        while let Some(target) = targets.recv().await {
            match routes
                .iter()
                .find(|route| route.supported_protocols.contains(&target.protocol()))
            {
                Some(route) => {
                    if route.tx.send(target).await.is_err() {
                        undeliverable += 1;
                        self.ctx.record_outcome(Outcome::Unroutable);
                    }
                }
                None => {
                    unroutable += 1;
                    self.ctx.record_outcome(Outcome::Unroutable);
                }
            }
        }

        // Recorded as a failure rather than logged. Both counts mean ports the
        // caller asked about are absent from the results, and every other
        // narrowing in the engine reaches the report and the event stream; a
        // warning reaches neither, so a consumer that awaits the scan and reads
        // what came back cannot tell a narrowed scan from an empty network.
        //
        // One entry carrying both counts, because they have one remedy between
        // them and a report listing them separately would suggest otherwise.
        //
        // **Except after a stop, where undeliverable targets are what stopping
        // means.** A scanner that has been told to finish stops reading, and
        // whatever the router still held could not be handed over. Reporting
        // that as a strategy failure tells somebody who pressed `^C` that
        // something went wrong, when what went wrong is what they asked for. The
        // targets are still not covered and still reach the report as such:
        // they simply did not fail.
        let stopped = self.ctx.handle.should_stop();
        let reportable = if stopped {
            unroutable
        } else {
            unroutable + undeliverable
        };

        if reportable > 0 {
            self.ctx
                .record_failure(ScannerKind::Composite, missed(unroutable, undeliverable));
        } else if undeliverable > 0 {
            info!(
                verbosity = 1,
                "{} were still queued when the scan was stopped",
                counted(undeliverable as u128, "target", "targets")
            );
        }

        // Drop the sender ends to signal EOF to the underlying scanners.
        drop(routes);

        // Wait for all scanners to finish and restore them so they can be
        // interrogated for service detection.
        //
        // Every handle is awaited before any failure is returned. Bailing on
        // the first one would leave the remaining scanners unrestored, so the
        // service-detection pass would skip strategies that ran perfectly well,
        // and their tasks would be left running against a store the scan has
        // already moved on from.
        let mut failure: Option<StrategyError> = None;

        for (kind, handle) in handles {
            match handle.await {
                Ok((scanner, res)) => {
                    self.scanners.push(scanner);
                    if let Err(e) = res {
                        failure.get_or_insert(e);
                    }
                }
                // The composite never aborts its tasks, so a `JoinError` only
                // ever means the scanner panicked - a bug, and one that would
                // otherwise vanish along with the scanner it took down.
                Err(e) => {
                    failure.get_or_insert_with(|| StrategyError::Panicked {
                        scanner: kind,
                        detail: e.to_string(),
                    });
                }
            }
        }

        match failure {
            Some(e) => Err(e),
            None => Ok(()),
        }
    }

    async fn detect_services(&mut self, ctx: &ScanContext) {
        for scanner in &mut self.scanners {
            scanner.detect_services(ctx).await;
        }
    }
}

/// How a router reports the work it could not place.
///
/// Two ways a target goes unprobed, kept apart in the message because they call
/// for different fixes. Nothing claiming the protocol is a scan assembled
/// without a strategy for it; a scanner that had already finished is one that
/// stopped early, most often because its own transport died mid-run.
fn missed(unroutable: usize, undeliverable: usize) -> String {
    let mut reasons = Vec::new();
    if unroutable > 0 {
        reasons.push(format!("{unroutable} had no scanner for their protocol"));
    }
    if undeliverable > 0 {
        reasons.push(format!(
            "{undeliverable} arrived after their scanner had finished"
        ));
    }

    format!(
        "{} never probed and missing from the results: {}",
        counted(
            (unroutable + undeliverable) as u128,
            "target was",
            "targets were"
        ),
        reasons.join(", ")
    )
}

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

#[cfg(test)]
mod tests {
    use super::*;
    use crate::model::target::Target;
    use crate::scanner::session::ScanSession;
    use std::net::{IpAddr, Ipv4Addr};
    use std::sync::{Arc, Mutex};

    /// How a [`MockPortScanner`] behaves once it starts scanning.
    enum Behaviour {
        /// Drain the target stream, recording everything that arrives.
        Collect,
        /// Fail immediately, as a scanner whose transport died would.
        Fail(&'static str),
        /// Panic immediately, as a scanner with a bug in it would.
        Panic,
    }

    struct MockPortScanner {
        supported: Vec<Protocol>,
        received: Arc<Mutex<Vec<Target>>>,
        behaviour: Behaviour,
    }

    impl MockPortScanner {
        fn new(supported: Vec<Protocol>) -> (Self, Arc<Mutex<Vec<Target>>>) {
            Self::with_behaviour(supported, Behaviour::Collect)
        }

        fn with_behaviour(
            supported: Vec<Protocol>,
            behaviour: Behaviour,
        ) -> (Self, Arc<Mutex<Vec<Target>>>) {
            let received = Arc::new(Mutex::new(Vec::new()));
            (
                Self {
                    supported,
                    received: received.clone(),
                    behaviour,
                },
                received,
            )
        }
    }

    #[async_trait]
    impl PortScanner for MockPortScanner {
        fn kind(&self) -> ScannerKind {
            ScannerKind::Composite
        }

        fn supported_protocols(&self) -> Vec<Protocol> {
            self.supported.clone()
        }

        async fn scan(
            &mut self,
            mut targets: mpsc::Receiver<PlannedTarget>,
        ) -> Result<(), StrategyError> {
            match self.behaviour {
                Behaviour::Fail(reason) => return Err(StrategyError::Probe(reason.into())),
                Behaviour::Panic => panic!("scanner bug"),
                Behaviour::Collect => {}
            }

            while let Some(t) = targets.recv().await {
                self.received.lock().unwrap().push(t.target);
            }
            Ok(())
        }
    }

    fn target(protocol: Protocol, port: u16) -> Target {
        Target {
            ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
            port,
            protocol,
        }
    }

    /// Feeds `targets` through a composite over `scanners` and returns what the
    /// run reported.
    async fn run(
        scanners: Vec<Box<dyn PortScanner>>,
        targets: Vec<Target>,
    ) -> Result<(), StrategyError> {
        let (_session, ctx) = ScanSession::new();
        let mut composite = CompositePortScanner::new(scanners, ctx);
        let (tx, rx) = mpsc::channel(16);
        for (position, t) in targets.into_iter().enumerate() {
            tx.send(PlannedTarget::new(position as u64, t))
                .await
                .unwrap();
        }
        drop(tx);
        composite.scan(rx).await
    }

    #[tokio::test]
    async fn composite_routes_by_protocol() {
        let (tcp_scanner, tcp_rx) = MockPortScanner::new(vec![Protocol::Tcp]);
        let (udp_scanner, udp_rx) = MockPortScanner::new(vec![Protocol::Udp]);

        let (_session, ctx) = ScanSession::new();
        let mut composite =
            CompositePortScanner::new(vec![Box::new(tcp_scanner), Box::new(udp_scanner)], ctx);

        let (tx, rx) = mpsc::channel(10);

        let target_tcp = Target {
            ip: IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)),
            port: 80,
            protocol: Protocol::Tcp,
        };

        let target_udp = Target {
            ip: IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)),
            port: 53,
            protocol: Protocol::Udp,
        };

        // Send targets
        tx.send(PlannedTarget::new(0, target_tcp)).await.unwrap();
        tx.send(PlannedTarget::new(1, target_udp)).await.unwrap();
        drop(tx); // Signal EOF

        // Run scanner
        composite.scan(rx).await.unwrap();

        // Verify routing
        let tcp_received = tcp_rx.lock().unwrap();
        assert_eq!(tcp_received.len(), 1);
        assert_eq!(tcp_received[0].protocol, Protocol::Tcp);

        let udp_received = udp_rx.lock().unwrap();
        assert_eq!(udp_received.len(), 1);
        assert_eq!(udp_received[0].protocol, Protocol::Udp);
    }

    /// A scanner that fails must not take its siblings' results with it: every
    /// scanner is restored for the service-detection pass regardless.
    #[tokio::test]
    async fn a_failing_scanner_is_reported_without_losing_the_others() {
        let (failing, _) =
            MockPortScanner::with_behaviour(vec![Protocol::Tcp], Behaviour::Fail("transport died"));
        let (working, udp_rx) = MockPortScanner::new(vec![Protocol::Udp]);
        let (_session, ctx) = ScanSession::new();
        let mut composite =
            CompositePortScanner::new(vec![Box::new(failing), Box::new(working)], ctx);

        let (tx, rx) = mpsc::channel(16);
        tx.send(PlannedTarget::new(0, target(Protocol::Udp, 53)))
            .await
            .unwrap();
        drop(tx);

        let err = composite.scan(rx).await.expect_err("the failure surfaces");

        assert!(err.to_string().contains("transport died"));
        assert_eq!(udp_rx.lock().unwrap().len(), 1, "sibling still ran");
        assert_eq!(composite.scanners.len(), 2, "both scanners restored");
    }

    /// A panicking scanner used to vanish along with its task, leaving the run
    /// looking clean. It has to surface as a failure like any other.
    #[tokio::test]
    async fn a_panicking_scanner_surfaces_as_a_failure() {
        let (panicking, _) = MockPortScanner::with_behaviour(vec![Protocol::Tcp], Behaviour::Panic);
        let (working, udp_rx) = MockPortScanner::new(vec![Protocol::Udp]);

        let err = run(
            vec![Box::new(panicking), Box::new(working)],
            vec![target(Protocol::Udp, 53)],
        )
        .await
        .expect_err("a panic is a failure");

        assert!(err.to_string().contains("panicked"), "got: {err}");
        assert_eq!(udp_rx.lock().unwrap().len(), 1, "sibling still ran");
    }

    /// Targets nothing claims are counted rather than silently discarded - a
    /// scan that answers a narrower question than it was asked has to say so.
    #[tokio::test]
    async fn targets_with_no_route_do_not_stop_the_run() {
        let (tcp_scanner, tcp_rx) = MockPortScanner::new(vec![Protocol::Tcp]);

        run(
            vec![Box::new(tcp_scanner)],
            vec![target(Protocol::Tcp, 80), target(Protocol::Udp, 53)],
        )
        .await
        .expect("unroutable targets are not a failure");

        let received = tcp_rx.lock().unwrap();
        assert_eq!(received.len(), 1);
        assert_eq!(received[0].protocol, Protocol::Tcp);
    }

    /// Saying so has to mean saying so where a consumer will see it. Ports the
    /// caller asked about went unprobed, and a warning on the log is the one
    /// channel a library consumer never receives: they await the scan and read
    /// the report, where a scan that quietly covered less than it was asked
    /// looks exactly like one that found nothing there.
    #[tokio::test]
    async fn targets_that_went_unprobed_reach_the_report() {
        let (_session, ctx) = ScanSession::new();
        let (tcp_scanner, _) = MockPortScanner::new(vec![Protocol::Tcp]);

        let mut composite = CompositePortScanner::new(vec![Box::new(tcp_scanner)], ctx.clone());
        let (tx, rx) = mpsc::channel(16);
        for (position, t) in [target(Protocol::Udp, 53), target(Protocol::Udp, 161)]
            .into_iter()
            .enumerate()
        {
            tx.send(PlannedTarget::new(position as u64, t))
                .await
                .unwrap();
        }
        drop(tx);
        composite
            .scan(rx)
            .await
            .expect("not a failure, a narrowing");

        let failures = ctx.take_failures();
        assert_eq!(failures.len(), 1, "one cause, one entry");
        assert_eq!(failures[0].scanner(), ScannerKind::Composite);
        assert!(
            failures[0].reason().contains('2'),
            "the count is what says how much was missed: {}",
            failures[0].reason()
        );
    }

    /// And nothing to report when nothing was missed, or every clean scan ends
    /// with a failure describing zero targets.
    #[tokio::test]
    async fn a_scan_that_probed_everything_reports_no_narrowing() {
        let (_session, ctx) = ScanSession::new();
        let (tcp_scanner, _) = MockPortScanner::new(vec![Protocol::Tcp]);

        let mut composite = CompositePortScanner::new(vec![Box::new(tcp_scanner)], ctx.clone());
        let (tx, rx) = mpsc::channel(16);
        tx.send(PlannedTarget::new(0, target(Protocol::Tcp, 80)))
            .await
            .unwrap();
        drop(tx);
        composite.scan(rx).await.unwrap();

        assert!(ctx.take_failures().is_empty());
    }

    /// Stopping a scan is not a strategy failing.
    ///
    /// A scanner told to finish stops reading, so whatever the router still held
    /// cannot be handed over. Reporting that as a failure tells somebody who
    /// pressed `^C` that something went wrong, when what went wrong is what they
    /// asked for. The targets are still uncovered, and still unsettled, so a
    /// resume asks about them again.
    #[tokio::test]
    async fn a_stopped_scan_does_not_report_a_failure() {
        let (session, ctx) = ScanSession::new();
        let (scanner, _received) = MockPortScanner::new(vec![Protocol::Tcp]);
        let mut composite = CompositePortScanner::new(vec![Box::new(scanner)], ctx.clone());

        // Stopped before anything is routed, so every target is undeliverable.
        session.handle().abort();

        let (tx, rx) = mpsc::channel(16);
        for (position, port) in [80u16, 443].into_iter().enumerate() {
            tx.send(PlannedTarget::new(
                position as u64,
                target(Protocol::Tcp, port),
            ))
            .await
            .unwrap();
        }
        drop(tx);
        composite.scan(rx).await.expect("a stop is not an error");

        assert!(
            ctx.take_failures().is_empty(),
            "a stop was reported as a strategy failure"
        );
        assert_eq!(
            ctx.settlements().settled_count(),
            0,
            "and nothing it could not hand over may be settled"
        );
    }
}