zond-engine 0.14.0

The core networking library powering Zond. Raw packet injection, protocol parsing, service and OS fingerprinting, and asynchronous network scanning.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
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
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
// 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

//! # Unprivileged TCP Connect Scanning
//!
//! The fallback strategy for when raw sockets are not available, whether because
//! the process is not root, no usable interface exists, or the OS could not route
//! a target. Everything here is built on ordinary [`TcpStream`] connects, so it
//! needs no special privileges and works anywhere the async runtime does.
//!
//! It answers both scan phases. [`discover`] establishes host presence by probing
//! a small set of common infrastructure ports and treating any TCP-layer response,
//! an accept or even a refusal, as proof the host is alive. [`scan`] takes known
//! targets and classifies each port from a full connect handshake.
//!
//! Both draw their work in shuffled batches and cap their in-flight connections
//! with a [`ProbePool`] to avoid exhausting OS sockets, and both record findings
//! through the shared [`ScanContext`] like every other strategy. What they draw
//! differs with the phase: a sweep asks about an address and a port scan about
//! an address paired with a port, which is the unit each of them settles.

use crate::config::ServiceDetection;
use crate::config::limits::{CONNECT_PROBE_TIMEOUT, DISCOVERY_CONCURRENCY};
use crate::error;
use crate::evasion::EvasionProfile;
use crate::journal::settle::{Outcome, Settled};
use crate::model::host::{Host, HostStatus, NetworkRole, StatusProtocol, StatusReason};
use crate::model::ip::scoped::ZoneMap;
use crate::model::ip::set::IpSet;
use crate::model::port::discovery::{Discovery, ScanResponse};
use crate::model::port::{Port, PortSet, PortState, Protocol};
use crate::model::target::PlannedTarget;
use crate::report::ScannerKind;
use crate::report::StopReason;
use crate::scanner::audit::ProbeAudit;
use crate::scanner::dispatcher::dispatch_addresses;
use crate::scanner::handle::ScanHandle;
use crate::scanner::payload;
use crate::scanner::pool::ProbePool;
use crate::scanner::session::ScanContext;
use crate::scanner::strategy::{HostScanner, PortScanner, StrategyError};
use async_trait::async_trait;
use socket2::{Domain, Socket, Type};
use std::io::ErrorKind;
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
use std::sync::Arc;
use std::time::Instant;
use tokio::net::{TcpSocket, TcpStream};
use tokio::sync::mpsc;
use tokio::time::timeout;

/// The evasion an unprivileged connect probe can honour: a source port to leave
/// from and a hop limit to carry.
///
/// Both are ordinary socket options that need no privilege, so they belong on
/// this path as much as on the raw one: a hop limit a filter keys on should be
/// the chosen value on *every* probe, the connect fallback included, or the
/// fallback would leak the real one. The framing techniques, a spoofed hardware
/// address, fragmentation, decoys, are absent here because they need a
/// self-built frame this path never touches; a profile that asks for one opens
/// the Ethernet path and never reaches this scanner. The segment shapers,
/// padding, a corrupt checksum, are absent for a different reason: the kernel
/// builds the segment a connect sends, so there is nothing here to shape.
#[derive(Debug, Clone, Copy, Default)]
struct ConnectShaping {
    /// The source port every probe binds to, or `None` to let the OS choose one.
    source_port: Option<u16>,
    /// The hop limit every probe carries, or `None` to leave the OS default.
    hop_limit: Option<u8>,
}

impl ConnectShaping {
    /// Whether either field departs from what the OS would pick, so a plain
    /// connect can be taken when it does not.
    fn is_active(self) -> bool {
        self.source_port.is_some() || self.hop_limit.is_some()
    }
}

impl From<&EvasionProfile> for ConnectShaping {
    fn from(evasion: &EvasionProfile) -> Self {
        Self {
            source_port: evasion.source_port,
            hop_limit: evasion.ttl,
        }
    }
}

/// Adapts the unprivileged [`discover`] strategy to [`HostScanner`], so it can
/// be spawned alongside [`LocalScanner`](super::local::LocalScanner) and
/// [`RoutedScanner`](super::routed::RoutedScanner) from a single explorer list.
pub struct ConnectScanner {
    /// The addresses being probed for aliveness.
    ips: IpSet,
    /// Shared state (host store, event channel, abort signal) for the scan
    /// this explorer is part of.
    ctx: ScanContext,
    /// What each liveness probe changes about the packet it sends. Only the
    /// source port and hop limit reach the wire from here (see [`ConnectShaping`]).
    evasion: EvasionProfile,
}

impl ConnectScanner {
    /// Checks each of `ips` for a pulse, connecting to a handful of common
    /// infrastructure ports and taking any TCP-layer answer, an accept or a
    /// refusal alike, as proof that something is there.
    ///
    /// Hosts are filed through `ctx`. Of `evasion`, only the source port and
    /// the hop limit reach the wire; the kernel builds the rest of what a
    /// connect sends.
    pub fn new(ips: IpSet, ctx: ScanContext, evasion: &EvasionProfile) -> Self {
        Self {
            ips,
            ctx,
            evasion: evasion.clone(),
        }
    }
}

#[async_trait]
impl HostScanner for ConnectScanner {
    fn kind(&self) -> ScannerKind {
        ScannerKind::Connect
    }

    async fn discover_hosts(&mut self) -> Result<(), StrategyError> {
        // The targets are taken rather than cloned. A sweep asks each address
        // once, so a second call has nothing left to probe and correctly does
        // nothing, where a clone would silently re-probe the whole set.
        discover(
            std::mem::take(&mut self.ips),
            self.ctx.clone(),
            &self.evasion,
        )
        .await
    }
}

/// What one finished prober task learned. A probe never fails, since every
/// network outcome maps to some combination of the fields below, so this is a
/// plain [`Option`] rather than a `Result`.
///
/// `None` means the target was not probed at all.
struct Probed {
    /// The address probed.
    ip: IpAddr,
    /// The port verdict, where the probe produced one.
    ///
    /// Separate from [`Probed::answered`] because the two say different things:
    /// a timeout yields a `Filtered` port and proves nothing about the host,
    /// while a refusal yields a `Closed` port *and* proves the host is up. Only
    /// a target that was never probed - UDP through a TCP prober - carries
    /// `None`.
    port: Option<Port>,
    /// What the port said while it was being fingerprinted, carried out of the
    /// probe for the detection phase to hand a passive detection.
    ///
    /// This scanner holds the only connection an unprivileged scan makes to the
    /// port, so bytes dropped here are bytes no later phase can read without
    /// dialling again. Empty for every probe that drew nothing.
    responses: Vec<String>,

    /// What those same bytes said about the *machine*, carried out for the same
    /// reason and filed in a different place: the service belongs to the port,
    /// the operating system to the host.
    ///
    /// Empty for every probe that drew nothing, and for every verdict that came
    /// from the kernel rather than from a conversation.
    about_the_host: crate::fingerprint::AboutTheHost,
    /// Whether the host answered. The kernel hands back a completed handshake or
    /// a `ConnectionRefused` only when a segment came back from the target, so
    /// either one proves a live stack - a refusal is a RST the kernel
    /// translated. A timeout proves nothing and never sets this.
    answered: bool,
    /// What became of this target, for a resume.
    ///
    /// Distinct from [`answered`](Self::answered), which is about the *host*: a
    /// timeout proves nothing about the host and still settles the target,
    /// because the connect made its one and only attempt.
    outcome: Outcome,
    /// What the reply proved the host *is*, where its protocol says so.
    ///
    /// A claim about the host rather than about the port, and carried alongside
    /// the verdict rather than folded into it for that reason: a name server
    /// and a socket bound to 53 produce the same `Open`, and only one of them
    /// is a name server. See [`payload::declared_role`].
    role: Option<NetworkRole>,
}

/// The outcome of one finished [`port_prober`] task.
type ProbedPort = Option<Probed>;

/// Adapts the unprivileged [`scan`] engine to [`PortScanner`], so
/// [`crate::scanner::scan`] can drive it through the same path as the privileged
/// [`TcpPortScanner`](super::ports::TcpPortScanner).
///
/// It carries no [`detect_services`](PortScanner::detect_services) override,
/// because the connect engine fingerprints each port inline over the live stream
/// it already holds (see this module's port prober), so a second identification pass would
/// be wasted work. This is the reason service detection lives on the trait rather
/// than in the caller: the fact that connect needs no second pass is expressed
/// here by its absence, instead of as a branch at the call site.
pub struct ConnectPortScanner {
    /// Shared state (host store, event channel, abort signal) for the scan this
    /// strategy is part of.
    ctx: ScanContext,
    /// The ceiling on in-flight connect probes.
    concurrency: usize,
    /// How far each probe may go to name what answered.
    ///
    /// [`ServiceDetection::Off`] means something slightly different here than it
    /// does on the privileged path, and the difference is worth knowing: this
    /// scanner's connection *is* how the port's state is established, so turning
    /// identification off skips the conversation, never the connection. A caller
    /// who needs the target's application logs to stay clean needs raw sockets;
    /// without them, being seen is the price of the answer.
    detection: ServiceDetection,
    /// What each probe changes about the packet it sends. Only the source port
    /// and hop limit reach the wire from here (see [`ConnectShaping`]).
    evasion: EvasionProfile,
    /// The interface each link-local target was named on, empty for a scan that
    /// named none. A `SocketAddrV6` with a zero scope id will not connect to a
    /// neighbour however close it is, so the scope id is carried per target and
    /// applied where the endpoint is built.
    zones: ZoneMap,
}

impl ConnectPortScanner {
    /// Settles each `(address, port)` it is fed with a full handshake, holding
    /// at most `concurrency` connections open and recording verdicts through
    /// `ctx`.
    ///
    /// `detection` decides how far the conversation goes once a port answers,
    /// not whether the connection is made: the connection is what establishes
    /// the state. `evasion` contributes the source port and the hop limit.
    pub fn new(
        ctx: ScanContext,
        concurrency: usize,
        detection: ServiceDetection,
        evasion: &EvasionProfile,
    ) -> Self {
        Self {
            ctx,
            concurrency,
            detection,
            evasion: evasion.clone(),
            zones: ZoneMap::new(),
        }
    }

    /// Names the interface each of the scan's link-local targets was given on.
    ///
    /// Without it a link-local endpoint is built with a zero scope id, which the
    /// kernel refuses to connect however reachable the neighbour is.
    pub fn with_zones(mut self, zones: ZoneMap) -> Self {
        self.zones = zones;
        self
    }
}

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

    fn supported_protocols(&self) -> Vec<Protocol> {
        vec![Protocol::Tcp]
    }

    async fn scan(&mut self, rx: mpsc::Receiver<PlannedTarget>) -> Result<(), StrategyError> {
        scan(
            rx,
            self.concurrency,
            self.ctx.clone(),
            self.detection,
            &self.evasion,
            &self.zones,
        )
        .await
    }
}

/// Unprivileged UDP port scanner.
pub struct ConnectUdpPortScanner {
    ctx: ScanContext,
    concurrency: usize,
    /// What each probe changes about the packet it sends. Only the source port
    /// and hop limit reach the wire from here (see [`ConnectShaping`]).
    evasion: EvasionProfile,
    /// How far the second pass may go to name what answered.
    ///
    /// Unlike [`ConnectPortScanner`] beside it, this one cannot identify a
    /// service inline: there is no connection to hold, and the datagram that
    /// establishes the port is open is not the one that identifies what is
    /// behind it. So it runs the second pass, and holds the level to run it at.
    service_detection: ServiceDetection,
    /// The interface each link-local target was named on, empty for a scan that
    /// named none. A `SocketAddrV6` with a zero scope id will not connect to a
    /// neighbour however close it is, so the scope id is carried per target and
    /// applied where the endpoint is built.
    zones: ZoneMap,
}

impl ConnectUdpPortScanner {
    /// Sends one datagram per `(address, port)` it is fed, `concurrency` of
    /// them in flight at a time, and files what came back through `ctx`. As on
    /// the TCP path, `evasion` reaches the wire as a source port and a hop
    /// limit and no further.
    ///
    /// A closed verdict here proves nothing about the host. It comes from an
    /// ICMP error the kernel matched to the socket, and the error's own source,
    /// a router as easily as the target, is not surfaced through this API. Only
    /// a datagram coming back proves the port and the host at once.
    pub fn new(ctx: ScanContext, concurrency: usize, evasion: &EvasionProfile) -> Self {
        Self::with_detection(ctx, concurrency, evasion, ServiceDetection::default())
    }

    /// The same scanner, told how far the second pass may go.
    ///
    /// [`new`](Self::new) is the ordinary way in and takes the default level;
    /// this is for a caller carrying a level of its own, which is every caller
    /// that read one from a configuration.
    pub fn with_detection(
        ctx: ScanContext,
        concurrency: usize,
        evasion: &EvasionProfile,
        service_detection: ServiceDetection,
    ) -> Self {
        Self {
            ctx,
            concurrency,
            evasion: evasion.clone(),
            service_detection,
            zones: ZoneMap::new(),
        }
    }

    /// Names the interface each of the scan's link-local targets was given on,
    /// as on the TCP scanner beside it.
    pub fn with_zones(mut self, zones: ZoneMap) -> Self {
        self.zones = zones;
        self
    }
}

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

    fn supported_protocols(&self) -> Vec<Protocol> {
        vec![Protocol::Udp]
    }

    /// Identifies the UDP services this scanner found open.
    ///
    /// [`ConnectPortScanner`] needs no such pass because it fingerprints over
    /// the stream it already holds. There is no equivalent here: a UDP probe is
    /// one datagram, sent to establish that the port is open, and the question
    /// that identifies what answered is a second one. So the phase runs, scoped
    /// to [`Protocol::Udp`] so a composite's TCP member keeps its own half.
    async fn detect_services(&mut self, ctx: &ScanContext) {
        crate::scanner::service::detect(ctx, self.service_detection, Protocol::Udp).await;
    }

    async fn scan(&mut self, mut rx: mpsc::Receiver<PlannedTarget>) -> Result<(), StrategyError> {
        let ctx = self.ctx.clone();
        let shaping = ConnectShaping::from(&self.evasion);
        let mut pool = ProbePool::new(
            self.concurrency,
            self.ctx.clone(),
            self.kind(),
            |probed, audit: &mut ProbeAudit| absorb_probe(&ctx, probed, audit),
        );

        let mut probes = 0u128;
        let mut reason = StopReason::AttemptsSpent;
        while let Some(target) = rx.recv().await {
            if let Some(cause) = self.ctx.handle.stopped() {
                reason = cause.into();
                record_unasked(&self.ctx, &target);
                break;
            }
            probes += 1;
            // A host past its own budget is left alone. Counted with the
            // probes, because it was work routed here, and recorded unasked so a
            // resume asks about it rather than trusting a verdict nobody earned.
            if self.ctx.host_expired(target.ip()) {
                record_unasked(&self.ctx, &target);
                continue;
            }
            pool.audit().record_send(true);
            let endpoint = self.zones.endpoint(target.ip(), target.port());
            pool.admit(udp_port_prober(target, shaping, endpoint)).await;
        }

        // Anything still queued was never sent, and carries no position to
        // settle. The TCP scan above has always done this; leaving it out here
        // both lost the ports and left the sitting's settlement counts short of
        // the targets it was handed.
        while let Ok(target) = rx.try_recv() {
            record_unasked(&self.ctx, &target);
        }

        pool.drain().await;
        finish(&self.ctx, pool.into_audit(), self.kind(), probes, reason);
        Ok(())
    }
}

/// Performs a high-concurrency, unprivileged port scan.
///
/// This is the primary scanning strategy for callers without root privileges. It
/// consumes the randomized stream of targets a
/// [`Dispatcher`](crate::scanner::dispatcher::Dispatcher) produces, holding the
/// number of in-flight connections at or below `concurrency_limit` to avoid
/// exhausting OS sockets, and records every port it probed into the shared
/// [`ScanContext`] store - open, closed and filtered alike, so the list does not
/// depend on whether the caller had root.
pub async fn scan(
    mut rx: mpsc::Receiver<PlannedTarget>,
    concurrency_limit: usize,
    ctx: ScanContext,
    detection: ServiceDetection,
    evasion: &EvasionProfile,
    zones: &ZoneMap,
) -> Result<(), StrategyError> {
    let shaping = ConnectShaping::from(evasion);
    let folder = ctx.clone();
    let mut pool = ProbePool::new(
        concurrency_limit,
        ctx.clone(),
        ScannerKind::Connect,
        |probed, audit: &mut ProbeAudit| absorb_probe(&folder, probed, audit),
    );

    let mut probes = 0u128;
    let mut reason = StopReason::AttemptsSpent;
    while let Some(target) = rx.recv().await {
        if let Some(cause) = ctx.handle.stopped() {
            reason = cause.into();
            // This one was taken off the queue and never asked, so it is
            // recorded with the rest still waiting behind it.
            record_unasked(&ctx, &target);
            break;
        }
        probes += 1;
        // A host past its own budget is left alone, and its remaining ports are
        // recorded unasked rather than given a verdict nothing earned.
        if ctx.host_expired(target.ip()) {
            record_unasked(&ctx, &target);
            continue;
        }
        pool.audit().record_send(true);
        let endpoint = zones.endpoint(target.ip(), target.port());
        pool.admit(port_prober(target, detection, shaping, endpoint))
            .await;
    }

    // Anything still queued was never sent, and carries no position to settle.
    while let Ok(target) = rx.try_recv() {
        record_unasked(&ctx, &target);
    }

    // Every target dispatched; wait out the probes still in flight.
    pool.drain().await;
    finish(
        &ctx,
        pool.into_audit(),
        ScannerKind::Connect,
        probes,
        reason,
    );
    Ok(())
}

/// Folds one finished probe into the store: the port it classified, if it
/// classified one worth keeping, and what the exchange proved about the host.
///
/// A refused connection reaches here with no port and `answered` set, which is
/// the case worth noticing: this strategy declines to file closed ports, but the
/// RST behind the refusal still proves the host is there, and that evidence
/// would otherwise be dropped along with the port verdict.
///
/// The responses the inline fingerprint drew are kept here too. They belong to
/// no host record, so they go to the context the
/// [detection phase](crate::scanner::detection) reads them from, which is the same
/// place [`service::detect`](crate::scanner::service::detect) puts the ones a
/// raw scan draws in its second pass.
fn absorb_probe(ctx: &ScanContext, probed: ProbedPort, audit: &mut ProbeAudit) {
    let Some(probed) = probed else {
        return;
    };
    ctx.record_outcome(probed.outcome);
    if probed.answered {
        // A connect probe carries no attempt token: the retransmission that may
        // have produced this answer was the host stack's, on its own schedule
        // (see `CONNECT_PROBE_TIMEOUT`), so which attempt was answered is
        // not knowable from here.
        audit.record_host_found(None);
    }
    if probed.port.is_none() && !probed.answered && probed.role.is_none() {
        return;
    }

    // Filed under the same key the port is, which is the key the detection
    // phase looks the responses up by: a host's zone comes from the key it was
    // stored under, so the two cannot disagree.
    if let Some((number, protocol)) = probed
        .port
        .as_ref()
        .map(|port| (port.number(), port.protocol()))
    {
        ctx.record_responses(probed.ip.into(), number, protocol, probed.responses);
    }

    ctx.update_host(probed.ip, |host| {
        if let Some(port) = probed.port.clone() {
            host.add_port(port);
        }
        if let Some(role) = probed.role {
            host.add_network_role(role);
        }
        if probed.answered {
            host.record_evidence(
                HostStatus::Up,
                StatusReason::new(StatusProtocol::TcpSyn, "tcp connect answered by the host"),
            );
        }
        if !probed.about_the_host.is_empty() {
            // The same call the service phase makes on the privileged path.
            // What a banner says about the machine is worth the same whichever
            // scanner happened to draw it, and this scanner is the only one
            // that draws it without a raw socket.
            probed.about_the_host.clone().apply(host);
        }
    });
}

/// A port in `state`, carrying the packet that settled it where one did.
///
/// This scanner never sees a segment, the kernel does the handshake and hands
/// back an outcome, but the outcome names the packet exactly: a completed
/// connection is a SYN/ACK, a refusal is the RST the kernel translated into it,
/// and a timeout is silence. Recorded so an unprivileged report can say what its
/// verdicts rest on, which is the one thing separating a port a firewall dropped
/// from a port nothing was listening on.
///
/// `None` where no packet is implied: a local failure, no route, no socket
/// left, is this host giving up, and crediting the target with a silence it was
/// never asked for would be evidence of the wrong thing.
fn settled(number: u16, state: PortState, reason: Option<ScanResponse>) -> Port {
    let port = crate::fingerprint::baseline_port(number, Protocol::Tcp, state);

    match reason {
        Some(reason) => port.with_discovery(Discovery::new(reason)),
        None => port,
    }
}

/// Records a planned target no probe was ever sent to.
///
/// Three ways one arises in this strategy: the scan stopped with targets still
/// queued, the target's host had already spent
/// [`ZondConfig::host_timeout`](crate::config::ZondConfig::host_timeout), and
/// this machine failed the connect locally before anything left it.
///
/// All three leave the port on the host rather than off it, for the reason
/// [`port_prober`]'s refusal branch gives about `Closed`: a port list whose shape
/// depends on how a run ended is a different answer rather than a smaller one,
/// and a comparison of two scans reads the difference as the network moving.
/// What the port says is [`PortState::Unasked`], which is the whole of what this
/// run established about it, and the outcome carries no position, so a resume
/// asks the question this sitting did not.
fn record_unasked(ctx: &ScanContext, target: &PlannedTarget) {
    let port =
        crate::fingerprint::baseline_port(target.port(), target.protocol(), PortState::Unasked);
    ctx.update_host(target.ip(), |host| {
        host.add_port(port);
    });
    ctx.record_outcome(Outcome::Unasked);
}

/// Probes a single [`Target`] over a full TCP connect handshake and classifies
/// its port. Returns `Some(..)` for a non-closed port and `None` for a closed
/// port or a target this strategy doesn't handle.
///
/// An accepted connection is `Open` and gets fingerprinted over the live stream,
/// and a refusal is `Closed`. Anything else is `Filtered`, including a timeout,
/// which is the usual signature of a firewall drop. Only TCP is supported, so UDP
/// targets are skipped.
async fn port_prober(
    planned: PlannedTarget,
    detection: ServiceDetection,
    shaping: ConnectShaping,
    socket_addr: SocketAddr,
) -> ProbedPort {
    let target = planned.target;
    if target.protocol == Protocol::Udp {
        // UDP can't be probed through a TCP stream; skip rather than misreport.
        // No outcome: unreported is re-probed, which is what a routing mistake
        // deserves.
        return None;
    }

    let position = planned.position;

    match timeout(CONNECT_PROBE_TIMEOUT, connect_shaped(socket_addr, shaping)).await {
        Ok(Ok(stream)) => {
            let port = settled(target.port, PortState::Open, Some(ScanResponse::TcpSynAck));
            // The detailed form, for the second and third values. This
            // handshake is the only conversation an unprivileged scan has with
            // the port, so what it draws here is everything any later phase can
            // read without dialling again: the responses a passive detection
            // needs, and what the same bytes said about the machine.
            let (port, about_the_host, responses) =
                crate::fingerprint::fingerprint_tcp_detailed(stream, port, detection).await;
            Some(Probed {
                ip: target.ip,
                port: Some(port),
                responses,
                about_the_host,
                answered: true,
                outcome: Outcome::Answered { position },
                // A TCP handshake proves a service, and the service is the
                // port's to name. No role is read from one.
                role: None,
            })
        }
        Ok(Err(e)) => {
            match e.kind() {
                // A refusal is the clearest verdict this scanner ever gets, and
                // it is filed as one. The RST the kernel translated into it
                // proves two things at once: the port has nothing listening, and
                // something is there to say so.
                //
                // Recorded rather than dropped because a port list that changes
                // with the caller's privilege level is not a smaller answer, it
                // is a different one. The raw path files `Closed` here, so
                // omitting it left an unprivileged report with no `Closed` entry
                // in its `ports_by_state` however many refusals it collected -
                // a summary that was structurally wrong rather than merely
                // incomplete, and exactly the kind of difference somebody
                // diffing two scans would read as a change in the network.
                ErrorKind::ConnectionRefused => Some(Probed {
                    ip: target.ip,
                    port: Some(settled(
                        target.port,
                        PortState::Closed,
                        Some(ScanResponse::TcpRst),
                    )),
                    responses: Vec::new(),
                    about_the_host: crate::fingerprint::AboutTheHost::default(),
                    answered: true,
                    outcome: Outcome::Answered { position },
                    role: None,
                }),
                // Anything else failed without a segment leaving this machine -
                // a local routing failure, an exhausted resource - so nothing
                // was asked and the host has proved nothing. The next sitting
                // may well get further.
                //
                // No evidence recorded, since there is no packet to name, and
                // no verdict either: this used to file `Filtered`, which credits
                // the target with a silence it was never asked for in the one
                // field a reader takes for a finding.
                _ => Some(Probed {
                    ip: target.ip,
                    port: Some(settled(target.port, PortState::Unasked, None)),
                    responses: Vec::new(),
                    about_the_host: crate::fingerprint::AboutTheHost::default(),
                    answered: false,
                    outcome: Outcome::Unroutable,
                    role: None,
                }),
            }
        }
        // Timeout: the probe was silently dropped, the classic firewall
        // signature. Settled, because a connect gets one attempt and this was
        // it: the whole budget, spent.
        Err(_) => Some(Probed {
            ip: target.ip,
            port: Some(settled(
                target.port,
                PortState::Filtered,
                Some(ScanResponse::NoResponse),
            )),
            responses: Vec::new(),
            about_the_host: crate::fingerprint::AboutTheHost::default(),
            answered: false,
            outcome: Outcome::Exhausted { position },
            role: None,
        }),
    }
}

/// The address a probe socket for a destination in `family`'s address family
/// binds its source to, carrying `port` (`0` lets the OS pick one).
///
/// A socket bound to `0.0.0.0` cannot reach an IPv6 destination - the connect
/// fails outright - so binding the family the target belongs to is what makes
/// v6 targets reachable at all rather than silently unprobed.
fn source_bind(family: IpAddr, port: u16) -> SocketAddr {
    match family {
        IpAddr::V4(_) => SocketAddr::new(IpAddr::V4(Ipv4Addr::UNSPECIFIED), port),
        IpAddr::V6(_) => SocketAddr::new(IpAddr::V6(Ipv6Addr::UNSPECIFIED), port),
    }
}

/// The wildcard, ephemeral-port address a probe socket for `target` binds to
/// when nothing about its source is being chosen.
fn wildcard_for(target: IpAddr) -> SocketAddr {
    source_bind(target, 0)
}

/// Sets `shaping`'s hop limit on a fresh socket, and, where a source port is
/// pinned, the address reuse a pinned port needs.
///
/// The hop limit goes on with the option the address family uses (`IP_TTL` or
/// `IPV6_UNICAST_HOPS`), so it is in force before the first byte leaves. Address
/// reuse is what lets the many probes a scan runs at once each bind the one
/// pinned source port: every probe still carries a distinct four-tuple through
/// its destination, so the kernel keeps their replies apart. The bind itself is
/// left to the caller, because TCP binds only to pin a port while UDP must bind
/// before it can send at all.
fn configure_shaping(
    socket: &Socket,
    family: IpAddr,
    shaping: ConnectShaping,
) -> std::io::Result<()> {
    if let Some(hops) = shaping.hop_limit {
        match family {
            IpAddr::V4(_) => socket.set_ttl_v4(hops.into())?,
            IpAddr::V6(_) => socket.set_unicast_hops_v6(hops.into())?,
        }
    }
    if shaping.source_port.is_some() {
        socket.set_reuse_address(true)?;
        // Unix only, and both supported platforms are: without it a second
        // socket on the pinned port is refused rather than bound alongside.
        #[cfg(unix)]
        socket.set_reuse_port(true)?;
    }
    Ok(())
}

/// A TCP socket set up to honour `shaping`, ready to connect to a peer in
/// `family`'s address family. Only reached when `shaping` is active.
fn shaped_tcp_socket(family: IpAddr, shaping: ConnectShaping) -> std::io::Result<TcpSocket> {
    let domain = match family {
        IpAddr::V4(_) => Domain::IPV4,
        IpAddr::V6(_) => Domain::IPV6,
    };
    let socket = Socket::new(domain, Type::STREAM, Some(socket2::Protocol::TCP))?;
    configure_shaping(&socket, family, shaping)?;
    if let Some(port) = shaping.source_port {
        socket.bind(&source_bind(family, port).into())?;
    }
    socket.set_nonblocking(true)?;
    Ok(TcpSocket::from_std_stream(std::net::TcpStream::from(
        socket,
    )))
}

/// Connects to `addr`, honouring `shaping`.
///
/// With inert shaping this is exactly a plain [`TcpStream::connect`], so a scan
/// that chose neither a source port nor a hop limit sends the SYN it always has,
/// byte for byte.
async fn connect_shaped(addr: SocketAddr, shaping: ConnectShaping) -> std::io::Result<TcpStream> {
    if !shaping.is_active() {
        return TcpStream::connect(addr).await;
    }
    shaped_tcp_socket(addr.ip(), shaping)?.connect(addr).await
}

/// A UDP socket bound to `family`'s wildcard and honouring `shaping`, ready to
/// be connected to a peer.
///
/// With inert shaping this is the plain ephemeral bind the scanner has always
/// used. Otherwise the socket carries the chosen hop limit and binds the chosen
/// source port (or an ephemeral one, so a hop-limit-only scan still has a socket
/// to send from).
async fn shaped_udp_socket(
    family: IpAddr,
    shaping: ConnectShaping,
) -> std::io::Result<tokio::net::UdpSocket> {
    if !shaping.is_active() {
        return tokio::net::UdpSocket::bind(wildcard_for(family)).await;
    }
    let domain = match family {
        IpAddr::V4(_) => Domain::IPV4,
        IpAddr::V6(_) => Domain::IPV6,
    };
    let socket = Socket::new(domain, Type::DGRAM, Some(socket2::Protocol::UDP))?;
    configure_shaping(&socket, family, shaping)?;
    socket.bind(&source_bind(family, shaping.source_port.unwrap_or(0)).into())?;
    socket.set_nonblocking(true)?;
    tokio::net::UdpSocket::from_std(std::net::UdpSocket::from(socket))
}

/// Probes a single [`Target`] for UDP using a standard OS `UdpSocket`, the
/// unprivileged counterpart of [`UdpPortScanner`](super::ports::UdpPortScanner).
///
/// UDP has no handshake to read a verdict from, so this leans on what the local
/// kernel reports about the datagram it sent. The socket is *connected*, which
/// is what makes that possible: a connected UDP socket has a known peer, so the
/// kernel can attribute an inbound ICMP error to it and surface it as
/// `ConnectionRefused` on a subsequent operation. An unconnected socket
/// discards the same error with nowhere to deliver it.
///
/// A reply is `Open`, a refusal is `Closed`, and silence is `OpenFiltered` -
/// the same three verdicts the raw scanner reaches, by a different route.
/// Errors that say nothing about the target (no local socket, no route) are
/// logged and yield no record rather than a guess.
async fn udp_port_prober(
    planned: PlannedTarget,
    shaping: ConnectShaping,
    socket_addr: SocketAddr,
) -> ProbedPort {
    let target = planned.target;
    if target.protocol != Protocol::Udp {
        return None;
    }

    let position = planned.position;
    // `answered` is set only where the kernel vouches for who sent the packet.
    // A datagram arriving on a connected socket came from the peer, so `Open`
    // proves the host. A refusal does not: it is an ICMP error the kernel
    // matched to this socket by the datagram it quotes, and the error's own
    // source address - a router's, or the target's - is not surfaced through
    // this API at all. The privileged scanner reads that address and can tell
    // the two apart; here the port verdict stands on its own and no claim is
    // made about the host.
    let record = |state, answered, outcome| {
        Some(Probed {
            ip: target.ip,
            port: Some(crate::fingerprint::baseline_port(
                target.port,
                Protocol::Udp,
                state,
            )),
            // Nothing on this path turns a datagram into the text a detection
            // reads: the reply is read for the role it declares and no more.
            responses: Vec::new(),
            about_the_host: crate::fingerprint::AboutTheHost::default(),
            answered,
            outcome,
            // Filled in by the one arm that has a reply to read it from.
            role: None,
        })
    };

    // Three ways this machine can fail before a datagram leaves it, below, and
    // each records the port unasked rather than dropping it. The target was
    // named by the plan, and a port that disappears from the host when the
    // scanner runs out of sockets is the shortfall a reader cannot see. The
    // outcome is `Unroutable` rather than `Unasked` for the reason the TCP
    // prober gives: this host gave up, which the next sitting may not.
    let socket = match shaped_udp_socket(target.ip, shaping).await {
        Ok(socket) => socket,
        Err(e) => {
            error!(
                verbosity = 2,
                "no UDP socket for probing {socket_addr}: {e}"
            );
            return record(PortState::Unasked, false, Outcome::Unroutable);
        }
    };

    if let Err(e) = socket.connect(socket_addr).await {
        error!(
            verbosity = 2,
            "cannot address UDP probe to {socket_addr}: {e}"
        );
        return record(PortState::Unasked, false, Outcome::Unroutable);
    }

    if let Err(e) = socket.send(payload::for_port(target.port)).await {
        // A refusal can surface here rather than on the receive: the kernel
        // reports a queued ICMP error on whichever operation comes next.
        return match e.kind() {
            ErrorKind::ConnectionRefused => {
                record(PortState::Closed, false, Outcome::Answered { position })
            }
            _ => {
                error!(
                    verbosity = 2,
                    "failed to send UDP probe to {socket_addr}: {e}"
                );
                record(PortState::Unasked, false, Outcome::Unroutable)
            }
        };
    }

    let mut buf = [0u8; 1024];
    match timeout(CONNECT_PROBE_TIMEOUT, socket.recv(&mut buf)).await {
        // Something answered, so something is listening, and what it said may
        // prove what the host is, which is a claim no port verdict can make.
        // Read here rather than left to the privileged path, so a scan without
        // root reaches the same conclusions about the network.
        Ok(Ok(read)) => {
            record(PortState::Open, true, Outcome::Answered { position }).map(|probed| Probed {
                role: payload::declared_role(target.port, &buf[..read]),
                ..probed
            })
        }
        // An ICMP Port Unreachable, surfaced against the connected peer.
        Ok(Err(e)) if e.kind() == ErrorKind::ConnectionRefused => {
            record(PortState::Closed, false, Outcome::Answered { position })
        }
        // Any other failure leaves the port as unknown as silence does.
        Ok(Err(e)) => {
            error!(
                verbosity = 2,
                "UDP probe to {socket_addr} failed after sending: {e}"
            );
            // A local read failure, not a fact about the target.
            record(PortState::OpenFiltered, false, Outcome::Unroutable)
        }
        // No error and no reply: open but silent, or filtered. UDP cannot tell.
        // Settled either way: this probe had one attempt and spent it.
        Err(_) => record(
            PortState::OpenFiltered,
            false,
            Outcome::Exhausted { position },
        ),
    }
}

/// Files what a finished sweep or scan measured.
///
/// Both halves of this strategy report the same way, so the audit line and the
/// recorded counters cannot drift between them.
fn finish(
    ctx: &ScanContext,
    audit: ProbeAudit,
    scanner: ScannerKind,
    probes: u128,
    reason: StopReason,
) {
    audit.report("connect", probes, reason, None, None);
    ctx.record_probe_stats(audit.stats(scanner, probes, reason, None, None));
}

/// Multi-port host discovery for unprivileged environments.
///
/// Sweeps the target networks by probing a small set of common infrastructure
/// ports: SSH (22), HTTP (80), HTTPS (443), SMB (445), and RDP (3389). Spreading
/// the probe across several ports catches hosts that only expose one of them,
/// which improves the odds of finding Linux, Windows, and embedded targets alike.
///
/// One task per address, not per port. Its ports are tried in turn and the
/// first TCP-layer answer ends the address, so a host that answers on SSH costs
/// one connect rather than five. A silent address costs all five, which is what
/// it took before as well: the same socket budget, spent on fewer addresses at a
/// time rather than on more ports of each.
///
/// That shape is also what lets a sweep be continued. An address is the unit a
/// journal counts, so its verdict has to be earned as a whole: answered, or
/// every port asked once and none of them answering. Interleaving the ports of
/// many addresses gave neither, because nothing knew when an address was
/// finished with.
///
/// Addresses are drawn from
/// [`dispatch_addresses`] to
/// spread load across the network instead of hammering one subnet at a time, and
/// each connect waits out the [`CONNECT_PROBE_TIMEOUT`] so that hosts on slow or
/// distant links still register.
pub async fn discover(
    ips: IpSet,
    ctx: ScanContext,
    evasion: &EvasionProfile,
) -> Result<(), StrategyError> {
    let shaping = ConnectShaping::from(evasion);
    // The same list `PortSet::common_discovery` names, taken from there rather
    // than spelled again here. Two copies of five port numbers is two copies to
    // keep in step, and nothing would have reported them drifting apart.
    let ports: Arc<[u16]> = PortSet::common_discovery()
        .iter()
        .map(|(port, _)| port)
        .collect::<Vec<_>>()
        .into();

    let mut rx = dispatch_addresses(ips, 1024, ctx.order_seed, &ctx.handle);
    let folder = ctx.clone();
    let mut pool = ProbePool::new(
        DISCOVERY_CONCURRENCY,
        ctx.clone(),
        ScannerKind::Connect,
        |probed, audit: &mut ProbeAudit| absorb_host(&folder, probed, audit),
    );

    let mut probes = 0u128;
    let mut reason = StopReason::AttemptsSpent;
    while let Some(ip) = rx.recv().await {
        if let Some(cause) = ctx.handle.stopped() {
            reason = cause.into();
            // Taken off the queue and never asked, so it counts with the rest
            // still waiting behind it.
            ctx.record_outcome(Outcome::Unasked);
            break;
        }
        probes += 1;
        pool.audit().record_send(true);
        pool.admit(prober(ip, Arc::clone(&ports), ctx.handle.clone(), shaping))
            .await;
    }

    // Anything still queued was never asked, and carries no position to settle.
    while rx.try_recv().is_ok() {
        ctx.record_outcome(Outcome::Unasked);
    }

    // Every address dispatched; wait out the probes still in flight.
    pool.drain().await;
    finish(
        &ctx,
        pool.into_audit(),
        ScannerKind::Connect,
        probes,
        reason,
    );
    Ok(())
}

/// What one address's liveness probe came to.
struct ProbedHost {
    /// The address asked about, which is the unit a sweep settles.
    ip: IpAddr,
    /// What became of it.
    fate: Fate,
}

/// The four things a sweep can honestly say about an address, before anything
/// knows where in the plan it sits.
///
/// Only the first two are verdicts the sweep earned. The others say the address
/// was not asked, or not finished with, and a resume must ask again. see
/// [`settle`](crate::journal::settle).
enum Fate {
    /// It answered, and this is what the answer proved.
    ///
    /// Boxed because a [`Host`] is by far the largest thing a fate can carry and
    /// four of the five variants carry nothing: unboxed, every probe that found
    /// silence would still move a host-sized value through the sweep.
    Answered(Box<Host>),
    /// Every port was asked once and not one of them answered. **Settled**: a
    /// connect gets one attempt per port and those were all of them.
    Exhausted,
    /// Nothing this probe sent left the host, no route, no socket left, so
    /// the address proved nothing and the next sitting may get further.
    Unroutable,
    /// The scan stopped while the address's ports were still being tried.
    Interrupted,
    /// The scan stopped before any of them were.
    Unasked,
}

/// Merges one finished discovery probe into the store, and settles the address
/// it asked about.
///
/// A freshly created entry starts from [`Host::new`] and absorbs the probe's
/// findings, so the recorded result is the same whether or not the host was seen
/// before.
///
/// The three cases are the three things a sweep can honestly say about an
/// address: it answered, it was asked as many times as it is going to be and
/// stayed silent, or it could not be asked from here at all. Only the first two
/// are settled. see [`settle`](crate::journal::settle).
fn absorb_host(ctx: &ScanContext, probed: ProbedHost, audit: &mut ProbeAudit) {
    match probed.fate {
        Fate::Answered(host) => {
            let ip = host.primary_ip();
            // See `absorb_probe`: this path has no attempt to attribute the
            // answer to, so every host it finds is counted as unattributed.
            audit.record_host_found(None);
            ctx.settle_address(probed.ip, Settled::Answered);
            ctx.update_host(ip, |existing| existing.merge(*host));
        }
        Fate::Exhausted => ctx.settle_address(probed.ip, Settled::Exhausted),
        Fate::Unroutable => ctx.record_outcome(Outcome::Unroutable),
        Fate::Interrupted => ctx.record_outcome(Outcome::Interrupted),
        Fate::Unasked => ctx.record_outcome(Outcome::Unasked),
    }
}

/// Probes one address for presence, over each of `ports` in turn.
///
/// Returns as soon as one of them answers at the TCP layer: a completed
/// handshake, or a reset the kernel surfaced as a connection error. Any other
/// failure says nothing about the address, only that this connect did not
/// finish, so the next port is tried.
///
/// The stop signal is checked between ports, not only between addresses.
/// One task now covers up to five connects, and a sweep that only looked once
/// per address would take five timeouts to wind down rather than one. What has
/// been asked so far decides how the address is filed: cut off part way through
/// is not the same as asked and silent, and only the second is a verdict.
async fn prober(
    ip: IpAddr,
    ports: Arc<[u16]>,
    handle: ScanHandle,
    shaping: ConnectShaping,
) -> ProbedHost {
    let start = Instant::now();
    let mut asked = false;

    for &port in ports.iter() {
        if handle.should_stop() {
            return ProbedHost {
                ip,
                fate: if asked {
                    Fate::Interrupted
                } else {
                    Fate::Unasked
                },
            };
        }

        let attempt = timeout(
            CONNECT_PROBE_TIMEOUT,
            connect_shaped(SocketAddr::new(ip, port), shaping),
        )
        .await;

        match attempt {
            // A completed handshake means the host is alive.
            Ok(Ok(_)) => return answered(ip, start),
            // Only these TCP errors imply the host answered at the IP/TCP layer.
            // Any other is a local failure, no route, permission denied, and
            // the probe never reached the wire.
            Ok(Err(e))
                if matches!(
                    e.kind(),
                    ErrorKind::ConnectionRefused
                        | ErrorKind::ConnectionReset
                        | ErrorKind::ConnectionAborted
                ) =>
            {
                return answered(ip, start);
            }
            Ok(Err(_)) => {}
            // A timeout is the probe going out and nothing coming back, which is
            // the address being asked and declining to answer.
            Err(_elapsed) => asked = true,
        }
    }

    ProbedHost {
        ip,
        fate: if asked {
            Fate::Exhausted
        } else {
            Fate::Unroutable
        },
    }
}

/// The record an address earns by answering.
fn answered(ip: IpAddr, start: Instant) -> ProbedHost {
    let mut host = Host::new(ip);
    host.add_rtt_from(start.elapsed(), StatusProtocol::TcpSyn);
    // Every outcome that reaches here required a segment from the target: a
    // completed handshake, or a reset the kernel surfaced as a connection error.
    // `Host::merge` keeps the stronger status, so this survives being folded
    // into an entry another strategy created first.
    host.record_evidence(
        HostStatus::Up,
        StatusReason::new(StatusProtocol::TcpSyn, "tcp connect answered by the host"),
    );

    ProbedHost {
        ip,
        fate: Fate::Answered(Box::new(host)),
    }
}

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

#[cfg(test)]
mod tests {
    use super::*;
    use crate::model::target::Target;
    use tokio::net::UdpSocket;

    fn udp_target(ip: IpAddr, port: u16) -> PlannedTarget {
        PlannedTarget::new(
            u64::from(port),
            Target {
                ip,
                port,
                protocol: Protocol::Udp,
            },
        )
    }

    /// Reserves a loopback UDP port and releases it, yielding a number nothing
    /// is listening on - so the kernel answers a probe with an ICMP error.
    async fn closed_loopback_udp_port(ip: IpAddr) -> u16 {
        let socket = UdpSocket::bind((ip, 0)).await.expect("bind to reserve");
        let port = socket.local_addr().expect("reserved addr").port();
        drop(socket);
        port
    }

    #[test]
    fn probe_socket_binds_the_target_family() {
        assert!(wildcard_for(IpAddr::V4(Ipv4Addr::LOCALHOST)).is_ipv4());
        assert!(wildcard_for(IpAddr::V6(Ipv6Addr::LOCALHOST)).is_ipv6());
    }

    /// The regression guard for the IPv4-only bind: a v6 target used to fail at
    /// `connect` and vanish without a record or a log. Loopback only, and no
    /// privileges required, so this runs everywhere the suite does.
    #[tokio::test]
    async fn closed_ipv6_port_is_classified_not_dropped() {
        let ip = IpAddr::V6(Ipv6Addr::LOCALHOST);
        let port = closed_loopback_udp_port(ip).await;

        let probed = udp_port_prober(
            udp_target(ip, port),
            ConnectShaping::default(),
            SocketAddr::new(ip, port),
        )
        .await;

        let probed = probed.expect("an IPv6 target must produce a verdict");
        let probed_port = probed.port.expect("a closed port is still a verdict");
        assert_eq!(probed.ip, ip);
        assert_eq!(probed_port.number(), port);
        assert_eq!(probed_port.state(), PortState::Closed);
    }

    #[tokio::test]
    async fn closed_ipv4_port_is_closed() {
        let ip = IpAddr::V4(Ipv4Addr::LOCALHOST);
        let port = closed_loopback_udp_port(ip).await;

        let probed = udp_port_prober(
            udp_target(ip, port),
            ConnectShaping::default(),
            SocketAddr::new(ip, port),
        )
        .await;

        assert_eq!(
            probed
                .and_then(|probed| probed.port)
                .expect("a verdict")
                .state(),
            PortState::Closed
        );
    }

    /// A listener that answers is `Open` over either family.
    #[tokio::test]
    async fn a_listener_that_answers_is_open() {
        for ip in [
            IpAddr::V4(Ipv4Addr::LOCALHOST),
            IpAddr::V6(Ipv6Addr::LOCALHOST),
        ] {
            let service = UdpSocket::bind((ip, 0)).await.expect("bind service");
            let port = service.local_addr().unwrap().port();
            tokio::spawn(async move {
                let mut buf = [0u8; 64];
                if let Ok((_, from)) = service.recv_from(&mut buf).await {
                    let _ = service.send_to(b"pong", from).await;
                }
            });

            let probed = udp_port_prober(
                udp_target(ip, port),
                ConnectShaping::default(),
                SocketAddr::new(ip, port),
            )
            .await;

            assert_eq!(
                probed
                    .and_then(|probed| probed.port)
                    .expect("a verdict")
                    .state(),
                PortState::Open,
                "a live {ip} listener must read as open"
            );
        }
    }

    /// TCP targets belong to the connect scanner next door; this prober must
    /// leave them alone rather than misreport them over the wrong protocol.
    #[tokio::test]
    async fn tcp_targets_are_skipped() {
        let target = PlannedTarget::new(
            0,
            Target {
                ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
                port: 80,
                protocol: Protocol::Tcp,
            },
        );
        assert!(
            udp_port_prober(
                target,
                ConnectShaping::default(),
                SocketAddr::new(target.ip(), target.port()),
            )
            .await
            .is_none()
        );
    }

    /// The two fields a connect can carry cross over from the profile, and a
    /// default profile stays inert so the scanner takes its plain path.
    ///
    /// The guard is the mapping itself: a version that dropped either field, or
    /// reported an inert profile as active, would send the wrong packet while
    /// every higher-level test still passed.
    #[test]
    fn the_profile_maps_onto_what_a_connect_can_carry() {
        let profile = EvasionProfile {
            source_port: Some(53),
            ttl: Some(12),
            ..Default::default()
        };
        let shaping = ConnectShaping::from(&profile);

        assert_eq!(shaping.source_port, Some(53));
        assert_eq!(shaping.hop_limit, Some(12));
        assert!(shaping.is_active());
        assert!(!ConnectShaping::from(&EvasionProfile::default()).is_active());
    }

    /// A shaped connect leaves from the chosen source port and carries the chosen
    /// hop limit: proven where it counts, on the wire, against a peer that reads
    /// both back.
    ///
    /// The peer's view of the source port is the whole chain end to end: profile
    /// to [`ConnectShaping`] to the bind. A version that ignored the source port
    /// would show an ephemeral one here; one that skipped the hop limit would
    /// show the OS default, not `9`.
    #[tokio::test]
    async fn a_shaped_connect_pins_its_source_port_and_hop_limit() {
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
            .await
            .expect("a loopback listener");
        let addr = listener.local_addr().expect("its address");

        const PINNED: u16 = 40_517;
        const HOPS: u8 = 9;
        let shaping = ConnectShaping {
            source_port: Some(PINNED),
            hop_limit: Some(HOPS),
        };

        let accept = tokio::spawn(async move { listener.accept().await });
        let stream = connect_shaped(addr, shaping)
            .await
            .expect("the shaped connect completes");
        let (_accepted, peer) = accept
            .await
            .expect("the accept task joins")
            .expect("an accept");

        assert_eq!(
            peer.port(),
            PINNED,
            "the SYN left from the pinned source port"
        );
        assert_eq!(
            stream.ttl().expect("the socket's hop limit"),
            u32::from(HOPS),
            "the SYN carried the chosen hop limit"
        );
    }

    /// A shaped UDP probe leaves from the chosen source port, read back off the
    /// datagram the far side receives.
    ///
    /// The UDP socket is built by its own path, so it earns its own guard: one
    /// that bound an ephemeral port instead of the pinned one would show a
    /// different source port to the receiver.
    #[tokio::test]
    async fn a_shaped_udp_probe_pins_its_source_port() {
        let server = UdpSocket::bind("127.0.0.1:0")
            .await
            .expect("a loopback server");
        let server_addr = server.local_addr().expect("its address");

        const PINNED: u16 = 40_619;
        let shaping = ConnectShaping {
            source_port: Some(PINNED),
            hop_limit: None,
        };
        let socket = shaped_udp_socket(IpAddr::V4(Ipv4Addr::LOCALHOST), shaping)
            .await
            .expect("a shaped UDP socket");
        socket
            .connect(server_addr)
            .await
            .expect("addressing the peer");
        socket.send(b"probe").await.expect("sending the probe");

        let mut buf = [0u8; 8];
        let (_read, from) = server
            .recv_from(&mut buf)
            .await
            .expect("the datagram arrives");
        assert_eq!(
            from.port(),
            PINNED,
            "the datagram left from the pinned source port"
        );
    }
}