zond-engine 0.12.0

A lightweight, fast, and highly concurrent networking backend for packet crafting, protocol fingerprinting, and host discovery.
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
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
// 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

//! # Assembling and running a whole scan
//!
//! What [`discover`](super::discover) and [`scan`](super::scan) do once they
//! have been called: read what this host can do, turn a plan into running
//! strategies, back the plan's intent with what actually opened, drive the port
//! scan, and wait for the hostname tail.
//!
//! Nothing here is public. It is one implementation of the engine's own policy,
//! and the two entry points above are its only callers. A consumer who wants a
//! different policy does not need to reach in here: they build a
//! [`plan`](super::plan), edit it, and run the steps they want, which is the
//! second of the three altitudes the [`scanner`](super) module documents.
//!
//! ## Why it is a module of its own
//!
//! The two entry points are about ninety lines between them. Everything else a
//! scan needs to be assembled is another five hundred, and read together they
//! obscure the thing a reader opens `scanner.rs` to find. Split out, the facade
//! reads as a facade and the policy reads as policy.
//!
//! ## The one decision worth knowing before reading
//!
//! A plan says what should run; only the attempt discovers what could. Those are
//! separate steps here on purpose, and the seam between them is
//! [`ensure_coverage`], which backs the plan's intent with the sockets that
//! actually opened. A protocol left with no strategy at all is not a degraded
//! scan but a silent one, since nothing would route its targets anywhere.

use std::net::IpAddr;

use tokio::sync::mpsc::{self, UnboundedReceiver, UnboundedSender};
use tokio::task::JoinHandle;

use crate::config::{OsDetection, ProbeTuning, ZondConfig};
use crate::fingerprint::os;
use crate::model::ip::range::IpRange;
use crate::model::{
    ip::set::IpSet,
    port::Protocol,
    target::{Target, TargetMap},
    technique::TcpScanTechnique,
};
use crate::scanner::resolver::HostnameResolver;
use crate::scanner::session::{ScanContext, ScannerKind};
use crate::scanner::strategy::{HostScanner, PortScanner, StrategyError};
use crate::scanner::{pacing, plan, resolver, strategy};
use crate::system::interface;
use crate::system::privilege::is_elevated;
use crate::{error, info, success, warn};

/// The targets an unprivileged sweep can actually walk, refusing the rest.
///
/// The privileged path gets this from [`plan::DiscoveryPlan::build`], which
/// classifies every range against this host's interfaces and refuses the ones no
/// strategy can take. The unprivileged path has no plan: it hands the whole set
/// to `connect`, which probes addresses one at a time and would keep doing so
/// until the process is killed. So the same rule is applied here, and applied to
/// the same constant, because a `/64` that is refused with root and scanned
/// forever without it is the engine giving two different answers about one
/// range.
///
/// Filtered per range rather than all-or-nothing. A set holding a `/64` and
/// three literal addresses is three quarters scannable, and refusing the whole
/// of it would throw away addresses somebody named.
///
/// IPv4 is untouched. Every IPv4 range is finite in a way a person can reason
/// about, and a `/8` is an unreasonable request rather than an impossible one —
/// which is a judgement for whoever is driving the engine, not for the engine.
pub(super) fn walkable(targets: IpSet, ctx: &ScanContext) -> IpSet {
    let refused: Vec<_> = targets
        .v6()
        .iter()
        .filter(|range| !interface::is_enumerable(range))
        .copied()
        .collect();

    if refused.is_empty() {
        return targets;
    }

    let mut kept = IpSet::new();
    for range in targets.v4() {
        kept.push_v4_range(*range);
    }
    for range in targets.v6() {
        if interface::is_enumerable(range) {
            kept.push_v6_range(*range);
        }
    }
    kept.canonicalize();

    for range in &refused {
        let refusal = plan::Refusal::unprivileged_range_not_enumerable(range);
        ctx.record_failure(refusal.scanner, refusal.reason);
    }

    kept
}

/// The environment-derived facts that steer how a scan runs.
///
/// Both entry points face the same two questions: can the process open raw
/// sockets, and should it resolve hostnames. Answering them once, up front,
/// lets [`scan`] and [`discover`] branch on the same facts and keeps the
/// privileged-versus-unprivileged and DNS-on-versus-off policy from drifting
/// between phases.
#[derive(Clone, Copy)]
pub(super) struct ScanCapabilities {
    /// Whether raw-socket scanning is available, meaning the process is root.
    /// When false, every phase falls back to unprivileged TCP connect scanning.
    pub(super) privileged: bool,
    /// Whether hostname resolution is enabled, the inverse of `cfg.no_dns`.
    dns: bool,
}

impl ScanCapabilities {
    /// Reads the runtime capabilities from the environment and config, and
    /// announces the scanning mode they imply once, here, rather than from the
    /// code that later acts on them.
    pub(super) fn resolve(cfg: &ZondConfig) -> Self {
        let privileged = is_elevated();
        if privileged {
            success!("Root privileges detected, raw socket scan enabled");
        } else {
            warn!("Root privileges missing, defaulting to unprivileged TCP scan");
        }
        Self {
            privileged,
            dns: !cfg.no_dns,
        }
    }
}

/// The privileged host-identification phase, shared by [`discover`] and
/// [`scan`].
///
/// It spawns the strategies discovery uses: per-interface [`LocalScanner`]s
/// (ARP and ICMPv6, yielding MAC and RTT), a [`RoutedScanner`] for off-link
/// targets (RTT), and the passive DNS and mDNS [`HostnameResolver`]. All of them
/// write into the shared store. [`discover`] runs this alone, while [`scan`]
/// runs it alongside the port scan. Keeping it in one place lets both surface
/// identical host detail without duplicating the orchestration.
pub(super) struct Enrichment {
    scanners: Vec<(ScannerKind, JoinHandle<Result<(), StrategyError>>)>,
    resolver: Option<JoinHandle<Option<HostnameResolver>>>,
}

impl Enrichment {
    /// Spawns every enrichment strategy for `targets`. They begin running
    /// immediately and concurrently. Call [`Enrichment::finish`] to await them.
    pub(super) async fn spawn(
        plan: plan::DiscoveryPlan,
        ctx: &ScanContext,
        caps: ScanCapabilities,
        tuning: ProbeTuning,
    ) -> Self {
        let (dns_tx, resolver) = if caps.dns {
            let (tx, rx) = mpsc::unbounded_channel();
            (Some(tx), Some(spawn_resolver(rx).await))
        } else {
            info!("DNS resolution skipped by user flag");
            (None, None)
        };

        let scanners = spawn_explorers(plan, ctx, dns_tx, tuning).await;
        Self { scanners, resolver }
    }

    /// Awaits every enrichment strategy, reports any that failed, then folds the
    /// resolver's collected hostnames and extra IPs into the store.
    async fn finish(self, ctx: &ScanContext) {
        for (kind, handle) in self.scanners {
            match handle.await {
                Ok(Ok(())) => {}
                Ok(Err(e)) => ctx.record_failure(kind, e.to_string()),
                Err(e) => ctx.record_failure(kind, format!("panicked: {e}")),
            }
        }

        if let Some(task) = self.resolver
            && let Ok(Some(mut resolver)) = task.await
        {
            resolver.resolve_hosts(ctx);
        }
    }
}

/// Turns a [`DiscoveryPlan`] into running tasks.
///
/// Every refusal the plan carries is recorded before anything is spawned, so the
/// distinction between "nothing is there" and "nobody looked" survives into the
/// report. Then each step is asked for its strategy: a step that cannot open
/// what it needs is recorded and skipped, and the rest of the scan proceeds
/// rather than being abandoned over one bad interface.
///
/// Each surviving strategy gets its own task, tagged with its own
/// [`ScannerKind`], so the caller can wait on all of them and react to failures
/// individually.
pub(super) async fn spawn_explorers(
    plan: plan::DiscoveryPlan,
    ctx: &ScanContext,
    dns_tx: Option<UnboundedSender<IpAddr>>,
    tuning: ProbeTuning,
) -> Vec<(ScannerKind, JoinHandle<Result<(), StrategyError>>)> {
    for refusal in plan.refusals() {
        ctx.record_failure(refusal.scanner, refusal.reason.clone());
    }

    let mut explorers: Vec<Box<dyn HostScanner>> = Vec::new();
    for step in plan.into_steps() {
        let kind = step.kind();
        info!(
            verbosity = 1,
            "Spawning {:?} scanner for {} target(s)",
            kind,
            step.target_count()
        );
        match step.into_scanner(ctx.clone(), dns_tx.clone(), tuning) {
            Ok(scanner) => explorers.push(scanner),
            Err(e) => ctx.record_failure(kind, e.to_string()),
        }
    }

    explorers
        .into_iter()
        .map(|mut explorer| {
            // Read before the strategy moves into its task: once it is running,
            // the only thing left to attribute a failure to is the handle.
            let kind = explorer.kind();
            (
                kind,
                tokio::spawn(async move { explorer.discover_hosts().await }),
            )
        })
        .collect()
}

/// Turns a [`PortScanPlan`](plan::PortScanPlan) into the single strategy
/// [`run_port_scan`] drives.
///
/// Every refusal is recorded first, for the same reason discovery records its
/// own: a protocol nobody probed has to be distinguishable from a protocol with
/// nothing open. A step that cannot open its socket is recorded and dropped, and
/// whatever built is wrapped in a
/// [`CompositePortScanner`](strategy::composite::CompositePortScanner), which
/// routes each target to a strategy that covers its protocol. One scanner comes
/// back either way, so the fork stays confined here.
pub(super) fn build_port_scanner(
    plan: plan::PortScanPlan,
    ctx: &ScanContext,
    target_count: usize,
    tuning: ProbeTuning,
) -> BuiltPortScan {
    for refusal in plan.refusals() {
        ctx.record_failure(refusal.scanner, refusal.reason.clone());
    }

    let technique = plan.technique();
    // Read before the steps are consumed. A protocol the plan never intended to
    // cover has already been refused above, in the same words, and must not be
    // refused a second time by the coverage check below.
    let intended: Vec<Protocol> = [Protocol::Tcp, Protocol::Udp]
        .into_iter()
        .filter(|protocol| plan.covers(*protocol))
        .collect();

    let mut scanners: Vec<Box<dyn PortScanner>> = Vec::new();
    let mut opened = Vec::new();
    for step in plan.into_steps() {
        match step.into_scanner(ctx.clone(), target_count, tuning) {
            Ok(scanner) => {
                opened.push(step);
                scanners.push(scanner);
            }
            Err(e) => ctx.record_failure(step.kind(), e.to_string()),
        }
    }

    BuiltPortScan {
        scanner: Box::new(strategy::composite::CompositePortScanner::new(
            ensure_coverage(scanners, ctx, technique, &intended),
            ctx.clone(),
        )),
        opened,
    }
}

/// Backs the plan's intent with what actually opened: any protocol left without
/// a strategy gets the unprivileged one, or is refused.
///
/// **The plan cannot do this on its own, and that is the point of separating
/// them.** A plan says a raw TCP scanner and a raw UDP scanner should run. Only
/// the attempt discovers that this host permitted one raw socket and not the
/// other — a sandbox can do exactly that — and a protocol left with no strategy
/// at all is not a degraded scan but a silent one:
/// [`CompositePortScanner`](strategy::composite::CompositePortScanner) has
/// nowhere to route those targets, so they are never probed and never reported.
/// Asking what actually built, rather than assuming a privileged scan covers
/// everything, is what keeps that from happening.
///
/// **A connect fallback substitutes for a SYN scan and for nothing else.** It
/// completes handshakes, so it answers roughly the question a SYN scan asks; it
/// cannot send a FIN, a flagless segment or a bare ACK, and so cannot answer
/// what any of those were asked. Where the caller chose one of those and no raw
/// scanner opened, the TCP half is reported as a failure and left undone. That
/// is worse for the caller and honest, where a silent substitution would hand
/// back verdicts from a technique they did not choose - and no field in the
/// report would say so.
///
/// **`intended` is what keeps this from repeating the plan.** A protocol the
/// plan never meant to cover was already refused, in the words
/// [`Refusal::technique_needs_raw_sockets`](plan::Refusal::technique_needs_raw_sockets)
/// supplies, and saying it again puts one cause in the report twice. What is
/// left for this function is the narrower case the plan could not foresee: a
/// protocol it did intend, whose socket would not open.
pub(super) fn ensure_coverage(
    mut scanners: Vec<Box<dyn PortScanner>>,
    ctx: &ScanContext,
    technique: TcpScanTechnique,
    intended: &[Protocol],
) -> Vec<Box<dyn PortScanner>> {
    let covered: Vec<Protocol> = scanners
        .iter()
        .flat_map(|scanner| scanner.supported_protocols())
        .collect();

    let missing = |protocol: Protocol| intended.contains(&protocol) && !covered.contains(&protocol);

    if missing(Protocol::Tcp) {
        if technique.finds_open_ports() {
            scanners.push(Box::new(strategy::connect::ConnectPortScanner::new(
                ctx.clone(),
                pacing::limits::CONNECT_CONCURRENCY,
            )));
        } else {
            let refusal = plan::Refusal::technique_needs_raw_sockets(technique);
            ctx.record_failure(refusal.scanner, refusal.reason);
        }
    }

    if missing(Protocol::Udp) {
        scanners.push(Box::new(strategy::connect::ConnectUdpPortScanner::new(
            ctx.clone(),
            pacing::limits::CONNECT_CONCURRENCY,
        )));
    }

    scanners
}

/// A port-scan strategy, and which of the planned steps actually opened.
///
/// The second half is not decoration. Host enrichment is worth running only
/// alongside a raw scan — it is the raw paths that yield a MAC and an RTT — and
/// whether a raw scan is happening is answerable only after the sockets were
/// asked for, not from the privilege the process holds.
///
/// The steps are kept rather than their [`ScannerKind`]s, because "did this
/// need raw sockets" is the question being asked and a strategy's name is a
/// different fact about it. Answered from the name, this silently stopped
/// enriching every scan whose technique was not a SYN.
pub(super) struct BuiltPortScan {
    pub(super) scanner: Box<dyn PortScanner>,
    opened: Vec<plan::PortScanStep>,
}

impl BuiltPortScan {
    /// Whether any raw-socket strategy is among what opened.
    pub(super) fn opened_raw(&self) -> bool {
        self.opened.iter().any(plan::PortScanStep::is_raw)
    }
}

/// Drives one port-scan strategy to completion. It streams targets through the
/// strategy, and when the strategy succeeds and the scan was not aborted, lets
/// the strategy run its own service-detection pass (a no-op for strategies that
/// fingerprint inline).
///
/// A strategy failure is reported on the event stream, tagged with the
/// strategy's own [`ScannerKind`], and otherwise swallowed so the surrounding
/// scan (host enrichment and DNS) still finishes.
pub(super) async fn run_port_scan(
    mut scanner: Box<dyn PortScanner>,
    rx: mpsc::Receiver<Target>,
    ctx: &ScanContext,
) {
    let kind = scanner.kind();
    match scanner.scan(rx).await {
        Ok(()) => {
            if !ctx.handle.should_stop() {
                scanner.detect_services(ctx).await;
            }
        }
        Err(e) => ctx.record_failure(kind, e.to_string()),
    }
}

/// Completes the hostname-resolution tail of a scan.
///
/// A privileged scan spawns passive DNS and mDNS resolution as part of its
/// [`Enrichment`]; awaiting that here folds the collected hostnames and extra
/// IPs into the store along with the rest of the enrichment strategies. An
/// unprivileged scan has no enrichment, so it falls back to active reverse
/// lookups when DNS is enabled and does nothing when it is not. This is the
/// single place the "passive when privileged, active otherwise" policy lives.
pub(super) async fn finish_enrichment(
    enrichment: Option<Enrichment>,
    caps: ScanCapabilities,
    ctx: &ScanContext,
) {
    match enrichment {
        Some(enrichment) => enrichment.finish(ctx).await,
        None if caps.dns => resolver::resolve_hosts_async(ctx).await,
        None => {}
    }
}

/// Reads an operating system out of what the scan already knows, sending
/// nothing.
///
/// This is [`OsDetection::Passive`] applied to a phase that had no way to apply
/// it. The port scanner reads a stack off the segments it drew and the echo
/// prober reads one off a ping it sent, but host discovery draws neither — so
/// until now a discovery sweep concluded nothing about any host, however much it
/// had learned about it. A machine whose hardware address names its maker and
/// whose hostname is the one its system generated was sitting in the store,
/// unread.
///
/// Runs after enrichment and not before it: [`os::hostname_evidence`] reads a
/// name, and the name arrives on the resolver's tail. Ordering this earlier
/// would consult a store that has not been told the hostnames yet.
///
/// ## What it will and will not conclude
///
/// The two sources it has are each, deliberately, below the floor
/// [`os::resolve`] reports at — so neither names a host alone, and a sweep of a
/// network of randomly-addressed phones concludes nothing at all. Two agreeing
/// sources clear it: an Apple address under a default `MacBook-Pro` name is a
/// verdict, where either alone is a guess. That is the intended yield and it is
/// a small one. It is not a substitute for reading a stack off the wire; it is
/// the part of passive identification that costs nothing and was simply not
/// wired up.
pub(super) fn run_passive_os_identification(ctx: &ScanContext, os_detection: OsDetection) {
    // `Off` means identify nothing and record nothing about the stacks that
    // answered. It costs no packets to disobey that, which is exactly why it
    // has to be obeyed here: a caller who asked for a report containing only
    // what they requested would otherwise find a fingerprint in it.
    if matches!(os_detection, OsDetection::Off) {
        return;
    }

    let mut named = 0usize;
    for ip in ctx.host_addresses() {
        let mut identified = false;
        ctx.write_host(ip, |host| {
            identified = os::identify(host, []);
            identified
        });
        if identified {
            named += 1;
        }
    }

    if named > 0 {
        info!(
            verbosity = 1,
            "Named {named} host(s) from what the sweep already knew"
        );
    }
}

/// Runs the active operating-system echo probe, where the caller asked for it
/// and the passive sources left hosts unnamed.
///
/// Target selection is from the store and not from the plan, deliberately: "the
/// passive sources concluded nothing" is only true once those sources have
/// finished, and the store is where that conclusion lives. Every host that
/// answered nothing a TCP rule could read — a stock Windows firewall drops
/// rather than refuses — is here, and an echo reply is the one packet such a
/// host still gives.
///
/// Declines quietly rather than failing when there is nothing to do: a scan
/// where every host was already named, or where none were, has not lost
/// anything by not pinging.
pub(super) async fn run_active_os_probe(
    ctx: &ScanContext,
    os_detection: crate::config::OsDetection,
    tuning: ProbeTuning,
) {
    if !os_detection.is_active() {
        return;
    }

    // A host worth pinging is one the scan found and could not name. Hosts the
    // scan never recorded were never asked about, and pinging addresses nobody
    // named is a discovery sweep rather than identification.
    let mut unnamed: Vec<IpAddr> = ctx
        .host_addresses()
        .into_iter()
        .filter(|ip| {
            ctx.read_host(ip, |host| {
                host.status().is_up() && host.os().is_none_or(|os| os.accuracy() < 85)
            })
            .unwrap_or(false)
        })
        .collect();
    unnamed.sort_unstable();
    unnamed.dedup();

    if unnamed.is_empty() {
        return;
    }

    info!(
        "Probing {} host(s) the passive sources could not name, by echo",
        unnamed.len()
    );

    match strategy::routed::OsEchoScanner::new(ctx.clone(), unnamed, tuning) {
        Ok(mut scanner) => {
            if let Err(e) = scanner.discover_hosts().await {
                ctx.record_failure(ScannerKind::OsEcho, e.to_string());
            }
        }
        // The raw ICMP socket would not open, most likely for want of
        // privileges. One recorded line, not a per-host failure: every host
        // keeps the answer the passive sources gave it, which is the state the
        // caller was already looking at.
        Err(e) => ctx.record_failure(
            ScannerKind::OsEcho,
            format!("the active echo probe could not open its transport: {e}"),
        ),
    }
}

/// Collects every target address from a [`TargetMap`] into an [`IpSet`], so the
/// host-enrichment phase knows which addresses to identify.
pub(super) fn target_ips(target_map: &TargetMap) -> IpSet {
    let mut ips = IpSet::new();
    for unit in &target_map.units {
        for range in unit.ips().v4() {
            ips.insert_range(IpRange::V4(*range));
        }
        for range in unit.ips().v6() {
            ips.insert_range(IpRange::V6(*range));
        }
    }
    ips.canonicalize();
    ips
}

/// Starts the background hostname resolver as its own task.
///
/// The resolver listens for raw DNS and mDNS traffic and answers reverse lookups
/// for any IP sent down `dns_rx`, independent of and concurrent with whatever
/// scanning strategies are running. When it fails to start, most likely because
/// no usable network socket could be opened, the failure is logged and `None` is
/// returned rather than propagated, since a scan without hostname resolution is
/// still useful.
pub(super) async fn spawn_resolver(
    dns_rx: UnboundedReceiver<IpAddr>,
) -> JoinHandle<Option<HostnameResolver>> {
    tokio::spawn(async move {
        match HostnameResolver::new(dns_rx) {
            Ok(resolver) => {
                success!("Successfully initialized hostname resolver");
                Some(resolver.run().await)
            }
            Err(e) => {
                error!("Resolver failed to start: {e}");
                None
            }
        }
    })
}

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

#[cfg(test)]
mod tests {
    use super::*;
    use crate::scanner::report::ScannerFailure;
    use crate::scanner::session::ScanSession;
    use tokio::sync::mpsc;

    /// A scanner that claims a protocol and does nothing, standing in for a
    /// privileged strategy that was built successfully.
    struct StubScanner(Vec<Protocol>);

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

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

        async fn scan(&mut self, _targets: mpsc::Receiver<Target>) -> Result<(), StrategyError> {
            Ok(())
        }
    }

    /// A plan that meant to cover both protocols, which is every plan except
    /// the one that refused a technique its fallback cannot express.
    const BOTH: &[Protocol] = &[Protocol::Tcp, Protocol::Udp];

    fn ip_set(exprs: &[&str]) -> IpSet {
        crate::model::parse::ip::to_set(exprs, None, None).expect("hand-written targets parse")
    }

    /// The defect this function exists for. A `/64` handed to the unprivileged
    /// path was probed one address at a time until the process was killed, while
    /// the same range with root was refused in the plan before a packet was
    /// sent — one engine giving two answers about one range.
    #[test]
    fn a_range_too_large_to_walk_is_refused_rather_than_started() {
        let (_session, ctx) = ScanSession::new();

        let kept = walkable(ip_set(&["2001:db8::/64"]), &ctx);

        assert!(kept.is_empty(), "nothing here can be walked");

        let failures = ctx.failures_snapshot();
        assert_eq!(failures.len(), 1);
        assert_eq!(failures[0].scanner(), ScannerKind::Connect);
        assert!(
            failures[0].reason().contains("18446744073709551616"),
            "the refusal quotes the size it is refusing: {}",
            failures[0].reason()
        );
    }

    /// Refusing the whole set over one unwalkable range in it would discard
    /// addresses somebody named and could have had.
    #[test]
    fn the_walkable_part_of_a_mixed_set_survives() {
        let (_session, ctx) = ScanSession::new();

        let kept = walkable(
            ip_set(&["2001:db8::/64", "10.0.0.0/30", "2001:db8:1::/126"]),
            &ctx,
        );

        // Four IPv4 addresses and the four in the /126; the /64 is gone.
        assert_eq!(kept.len(), 8);
        assert_eq!(ctx.failures_snapshot().len(), 1);
    }

    /// A set that is entirely walkable is handed back untouched, and — the part
    /// that matters — files no failure. A report claiming a refusal that never
    /// happened marks a complete scan as partial.
    #[test]
    fn a_set_that_can_be_walked_is_left_alone_and_files_nothing() {
        let (_session, ctx) = ScanSession::new();

        let kept = walkable(ip_set(&["10.0.0.0/24", "2001:db8::/120"]), &ctx);

        assert_eq!(kept.len(), 512);
        assert!(ctx.failures_snapshot().is_empty());
    }

    /// IPv4 is deliberately not bounded here. A `/8` is sixteen million probes,
    /// which is unreasonable rather than impossible, and which of those it is is
    /// a judgement for whoever is driving the engine.
    #[test]
    fn a_large_ipv4_range_is_not_this_functions_business() {
        let (_session, ctx) = ScanSession::new();

        let kept = walkable(ip_set(&["10.0.0.0/8"]), &ctx);

        assert_eq!(kept.len(), 1 << 24);
        assert!(ctx.failures_snapshot().is_empty());
    }

    fn covered(scanners: Vec<Box<dyn PortScanner>>) -> Vec<Protocol> {
        let (_session, ctx) = ScanSession::new();
        ensure_coverage(scanners, &ctx, TcpScanTechnique::Syn, BOTH)
            .iter()
            .flat_map(|scanner| scanner.supported_protocols())
            .collect()
    }

    /// The plan refuses what it can foresee and `ensure_coverage` catches what
    /// only the attempt reveals. Both had the same words for the same cause, so
    /// an unprivileged flag-probe scan recorded the identical failure twice:
    /// once from the plan's refusal and once from the coverage check that did
    /// not know the plan had already spoken.
    ///
    /// A consumer counting failures over-reports, and one rendering them shows
    /// the same paragraph to a user twice.
    #[test]
    fn a_refusal_the_plan_already_made_is_not_recorded_again() {
        let cfg = ZondConfig {
            tcp_technique: TcpScanTechnique::Fin,
            ..ZondConfig::default()
        };
        let (_session, ctx) = ScanSession::new();

        let _built = build_port_scanner(
            plan::PortScanPlan::build(&cfg, false),
            &ctx,
            0,
            cfg.probe_tuning(),
        );

        let failures = ctx.take_failures();
        assert_eq!(
            failures.len(),
            1,
            "one cause, one entry: {:?}",
            failures
                .iter()
                .map(ScannerFailure::reason)
                .collect::<Vec<_>>()
        );
        assert_eq!(failures[0].scanner(), ScannerKind::TcpPort);
        assert!(failures[0].reason().contains("fin"));
    }

    /// Host enrichment is keyed on whether a raw scan is happening, and a raw
    /// scan is one whatever segment its probes carry. Read off the strategy's
    /// name instead, a FIN scan stopped counting as raw the moment it stopped
    /// being called `syn_port`, and every non-SYN privileged scan quietly lost
    /// its MAC addresses and round trips.
    #[test]
    fn a_raw_scan_earns_enrichment_whichever_technique_it_carries() {
        for technique in TcpScanTechnique::ALL {
            let built = BuiltPortScan {
                scanner: Box::new(StubScanner(vec![Protocol::Tcp])),
                opened: vec![plan::PortScanStep::RawTcp { technique }],
            };
            assert!(built.opened_raw(), "a raw {technique} scan is still raw");
        }

        let unprivileged = BuiltPortScan {
            scanner: Box::new(StubScanner(vec![Protocol::Tcp])),
            opened: vec![
                plan::PortScanStep::ConnectTcp,
                plan::PortScanStep::ConnectUdp,
            ],
        };
        assert!(
            !unprivileged.opened_raw(),
            "a connect scan has no MAC or round trip to offer"
        );
    }

    /// With no privileged scanner at all, both connect fallbacks stand in.
    #[test]
    fn an_unprivileged_scan_covers_both_protocols() {
        let protocols = covered(Vec::new());
        assert!(protocols.contains(&Protocol::Tcp));
        assert!(protocols.contains(&Protocol::Udp));
    }

    /// The regression guard for the per-protocol fallback: a host that could
    /// build the raw UDP scanner but not the SYN one must still probe TCP.
    /// Gating on "any privileged scanner exists" left those targets with no
    /// route at all, so they were dropped without a record.
    #[test]
    fn a_protocol_without_a_privileged_scanner_still_gets_a_fallback() {
        let protocols = covered(vec![Box::new(StubScanner(vec![Protocol::Udp]))]);
        assert!(
            protocols.contains(&Protocol::Tcp),
            "TCP targets would be silently dropped"
        );
        assert!(protocols.contains(&Protocol::Udp));
    }

    /// A connect scan is a substitute for a SYN scan and for nothing else. Asked
    /// for a technique it cannot express, an unprivileged scan has to leave the
    /// TCP half undone and say so - a silent substitution would hand back
    /// verdicts from a technique nobody chose.
    ///
    /// The case is a plan that *did* intend TCP, whose raw socket then would
    /// not open. A plan that never intended it refused before reaching here;
    /// see `a_refusal_the_plan_already_made_is_not_recorded_again`.
    #[test]
    fn a_technique_the_fallback_cannot_express_is_reported_rather_than_substituted() {
        let (_session, ctx) = ScanSession::new();
        let scanners = ensure_coverage(Vec::new(), &ctx, TcpScanTechnique::Fin, BOTH);
        let protocols: Vec<Protocol> = scanners
            .iter()
            .flat_map(|scanner| scanner.supported_protocols())
            .collect();

        assert!(
            !protocols.contains(&Protocol::Tcp),
            "a connect scan cannot send a FIN and must not pretend to"
        );

        let failures = ctx.take_failures();
        assert_eq!(failures.len(), 1, "the caller has to be told");
        assert_eq!(failures[0].scanner(), ScannerKind::TcpPort);
        assert!(
            failures[0].reason().contains("fin"),
            "the failure has to name the technique: {}",
            failures[0].reason()
        );
    }

    /// And the mirror case: raw TCP available, raw UDP not.
    #[test]
    fn a_privileged_tcp_only_scan_falls_back_for_udp() {
        let protocols = covered(vec![Box::new(StubScanner(vec![Protocol::Tcp]))]);
        assert!(protocols.contains(&Protocol::Tcp));
        assert!(
            protocols.contains(&Protocol::Udp),
            "UDP targets would be silently dropped"
        );
    }

    /// When the privileged scanners already cover everything, no fallback is
    /// added - a connect scanner beside them would re-probe the same ports.
    #[test]
    fn fully_covered_protocols_gain_no_fallback() {
        let (_session, ctx) = ScanSession::new();
        let scanners = ensure_coverage(
            vec![
                Box::new(StubScanner(vec![Protocol::Tcp])),
                Box::new(StubScanner(vec![Protocol::Udp])),
            ],
            &ctx,
            TcpScanTechnique::Syn,
            BOTH,
        );
        // Two scanners in, two scanners out: nothing was added beside them.
        assert_eq!(scanners.len(), 2);
    }

    /// The mirror of the double-record: a plan that never intended TCP gets no
    /// connect fallback for it either, however open-port-finding the technique
    /// would have been. Nothing intended it, so there is nothing to stand in
    /// for.
    #[test]
    fn a_protocol_the_plan_left_out_gains_no_fallback_and_no_second_refusal() {
        let (_session, ctx) = ScanSession::new();
        let scanners = ensure_coverage(Vec::new(), &ctx, TcpScanTechnique::Fin, &[Protocol::Udp]);

        let protocols: Vec<Protocol> = scanners
            .iter()
            .flat_map(|scanner| scanner.supported_protocols())
            .collect();
        assert_eq!(protocols, vec![Protocol::Udp]);
        assert!(
            ctx.take_failures().is_empty(),
            "the plan already said why, in the same words"
        );
    }

    /// The gap this pass exists to close: a sweep that learned a host's hardware
    /// and its name, and concluded nothing from either.
    #[test]
    fn a_discovery_sweep_now_names_what_its_own_findings_imply() {
        let (_session, ctx) = ScanSession::new();
        let ip: IpAddr = "192.0.2.1".parse().expect("a valid address");

        ctx.update_host(ip, |host| {
            host.record_mac("a4:83:e7:00:00:01".parse().expect("an Apple address"));
            host.set_hostname(Some("MacBook-Pro".to_owned()));
        });

        run_passive_os_identification(&ctx, OsDetection::Passive);

        let named = ctx
            .read_host(&ip, |host| host.os().map(ToString::to_string))
            .expect("the host is in the store");
        assert!(
            named.as_deref().is_some_and(|os| os.contains("macOS")),
            "{named:?}"
        );
    }

    /// `Off` means identify nothing. It costs no packets to disobey, which is
    /// exactly why obeying it has to be tested: a caller who asked for a report
    /// containing only what they requested must not find a fingerprint in it.
    #[test]
    fn detection_turned_off_identifies_nothing() {
        let (_session, ctx) = ScanSession::new();
        let ip: IpAddr = "192.0.2.1".parse().expect("a valid address");

        ctx.update_host(ip, |host| {
            host.record_mac("a4:83:e7:00:00:01".parse().expect("an Apple address"));
            host.set_hostname(Some("MacBook-Pro".to_owned()));
        });

        run_passive_os_identification(&ctx, OsDetection::Off);

        let named = ctx
            .read_host(&ip, |host| host.os().is_some())
            .expect("the host is in the store");
        assert!(!named);
    }

    /// The pass runs over every host a sweep found, and most of them have
    /// nothing to go on. That must leave them alone rather than guess.
    #[test]
    fn a_host_with_nothing_to_go_on_is_left_as_it_was() {
        let (_session, ctx) = ScanSession::new();
        let ip: IpAddr = "192.0.2.2".parse().expect("a valid address");

        ctx.update_host(ip, |host| {
            host.record_mac(
                "02:00:5e:00:53:04"
                    .parse()
                    .expect("a locally administered address"),
            );
        });

        run_passive_os_identification(&ctx, OsDetection::Passive);

        let named = ctx
            .read_host(&ip, |host| host.os().is_some())
            .expect("the host is in the store");
        assert!(!named);
    }
}