zond-engine 0.16.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
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
// 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 std::net::IpAddr;
use std::sync::Arc;

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

use crate::journal::settle::Outcome;
use crate::model::ip::set::IpSet;
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;

/// Which addresses a scanner in a composite is handed.
///
/// Every scanner takes every address unless a scan says otherwise, and one says
/// otherwise only when its raw strategies send frames alone: a frame reaches
/// what has Ethernet in front of it, and the rest of the targets go to a connect
/// scanner beside it. See
/// [`beyond_frames`](crate::system::interface::beyond_frames).
#[derive(Debug, Clone, Default)]
pub(crate) enum Reach {
    /// Every address.
    #[default]
    Any,
    /// Only these.
    Only(Arc<IpSet>),
    /// Every address but these.
    Except(Arc<IpSet>),
}

impl Reach {
    /// Whether a scanner with this reach is handed `address`.
    fn admits(&self, address: &IpAddr) -> bool {
        match self {
            Self::Any => true,
            Self::Only(set) => set.contains(address),
            Self::Except(set) => !set.contains(address),
        }
    }
}

/// A port scanner that multiplexes targets by protocol.
pub struct CompositePortScanner {
    /// Each scanner with the addresses it is handed. Every one is [`Reach::Any`]
    /// unless the composite was built by
    /// [`with_reach`](Self::with_reach).
    scanners: Vec<(Box<dyn PortScanner>, Reach)>,
    /// Each protocol the scan refused to probe, with the addresses the refusal
    /// covers. Empty unless the composite was built with
    /// [`refusing`](Self::refusing).
    refused: Vec<(Protocol, Reach)>,
    /// 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::with_reach(
            scanners
                .into_iter()
                .map(|scanner| (scanner, Reach::Any))
                .collect(),
            ctx,
        )
    }

    /// Constructs a composite that routes by address as well as by protocol: a
    /// target goes to the first scanner that claims its protocol and whose
    /// [`Reach`] admits its address.
    pub(crate) fn with_reach(
        scanners: Vec<(Box<dyn PortScanner>, Reach)>,
        ctx: ScanContext,
    ) -> Self {
        Self {
            scanners,
            refused: Vec::new(),
            ctx,
        }
    }

    /// The same composite, told which targets the scan refused to probe: each
    /// protocol a refusal names, with the addresses it covers.
    ///
    /// A target the router can place nowhere is one of two things, and only
    /// the scan that assembled the router knows which. Either something decided
    /// not to probe it and a refusal in the report already says so, or nothing
    /// did and the scan has lost it. Both leave the target unprobed and owed to
    /// a resume. Only the second is a fault: the first reported as one reads as
    /// a defect in the engine, and tells one decision twice.
    pub(crate) fn refusing(mut self, refused: Vec<(Protocol, Reach)>) -> Self {
        self.refused = refused;
        self
    }
}

#[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>,
            reach: Reach,
            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, reach) 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, reach.clone(), handle));
            routes.push(Route {
                supported_protocols,
                reach,
                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. A target the scan refused
        // is left unprobed as well, and its refusal is what says so.
        let mut unroutable = 0usize;
        let mut undeliverable = 0usize;

        while let Some(target) = targets.recv().await {
            let (protocol, ip) = (target.protocol(), target.target.ip);
            match routes.iter().find(|route| {
                route.supported_protocols.contains(&protocol) && route.reach.admits(&ip)
            }) {
                Some(route) => {
                    if route.tx.send(target).await.is_err() {
                        undeliverable += 1;
                        self.ctx.record_outcome(Outcome::Unroutable);
                    }
                }
                None => {
                    if !self
                        .refused
                        .iter()
                        .any(|(refused, reach)| *refused == protocol && reach.admits(&ip))
                    {
                        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, reach, handle) in handles {
            match handle.await {
                Ok((scanner, res)) => {
                    self.scanners.push((scanner, reach));
                    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 scan whose raw strategies send frames alone splits one protocol by
    /// address: the raw scanner takes what a frame reaches and a connect
    /// scanner the rest. Routed by protocol alone, every target would go to the
    /// raw one, and loopback would come back unasked.
    #[tokio::test]
    async fn targets_are_routed_by_address_where_a_scanner_says_so() {
        let (raw, raw_rx) = MockPortScanner::new(vec![Protocol::Tcp]);
        let (connect, connect_rx) = MockPortScanner::new(vec![Protocol::Tcp]);

        let loopback = IpAddr::V4(Ipv4Addr::LOCALHOST);
        let neighbour = IpAddr::V4(Ipv4Addr::new(192, 0, 2, 8));
        let mut beyond = IpSet::new();
        beyond.insert(loopback);
        let beyond = Arc::new(beyond);

        let (_session, ctx) = ScanSession::new();
        let mut composite = CompositePortScanner::with_reach(
            vec![
                (Box::new(raw), Reach::Except(Arc::clone(&beyond))),
                (Box::new(connect), Reach::Only(beyond)),
            ],
            ctx.clone(),
        );

        let (tx, rx) = mpsc::channel(4);
        for (position, ip) in [loopback, neighbour].into_iter().enumerate() {
            let target = Target {
                ip,
                port: 22,
                protocol: Protocol::Tcp,
            };
            tx.send(PlannedTarget::new(position as u64, target))
                .await
                .unwrap();
        }
        drop(tx);
        composite.scan(rx).await.unwrap();

        let ips = |received: &Arc<Mutex<Vec<Target>>>| {
            received
                .lock()
                .unwrap()
                .iter()
                .map(|target| target.ip)
                .collect::<Vec<_>>()
        };
        assert_eq!(ips(&raw_rx), vec![neighbour]);
        assert_eq!(ips(&connect_rx), vec![loopback]);
        assert!(
            ctx.failures_snapshot().is_empty(),
            "every target found a route"
        );
    }

    /// 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 would otherwise 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()
        );
    }

    /// A target the scan refused is left to the refusal that already names it,
    /// and only there: the same protocol at an address the refusal does not
    /// cover is still work the scan lost. Both stay unprobed and owed, so a
    /// resume with the sockets the refusal wanted asks about them again.
    #[tokio::test]
    async fn a_refused_target_is_left_to_its_refusal_and_no_other_is() {
        let (_session, ctx) = ScanSession::new();
        let mut loopback = IpSet::new();
        loopback.insert(IpAddr::V4(Ipv4Addr::LOCALHOST));

        let mut composite = CompositePortScanner::new(Vec::new(), ctx.clone())
            .refusing(vec![(Protocol::Tcp, Reach::Only(Arc::new(loopback)))]);
        let (tx, rx) = mpsc::channel(16);
        let elsewhere = Target {
            ip: "192.0.2.8".parse().expect("literal"),
            ..target(Protocol::Tcp, 80)
        };
        for (position, t) in [target(Protocol::Tcp, 80), elsewhere]
            .into_iter()
            .enumerate()
        {
            tx.send(PlannedTarget::new(position as u64, t))
                .await
                .unwrap();
        }
        drop(tx);
        composite.scan(rx).await.expect("a narrowing, not an error");

        let failures = ctx.take_failures();
        assert_eq!(failures.len(), 1, "{failures:?}");
        assert!(
            failures[0]
                .reason()
                .starts_with("1 target was never probed"),
            "only the target the refusal does not cover is lost: {}",
            failures[0].reason()
        );
        assert_eq!(ctx.settlements().count(Outcome::Unroutable), 2);
    }

    /// 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"
        );
    }
}