zond-engine 0.15.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
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
// Copyright (c) 2026 Erik Lening (hollowpointer) and Contributors
//
// This file is part of Zond Engine, licensed under the GNU Affero General
// Public License, version 3 or later. See the LICENSE file for details, or
// <https://www.gnu.org/licenses/agpl-3.0.html>.
//
// SPDX-License-Identifier: AGPL-3.0-or-later

//! # What every raw strategy is built from
//!
//! The layer under the strategies that open a raw socket: how a probe reaches
//! the wire, what identifies one attempt, and the timing profiles a probe over
//! a routed path is held to. Nothing here scans anything. It is what
//! [`routed`](super::routed), [`ports`](super::ports),
//! [`identify`](super::identify) and [`topology`](super::topology) have in
//! common, gathered so that none of them has to reach into another.
//!
//! ## Why it is a module rather than part of a scanner
//!
//! It used to live in `routed`, beside the SYN sweep, because the sweep was the
//! first thing to need it. Everything raw that arrived afterwards, four port
//! scanners and two operating-system probes and a trace and a filter probe, was
//! then written as a submodule of the sweep, which is not what any of them is. The
//! contents did not change; what changed is that `routed` no longer means both
//! "reached through a gateway" and "opens a raw socket".
//!
//! ## What is shared and what is not
//!
//! The timings here are the ones a probe over a routed path shares whatever it
//! is asking about: a SYN sweep and a TCP port scan cross the same links and
//! wait on the same round trips. What each scan does with them is its own.
//! [`ports`](super::ports) holds the profiles that belong to a port scan, and
//! the UDP scanner keeps its own outright, because an ICMP rate limiter is not
//! a property of the path.

use std::net::IpAddr;
use std::num::NonZeroU32;
use std::time::Duration;

use crate::evasion::SegmentShaping;
use crate::logging::error;
use crate::model::technique::TcpScanTechnique;
use crate::protocols as protocol;
use crate::scanner::pacing::deadline::AdaptiveDeadlineConfig;
use crate::scanner::pacing::retry::{RetryPolicy, SilentHostPolicy};
use crate::scanner::pacing::timer::ScanBudget;
use crate::scanner::payload;
use crate::transport::probe::{Emission, ProbeSender, SendError};
use crate::{info, success};

/// How long a routed sweep or port scan runs and how it adapts.
///
/// Routed targets sit anywhere on the internet rather than on one segment, so a
/// single scan spans a wide range of round trips and the extremes matter more
/// than the average. Two of these values carry most of that weight:
///
/// - **Silence floor.** The silence tolerance is derived from observed round
///   trips, which the fastest responders dominate - they answer first and pull
///   the estimate toward their own latency, which would end the scan while
///   slower targets are still legitimately in flight. The floor is what bounds
///   that, so it is set against the tail of the round-trip distribution rather
///   than its middle.
/// - **Hard budget.** The base gives a distant target room for several round
///   trips; the per-target term covers the send burst and the spread of
///   arrivals behind it. The ceiling bounds a scan whose pace nobody derived:
///   it is *not* what bounds the port scanners, which tell it their size and
///   their pacing floor and so cannot be clamped by it. It used to be, and it
///   truncated a 65 535-port scan at 60 seconds of the 104 it had earned.
///
/// The minimum runtime exists so silence is never the reason a scan stops
/// before an answer could plausibly have arrived at all.
///
/// A generous budget costs nothing when a scan succeeds, since both loops exit
/// as soon as every target is resolved ([`RoutedScanner`] once all targets have
/// responded, [`TcpPortScanner`] once nothing is pending). It is spent only
/// when something is still missing.
pub(super) const DEADLINE_CONFIG: AdaptiveDeadlineConfig = AdaptiveDeadlineConfig::new(
    ScanBudget::new(
        Duration::from_millis(2_000),
        Duration::from_millis(1),
        Duration::from_secs(60),
    ),
    ScanBudget::new(
        Duration::from_millis(300),
        Duration::from_micros(500),
        Duration::from_secs(10),
    ),
    Duration::from_millis(400),
    Duration::from_secs(3),
    4.0,
    20,
);

/// How a SYN probe is retransmitted, shared by both scanners here for the same
/// reason they share a deadline profile: it is the same probe over the same kind
/// of path.
///
/// Three attempts is what a paced sweep needs and what an unpaced one cannot be
/// rescued by. Two is the least that distinguishes a lost packet from a silent
/// one, and the third still earns its place: on a large range it is the
/// attempt that recovers the last few percent.
///
/// The budget is bounded here rather than raised because the loss it would be
/// compensating for is not the kind repetition fixes. Sending faster than a path
/// absorbs costs coverage on every attempt alike, so a scan that answers it with
/// more attempts pays the full budget on every dead address to buy back what
/// [`PROBE_RATE_PER_SEC`] gives away for nothing. On a range with nothing on it,
/// which is the ordinary case, each attempt is the whole range's worth of
/// packets and recovers no host at all.
///
/// The floor sits far below the starting timeout, and the gap between them is
/// the point. Before anything has been measured the network is unknown rather
/// than known to be fast, so 200 ms of patience is cheap insurance against
/// tripling the traffic of a scan that crosses an ocean. Once a target has
/// answered, its own round trip governs, and on a local path that collapses
/// toward the floor - so silence is settled in a fraction of a second where a
/// fixed timeout would have spent the whole budget waiting.
pub(super) const RETRY_POLICY: RetryPolicy = RetryPolicy::new(
    3,
    Duration::from_millis(200),
    Duration::from_millis(25),
    Duration::from_secs(2),
    2.0,
    0.2,
    Some(SilentHostPolicy::new(32, 2)),
);

/// The shortest interval the send ticker is asked to keep.
///
/// A tokio interval cannot be relied on much below a millisecond, so a rate
/// faster than one probe per tick is expressed by releasing several per tick
/// rather than by ticking faster. Below that the tick lengthens instead - see
/// [`pacing_for`], where getting this wrong is silent.
pub(super) const MIN_SEND_TICK: Duration = Duration::from_millis(1);

/// The rate a scan runs at, given the bounds the caller asked for.
///
/// A configured zero is a caller error rather than an instruction to stall, and
/// falls back to the engine's own rate the same way an unset one does. Pacing at
/// one probe a second would honour the number and not the intent.
///
/// `floor` lifts a scanner's own default, which is the case it exists for: a
/// plan large enough that the scan's budget runs out before its targets do. It
/// does not lift a `ceiling` the caller set. Those two are a throughput wish and
/// a safety limit, and a floor that overrode the limit would push a target the
/// operator had already said must not be pushed.
///
/// What the answer *means* is the strategy's own, and the four that ask differ:
/// a sweep and a UDP scan are paced by this number, while a TCP scan reads it as
/// a ceiling and paces itself on
/// [`CongestionWindow`](crate::scanner::pacing::congestion::CongestionWindow).
/// A floor therefore raises a pace in one place and a ceiling in another, and
/// overrides the window in neither.
pub(super) fn rate_within(
    ceiling: Option<NonZeroU32>,
    floor: Option<NonZeroU32>,
    default: NonZeroU32,
) -> NonZeroU32 {
    let rate = ceiling.unwrap_or(default);
    let lifted = match floor {
        Some(floor) => rate.max(floor),
        None => rate,
    };
    match ceiling {
        Some(ceiling) => lifted.min(ceiling),
        None => lifted,
    }
}

/// How often to wake and how many probes to release each time, for a sweep
/// paced at `rate_per_sec`.
///
/// The batch is chosen first and the interval derived from it, so the product
/// is the rate that was asked for rather than something near it. Fixing the
/// interval and rounding the batch instead is the obvious way to write this and
/// it is wrong in a way nothing reports: a batch cannot be less than one probe,
/// so every rate below one probe per tick collapses to the same value and a
/// sweep configured for 500 probes a second quietly runs at 1000.
pub(super) fn pacing_for(rate_per_sec: NonZeroU32) -> (Duration, usize) {
    let rate = f64::from(rate_per_sec.get());
    let batch = (rate * MIN_SEND_TICK.as_secs_f64()).round().max(1.0);

    (Duration::from_secs_f64(batch / rate), batch as usize)
}

/// A TCP sequence number, which is what a SYN attempt is recognised by when
/// its answer echoes it back. See [`SynToken`].
pub(super) type SeqNum = u32;

/// What identifies one SYN attempt on the wire.
///
/// Both halves earn their place. The sequence number comes back in the reply's
/// acknowledgement, and the source port is where the reply is addressed, so
/// together they establish that a segment answers *this probe* rather than
/// merely that it came from the right port on the right host.
///
/// A fresh pair per attempt is also what makes a retried probe measurable. TCP
/// itself must discard round-trip samples from retransmissions because it
/// cannot tell which transmission an acknowledgement answers; a scanner picks a
/// new sequence number every time, so the reply names the attempt it belongs to.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SynToken {
    /// The sequence number this attempt carried, returned in the
    /// acknowledgement of whatever answers it.
    pub seq: SeqNum,
    /// The port this attempt left from, and so where its reply is addressed.
    pub src_port: u16,
}

/// What a scan's evasion settings come to for one probe: how the packet reaches
/// the wire, how its segment is shaped, and the decoys it travels among.
///
/// All three are derived from one
/// [`EvasionProfile`](crate::evasion::EvasionProfile).
#[derive(Debug, Clone, Copy)]
pub(super) struct EvasionParts<'a> {
    /// How the packet is put on the wire, including any fragmentation.
    pub emission: Emission,
    /// Padding and checksum corruption applied to the Layer-4 segment.
    pub shaping: SegmentShaping,
    /// Addresses the real probe is sent among. Empty for an ordinary send.
    pub decoys: &'a [IpAddr],
}

/// Sends the real probe among its already-built decoy probes, in random order,
/// and returns the real probe's send outcome.
///
/// The randomisation is of the wire order, so an observer cannot pick the real
/// source out of the decoys by position. A decoy is sent and forgotten,
/// nothing about it is recorded, which is what keeps a decoy's reply from ever
/// resolving a port. With no decoys this is one ordinary send.
pub(super) fn emit_among_decoys(
    sender: &dyn ProbeSender,
    dst: IpAddr,
    zone: Option<u32>,
    emission: Emission,
    real_src: IpAddr,
    real_packet: &[u8],
    decoy_packets: &[(IpAddr, Vec<u8>)],
) -> Result<(), SendError> {
    if decoy_packets.is_empty() {
        return sender.send(real_packet, real_src, dst, zone, emission);
    }

    use rand::seq::SliceRandom;

    // The real probe is flagged rather than found by address, so a caller that
    // lists its own address among the decoys still gets its real send back.
    let mut probes: Vec<(IpAddr, &[u8], bool)> = Vec::with_capacity(1 + decoy_packets.len());
    probes.push((real_src, real_packet, true));
    for (src, packet) in decoy_packets {
        probes.push((*src, packet.as_slice(), false));
    }
    probes.shuffle(&mut rand::rng());

    let mut real_result = None;
    for (src, packet, is_real) in &probes {
        let result = sender.send(packet, *src, dst, zone, emission);
        if *is_real {
            real_result = Some(result);
        }
    }
    real_result.expect("the real probe is always among those sent")
}

/// Sends a single SCTP INIT from `src_addr` to `dst_addr:dst_port` through
/// `sender` and logs the outcome. On success it returns the Initiate Tag the
/// packet went out carrying, which a conformant peer echoes back in whatever it
/// answers with, so a reply can be tied to this attempt.
///
/// The counterpart of [`send_syn`] for a sweep asking over SCTP, and it reports
/// its failures the same way and for the same reason. What it does not carry is
/// the segment shaping a SYN takes: an SCTP packet is covered by a CRC32c rather
/// than a checksum worth perturbing, and padding a chunk changes what the
/// receiver reads rather than only how the packet looks. Decoys still apply,
/// being a property of the source address rather than of the packet.
///
/// Infallible in its building, unlike [`send_syn`]: an SCTP checksum covers no
/// pseudo-header, so there are no addresses for the builder to reconcile.
#[allow(clippy::too_many_arguments)]
pub(super) fn send_init(
    sender: &dyn ProbeSender,
    src_addr: IpAddr,
    dst_addr: IpAddr,
    dst_zone: Option<u32>,
    dst_port: u16,
    src_port: u16,
    decoys: &[IpAddr],
    emission: Emission,
    faults: &mut SendFaults,
) -> Option<u32> {
    // Non-zero, which RFC 4960 §3.3.2 requires of an Initiate Tag and which the
    // builder leaves to its caller.
    let tag: u32 = rand::random_range(1..=u32::MAX);
    let packet = protocol::sctp::build_init_probe(src_port, dst_port, tag);

    // A decoy from each address of the target's own family, carrying a port and
    // a tag of its own so none of the probes is the odd one out.
    let decoy_packets: Vec<(IpAddr, Vec<u8>)> = decoys
        .iter()
        .filter(|decoy| decoy.is_ipv4() == dst_addr.is_ipv4())
        .map(|&decoy| {
            let packet = protocol::sctp::build_init_probe(
                rand::random_range(50_000..u16::MAX),
                dst_port,
                rand::random_range(1..=u32::MAX),
            );
            (decoy, packet)
        })
        .collect();

    match emit_among_decoys(
        sender,
        dst_addr,
        dst_zone,
        emission,
        src_addr,
        &packet,
        &decoy_packets,
    ) {
        Ok(()) => {
            success!(verbosity = 2, "sent SCTP init to {dst_addr}:{dst_port}");
            Some(tag)
        }
        Err(e) => {
            faults.record(dst_addr, &e);
            None
        }
    }
}

/// Sends a single TCP SYN packet from `src_addr` to `dst_addr:dst_port` through
/// `sender` and logs the outcome. On success it returns the [`SynToken`] the
/// packet went out carrying, so the caller can record it and recognize a later
/// reply as answering this attempt.
///
/// `reason` receives the failure when there is one, so a scan whose probes never
/// reached the wire can say why in its report rather than only in a log line. A
/// probe that was never sent and a probe nobody answered are indistinguishable
/// in a host count and could hardly be more different in what they mean.
#[allow(clippy::too_many_arguments)]
pub(super) fn send_syn(
    sender: &dyn ProbeSender,
    src_addr: IpAddr,
    dst_addr: IpAddr,
    dst_zone: Option<u32>,
    dst_port: u16,
    src_port_override: Option<u16>,
    evasion: EvasionParts<'_>,
    faults: &mut SendFaults,
) -> Option<SynToken> {
    let EvasionParts {
        emission,
        shaping,
        decoys,
    } = evasion;
    // A caller who pinned a source port gets that port; otherwise a fresh
    // random high port, which is this sweep's default and is what makes a
    // retried probe measurable. see the field this override travels on.
    let src_port: u16 = src_port_override.unwrap_or_else(|| rand::random_range(50_000..u16::MAX));
    let seq_num: u32 = rand::random_range(0..=u32::MAX);

    let packet = match protocol::tcp::build_probe_shaped(
        TcpScanTechnique::Syn,
        src_addr,
        dst_addr,
        src_port,
        dst_port,
        seq_num,
        shaping.padding,
        shaping.bad_tcp_checksum,
    ) {
        Ok(pkt) => pkt,
        Err(e) => {
            error!(
                verbosity = 2,
                "failed to create SYN packet for {dst_addr}:{dst_port}: {e}"
            );
            return None;
        }
    };

    // A decoy from each address of the target's own family, built with its own
    // port and sequence so it is a probe in its own right, and the same shaping
    // so no decoy is the odd one out carrying a different-looking checksum.
    let decoy_packets: Vec<(IpAddr, Vec<u8>)> = decoys
        .iter()
        .filter(|decoy| decoy.is_ipv4() == dst_addr.is_ipv4())
        .filter_map(|&decoy| {
            protocol::tcp::build_probe_shaped(
                TcpScanTechnique::Syn,
                decoy,
                dst_addr,
                rand::random_range(50_000..u16::MAX),
                dst_port,
                rand::random_range(0..=u32::MAX),
                shaping.padding,
                shaping.bad_tcp_checksum,
            )
            .ok()
            .map(|packet| (decoy, packet))
        })
        .collect();

    match emit_among_decoys(
        sender,
        dst_addr,
        dst_zone,
        emission,
        src_addr,
        &packet,
        &decoy_packets,
    ) {
        Ok(_) => {
            success!(verbosity = 2, "sent SYN probe to {dst_addr}:{dst_port}");
            Some(SynToken {
                seq: seq_num,
                src_port,
            })
        }
        Err(e) => {
            // Which of the two this was decides how it is reported; see
            // `SendFaults`. Either way it is said once per kind rather than once
            // per probe: a dual-stack sweep of a range has one unroutable
            // address per name in it, and sixteen identical lines bury
            // everything else.
            if e.is_unroutable() {
                // **Not an error, and not logged as one here at all.** An
                // address this host has no route to is ordinary, the caller
                // reports it once against the address, and an `error!` would
                // print regardless of verbosity: errors are exempt from it,
                // which is exactly right for a scan that broke and exactly
                // wrong for a machine that has no IPv6.
                //
                // The operating system's own words are kept for `-v`, where
                // somebody is asking why rather than being told.
                if faults.unroutable.is_none() {
                    info!(verbosity = 1, "no route to {dst_addr}: {e:#}");
                }
            } else if faults.broken.is_none() {
                // `{e:#}` rather than `{e}`: the outer message says which probe
                // failed, and the chained cause is the operating system's own
                // explanation. "Permission denied" and a full send buffer call
                // for completely different responses, and the bare wrapper
                // distinguishes neither.
                error!(
                    verbosity = 2,
                    "failed to send SYN probe to {dst_addr}:{dst_port}: {e:#}"
                );
            }
            faults.record(dst_addr, &e);
            None
        }
    }
}

/// Sends a single UDP probe from `src_port` to `dst_addr:dst_port` through
/// `sender` and logs the outcome.
///
/// Unlike [`send_syn`], which randomizes its source port per probe, every UDP
/// probe in a scan leaves from the same `src_port`. That single port is the
/// scan's identity on the wire: the capture filter narrows direct replies down
/// to it, and the datagram quoted inside an ICMP error is checked against it.
/// Randomizing per probe would leave no filter expressible but "all UDP".
///
/// `reason` receives the failure when there is one, exactly as it does for
/// [`send_syn`]. A UDP scan whose probes never left reports every port
/// open-filtered - the same answer a firewall produces - and only this says
/// otherwise.
#[allow(clippy::too_many_arguments)]
pub(super) fn send_udp(
    sender: &dyn ProbeSender,
    src_port: u16,
    src_addr: IpAddr,
    dst_addr: IpAddr,
    dst_zone: Option<u32>,
    dst_port: u16,
    evasion: EvasionParts<'_>,
    reason: &mut Option<String>,
) -> Option<()> {
    let EvasionParts {
        emission,
        shaping,
        decoys,
    } = evasion;
    // What makes an open port answer at all: UDP has no handshake, so the
    // application itself has to recognize the request. See [`payload`].
    let payload = payload::for_port(dst_port).to_vec();

    let packet = match crate::protocols::udp::build_packet_shaped(
        src_addr,
        dst_addr,
        src_port,
        dst_port,
        payload,
        shaping.padding,
    ) {
        Ok(pkt) => pkt,
        Err(e) => {
            error!(
                verbosity = 2,
                "failed to create UDP packet for {dst_addr}:{dst_port}: {e}"
            );
            return None;
        }
    };

    // A decoy datagram from each address of the target's own family, from its
    // own source port so its reply falls outside this scan's capture filter, and
    // the same payload so it asks the same question the real probe does.
    let decoy_packets: Vec<(IpAddr, Vec<u8>)> = decoys
        .iter()
        .filter(|decoy| decoy.is_ipv4() == dst_addr.is_ipv4())
        .filter_map(|&decoy| {
            crate::protocols::udp::build_packet_shaped(
                decoy,
                dst_addr,
                rand::random_range(50_000..u16::MAX),
                dst_port,
                payload::for_port(dst_port).to_vec(),
                shaping.padding,
            )
            .ok()
            .map(|packet| (decoy, packet))
        })
        .collect();

    match emit_among_decoys(
        sender,
        dst_addr,
        dst_zone,
        emission,
        src_addr,
        &packet,
        &decoy_packets,
    ) {
        Ok(_) => {
            success!(verbosity = 2, "sent UDP probe to {dst_addr}:{dst_port}");
            Some(())
        }
        Err(e) => {
            // `{e:#}` rather than `{e}`, for the reason `send_syn` gives: the
            // chained cause is the operating system's own explanation, and
            // "No route to host" and "Permission denied" call for completely
            // different responses.
            // Once; see the same guard in `ports::tcp::send_tcp_probe`.
            if reason.is_none() {
                error!(
                    verbosity = 2,
                    "failed to send UDP probe to {dst_addr}:{dst_port}: {e:#}"
                );
                *reason = Some(format!("{e:#}"));
            }
            None
        }
    }
}

/// Why probes did not reach the wire, split by what that says.
///
/// Two kinds, because they are not the same finding. A send path that will
/// not work is a strategy that did not run, and a caller has to hear that the
/// scan covered less than it was asked to. An address this host has no route to
/// is ordinary, a dual-stack name on an IPv4-only network resolves to an AAAA
/// nobody here can reach, and reporting it as a broken scan makes every such
/// scan look partial, which trains a reader to ignore the one that is.
///
/// Each keeps the first of its kind rather than all of them: sixteen identical
/// "no route to host" lines say nothing the first does not.
#[derive(Debug, Default)]
pub(super) struct SendFaults {
    /// The first failure that says this host's send path is the problem.
    pub(super) broken: Option<String>,
    /// The first address this host has no route to, and what it said.
    pub(super) unroutable: Option<(IpAddr, String)>,
    /// How many addresses had no route.
    pub(super) unroutable_count: u64,
    /// Which addresses those were, so the report can name them.
    ///
    /// The count above is what a message says; this is what a consumer reads. A
    /// number cannot tell somebody *which* of their targets went uncovered, and
    /// that is the only part they can act on.
    pub(super) addresses: std::collections::BTreeSet<IpAddr>,
}

impl SendFaults {
    /// Files one failed send against the address it was aimed at.
    fn record(&mut self, target: IpAddr, error: &SendError) {
        if error.is_unroutable() {
            self.unroutable_count += 1;
            self.addresses.insert(target);
            self.unroutable
                .get_or_insert_with(|| (target, error.to_string()));
        } else {
            self.broken.get_or_insert_with(|| error.to_string());
        }
    }
}

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

#[cfg(test)]
mod tests {
    use super::*;
    use crate::scanner::strategy::routed::PROBE_RATE_PER_SEC;
    use std::net::Ipv4Addr;

    /// A sender that refuses one chosen source and accepts every other, so a
    /// test can tell whose send outcome came back.
    struct RefusesOneSource(IpAddr);
    impl ProbeSender for RefusesOneSource {
        fn send(
            &self,
            _segment: &[u8],
            src: IpAddr,
            _dst: IpAddr,
            _zone: Option<u32>,
            _emission: Emission,
        ) -> Result<(), SendError> {
            if src == self.0 {
                Err(SendError::Unsupported("refused for the test"))
            } else {
                Ok(())
            }
        }
    }

    #[test]
    fn emit_among_decoys_sends_every_probe_and_reports_the_real_ones_outcome() {
        use crate::transport::probe::MockSender;

        let real = IpAddr::V4(Ipv4Addr::new(10, 0, 0, 1));
        let dst = IpAddr::V4(Ipv4Addr::new(10, 0, 0, 9));
        let real_packet = vec![0xAAu8, 0xBB];
        let decoys = vec![
            (IpAddr::V4(Ipv4Addr::new(10, 0, 0, 2)), vec![1u8, 1]),
            (IpAddr::V4(Ipv4Addr::new(10, 0, 0, 3)), vec![2u8, 2]),
        ];

        // Every probe reaches the wire, the real one and both decoys, and the
        // real source appears exactly once.
        let mock = MockSender::default();
        assert!(
            emit_among_decoys(
                &mock,
                dst,
                None,
                Emission::routed(),
                real,
                &real_packet,
                &decoys
            )
            .is_ok()
        );
        let sent = mock.sent.lock().unwrap();
        assert_eq!(sent.len(), 3, "the real probe and both decoys are all sent");
        assert_eq!(sent.iter().filter(|(_, src, _)| *src == real).count(), 1);
        drop(sent);

        // With no decoys it is a single ordinary send.
        let mock = MockSender::default();
        emit_among_decoys(
            &mock,
            dst,
            None,
            Emission::routed(),
            real,
            &real_packet,
            &[],
        )
        .unwrap();
        assert_eq!(mock.sent.lock().unwrap().len(), 1);

        // The outcome returned is the real probe's own, never a decoy's, which
        // is what lets a caller keep a token only when *its* probe was sent, the
        // root of the invariant that a decoy resolves no port.
        let refusing_the_real = RefusesOneSource(real);
        assert!(
            emit_among_decoys(
                &refusing_the_real,
                dst,
                None,
                Emission::routed(),
                real,
                &real_packet,
                &decoys
            )
            .is_err()
        );
        let refusing_a_decoy = RefusesOneSource(decoys[0].0);
        assert!(
            emit_among_decoys(
                &refusing_a_decoy,
                dst,
                None,
                Emission::routed(),
                real,
                &real_packet,
                &decoys
            )
            .is_ok()
        );
    }

    /// The two kinds of send failure are kept apart, and each keeps only its
    /// first.
    ///
    /// They are reported through different channels: a broken send path is a
    /// strategy that did not run and reaches the report as a failure; an
    /// address with no route is said once and changes nothing about the scan's
    /// standing. Collapsed into one counter, a dual-stack name on an IPv4-only
    /// network made every scan of it report itself partial, which teaches a
    /// reader to ignore the warning that matters.
    #[test]
    fn a_missing_route_is_counted_apart_from_a_broken_send_path() {
        let unreachable = |address: &str| {
            SendError::from_io(std::io::Error::new(
                std::io::ErrorKind::HostUnreachable,
                format!("failed to send to {address}: No route to host"),
            ))
        };

        let mut faults = SendFaults::default();
        let first: IpAddr = "2001:db8::1".parse().expect("literal");
        let second: IpAddr = "2001:db8::2".parse().expect("literal");

        faults.record(first, &unreachable("2001:db8::1"));
        faults.record(second, &unreachable("2001:db8::2"));

        assert_eq!(faults.unroutable_count, 2);
        assert_eq!(
            faults.unroutable.as_ref().map(|(address, _)| *address),
            Some(first),
            "the first address is kept, not the last"
        );
        assert!(
            faults.broken.is_none(),
            "no route to somewhere is not a scan that could not run"
        );

        faults.record(
            first,
            &SendError::from_io(std::io::Error::new(
                std::io::ErrorKind::PermissionDenied,
                "Operation not permitted",
            )),
        );

        assert!(faults.broken.is_some(), "and this one is");
        assert_eq!(faults.unroutable_count, 2, "which is a separate tally");
    }

    /// The rate a sweep actually paces itself at, which is what the pair has
    /// to reproduce however it is split between the two.
    fn effective_rate(rate_per_sec: u32) -> f64 {
        let (tick, batch) = pacing_for(NonZeroU32::new(rate_per_sec).expect("a non-zero rate"));
        batch as f64 / tick.as_secs_f64()
    }

    #[test]
    fn a_fast_rate_is_expressed_as_a_batch_on_the_shortest_tick() {
        assert_eq!(
            pacing_for(NonZeroU32::new(2_000).unwrap()),
            (MIN_SEND_TICK, 2)
        );
        assert_eq!(
            pacing_for(NonZeroU32::new(100_000).unwrap()),
            (MIN_SEND_TICK, 100)
        );
    }

    /// The failure this pair exists to prevent. A batch cannot be less than one
    /// probe, so holding the tick fixed collapses every rate below one probe
    /// per tick onto the same value - and a sweep asked for 500 a second runs
    /// at 1000 without saying so.
    #[test]
    fn a_slow_rate_lengthens_the_tick_rather_than_doubling_the_rate() {
        assert_eq!(
            pacing_for(NonZeroU32::new(500).unwrap()),
            (Duration::from_millis(2), 1)
        );
        assert_eq!(
            pacing_for(NonZeroU32::new(100).unwrap()),
            (Duration::from_millis(10), 1)
        );
    }

    #[test]
    fn every_rate_is_paced_at_the_rate_it_asked_for() {
        for rate in [1, 100, 500, 999, 1_000, 1_500, 2_000, 4_000, 16_000] {
            let effective = effective_rate(rate);
            let error = (effective - f64::from(rate)).abs() / f64::from(rate);
            assert!(
                error < 0.01,
                "{rate}/s is paced at {effective}/s, off by {:.0}%",
                error * 100.0
            );
        }
    }

    /// A rate of zero is a caller error, not an instruction to stall forever.
    ///
    /// It can no longer be asked at any level. `pacing_for` takes a
    /// [`NonZeroU32`] and so does the configuration above it, so the fallback
    /// this holds is now only the one a caller means: no ceiling at all.
    ///
    /// Zero used to arrive here as `Some(0)` and resolve to the engine's own
    /// rate, at three call sites of which only this one went through the
    /// resolver, while the report recorded the ceiling the caller believed they
    /// had set.
    #[test]
    fn an_unset_rate_falls_back_to_the_default_and_a_set_one_is_obeyed() {
        assert_eq!(
            rate_within(None, None, PROBE_RATE_PER_SEC),
            PROBE_RATE_PER_SEC
        );
        assert_eq!(
            rate_within(NonZeroU32::new(500), None, PROBE_RATE_PER_SEC).get(),
            500,
            "a rate the caller meant is the rate they get"
        );
    }

    /// The floor lifts a default and stops at a ceiling.
    ///
    /// The second case is the one worth pinning. A floor above an explicit
    /// ceiling is a contradiction the caller can express in a settings file, and
    /// resolving it the other way would push a target the operator had said must
    /// not be pushed, on the strength of a throughput preference.
    #[test]
    fn a_floor_raises_the_default_but_never_a_ceiling() {
        let default = PROBE_RATE_PER_SEC;

        assert_eq!(
            rate_within(None, NonZeroU32::new(default.get() * 2), default).get(),
            default.get() * 2,
            "with no ceiling set, a floor above the engine's own rate is the rate"
        );
        assert_eq!(
            rate_within(None, NonZeroU32::new(1), default),
            default,
            "a floor below the engine's own rate changes nothing"
        );
        assert_eq!(
            rate_within(NonZeroU32::new(50), NonZeroU32::new(5_000), default).get(),
            50,
            "the ceiling wins: a safety limit is not traded away for a throughput wish"
        );
        assert_eq!(
            rate_within(NonZeroU32::new(5_000), NonZeroU32::new(50), default).get(),
            5_000,
            "a ceiling already above the floor is left where it is"
        );
    }
}