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
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
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
// 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 a scan is asked to do
//!
//! [`ZondConfig`] is the whole of it: one value, built once, handed to
//! [`scan`](crate::scanner::scan) or [`discover`](crate::scanner::discover), and
//! read by every strategy the run assembles. A caller that changes nothing gets
//! the default, which is a scan that sends what it must and no more.
//!
//! ## Effort levels, not timing numbers
//!
//! Most of what a person wants to say about a scan is how hard it should try,
//! and the levels here are the vocabulary for that. [`ScanEffort`] sets how many
//! attempts a probe gets and how long each one waits. [`OsDetection`] and
//! [`ServiceDetection`] set how far a run may go to name what it found.
//!
//! All three are one vocabulary and are built alike: an ordered scale, an `ALL`
//! in that order, a `name` and a `level` for each rung, and a `FromStr` that
//! takes either spelling so a front end can accept a word from a settings file
//! and a number from a flag without keeping a table of its own. Each is carried
//! into the report, so a result says what was asked of it.
//!
//! Where the default sits is each scale's own decision rather than a rule.
//! [`ScanEffort`] and [`OsDetection`] default low, since effort and traffic are
//! what a caller should have to ask for. [`ServiceDetection`] defaults to its
//! *top* level, because there its highest level is also its fastest against an
//! unrecognised port; the reasoning is at the variant.
//!
//! Below those sit the numbers a strategy actually paces by, and they are not
//! here to be set. A raw scanner measures its own round trips and sizes its
//! patience from them; the connect paths, which cannot measure anything, run
//! against the shared constants in [`limits`]. What a caller supplies is a
//! ceiling and a preference, and the engine decides the rest against the network
//! in front of it.
//!
//! ## Two things that are not effort
//!
//! [`EvasionProfile`] changes the shape of what goes on the wire rather than how
//! much of it does, and it is inert by default: a strategy handed a default
//! profile sends exactly what it would have sent without one.
//!
//! [`DetectionEnvelope`] is a permission rather than a setting. A detection
//! declares how intrusive it is and runs only where the envelope allows that
//! class, so raising it is an operator's decision and not a tuning knob. See
//! [`envelope`] for the ordering.
//!
//! ## Nothing about output
//!
//! No verbosity, no colour, no format. The engine emits `tracing` events and
//! installs no subscriber, so what a run looks like belongs entirely to whoever
//! embeds the crate. The boundary earns its keep because this type is also the
//! record of how a scan was run: [`ScanSettings`](crate::report::ScanSettings)
//! is derived from it into every report, and a field that cannot change a
//! finding has no business in the record of one.

pub mod envelope;
pub mod limits;

pub use crate::config::envelope::DetectionEnvelope;

use std::collections::BTreeSet;
use std::fmt;
use std::net::IpAddr;
use std::num::{NonZeroU8, NonZeroU32};
use std::str::FromStr;
use std::time::Duration;

use crate::evasion::EvasionProfile;
use crate::model::exclusion::Exclusions;
use crate::model::technique::{SctpScanTechnique, TcpScanTechnique};
use crate::transport::probe::SendMode;

/// Reads a level written as its name or as its number.
///
/// The three scales in this module are one vocabulary and are parsed one way.
/// Written out per type, the three drifted: two accepted a number and one did
/// not, while the module documentation promised all three did, and the three
/// bodies compared names by three different means.
///
/// Both spellings are accepted because both are how these are written in
/// practice: a settings file says `passive`, and a command line says `2`.
/// Splitting them across two entry points would put the correspondence between
/// the word and the number in whoever called this, and two front ends would
/// eventually disagree about it.
fn parse_level<T: Copy>(
    written: &str,
    all: &[T],
    name: fn(T) -> &'static str,
    from_level: fn(u8) -> Option<T>,
) -> Option<T> {
    let written = written.trim();

    if let Ok(level) = written.parse::<u8>() {
        return from_level(level);
    }

    all.iter()
        .copied()
        .find(|level| name(*level).eq_ignore_ascii_case(written))
}

/// The `expected one of` half of every parse error in this module, built from
/// the levels themselves.
///
/// The three messages used to spell their own lists. A variant added to an enum
/// and to its `ALL` left the message naming the levels that existed when it was
/// written, and nothing here would have said so: both spellings still parse, and
/// only the sentence a caller reads is wrong.
fn expected_levels<T: Copy>(
    all: &[T],
    name: fn(T) -> &'static str,
    f: &mut fmt::Formatter<'_>,
) -> fmt::Result {
    let names: Vec<&str> = all.iter().copied().map(name).collect();
    let highest = all.len().saturating_sub(1);
    write!(
        f,
        "expected one of: {} (or 0 to {highest})",
        names.join(", ")
    )
}

/// How much effort a scan spends before accepting silence as an answer.
///
/// Every probing path has its own tuned
/// [`RetryPolicy`](crate::scanner::pacing::retry::RetryPolicy), set against what its
/// protocol actually requires - a SYN is answered as fast as the path allows, an
/// ICMP error only as fast as the host is permitted to send one. This scales
/// that starting point rather than replacing it, so choosing "fast" does not
/// quietly hand the UDP scanner a schedule its protocol cannot satisfy.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum ScanEffort {
    /// One probe per target and no repeats.
    ///
    /// A first-class choice rather than a disabled feature: it is what an
    /// address-space-scale sweep wants, where per-probe state cannot be afforded
    /// and coverage is bought with a second pass instead.
    Single,
    /// Fewer attempts and less patience. For a network already known to be
    /// healthy, where a missed host is cheaper than the time spent confirming
    /// one is absent.
    Fast,
    /// The level a scan runs at when nobody chose one. Enough attempts to
    /// ride out ordinary loss, and enough patience for a host on the far side
    /// of a slow link.
    #[default]
    Balanced,
    /// More attempts, more patience, and no shortcuts on hosts that stay
    /// silent. For a lossy path, or a result someone is going to act on.
    Thorough,
}

impl ScanEffort {
    /// Every level, ordered from least effort to most. The index of a level in
    /// this array is its [`level`](Self::level) number.
    pub const ALL: [ScanEffort; 4] = [
        ScanEffort::Single,
        ScanEffort::Fast,
        ScanEffort::Balanced,
        ScanEffort::Thorough,
    ];

    /// The name this level is written under, wherever it arrives as text.
    pub const fn name(self) -> &'static str {
        match self {
            ScanEffort::Single => "single",
            ScanEffort::Fast => "fast",
            ScanEffort::Balanced => "balanced",
            ScanEffort::Thorough => "thorough",
        }
    }

    /// The number this level is written as, for a front end that offers it as a
    /// dial rather than a word.
    ///
    /// # Examples
    ///
    /// ```
    /// use zond_engine::config::ScanEffort;
    ///
    /// assert_eq!(ScanEffort::default().level(), 2);
    /// ```
    pub const fn level(self) -> u8 {
        match self {
            ScanEffort::Single => 0,
            ScanEffort::Fast => 1,
            ScanEffort::Balanced => 2,
            ScanEffort::Thorough => 3,
        }
    }

    /// The level with this number, or `None` past the highest there is.
    ///
    /// Deliberately not saturating, on the reasoning
    /// [`OsDetection::from_level`] gives.
    pub const fn from_level(level: u8) -> Option<Self> {
        match level {
            0 => Some(ScanEffort::Single),
            1 => Some(ScanEffort::Fast),
            2 => Some(ScanEffort::Balanced),
            3 => Some(ScanEffort::Thorough),
            _ => None,
        }
    }
}

impl std::fmt::Display for ScanEffort {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.name())
    }
}

/// The error parsing a [`ScanEffort`] returns, carrying the names that would
/// have worked so a front end can print it verbatim.
///
/// The list is built from [`ScanEffort::ALL`] rather than spelled here, so a
/// level added to the enum is a level this message names.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UnknownScanEffort {
    /// What the caller wrote.
    pub input: String,
}

impl fmt::Display for UnknownScanEffort {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "unknown scan effort '{}', ", self.input)?;
        expected_levels(&ScanEffort::ALL, ScanEffort::name, f)
    }
}

impl std::error::Error for UnknownScanEffort {}

impl std::str::FromStr for ScanEffort {
    type Err = UnknownScanEffort;

    /// Parses an effort name, ignoring case and surrounding whitespace, so a
    /// choice arriving as text - from an argument, a form field, a settings
    /// file - needs no mapping table of its own.
    ///
    /// # Examples
    ///
    /// ```
    /// use zond_engine::config::ScanEffort;
    ///
    /// assert_eq!("Thorough".parse(), Ok(ScanEffort::Thorough));
    /// assert!("maximum".parse::<ScanEffort>().is_err());
    /// ```
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        parse_level(s, &Self::ALL, Self::name, Self::from_level).ok_or_else(|| UnknownScanEffort {
            input: s.to_string(),
        })
    }
}

/// How far a scan goes to identify the operating system behind a host.
///
/// Four levels, ordered by what they put on the wire. The ordering is the point:
/// each level is a superset of the one below it, so raising the level only ever
/// adds evidence and never trades one technique for another. That is what makes
/// [`is_active`](Self::is_active), asking whether a level may send packets of its
/// own, a question with a single answer, and what lets a front end offer this as
/// a dial rather than a menu.
///
/// # Why the default is on
///
/// [`Passive`](Self::Passive) sends **nothing at all**. Every signal it reads is
/// already in a reply the scan drew for another reason: the hop count, the
/// fragmentation policy and the identifier in an IP header the capture used to
/// arrive at, and the window and options of a segment the port scanner was
/// waiting for anyway. A scan with it on and a scan with it off emit
/// byte-identical traffic and take the same time, so there is nothing for a
/// caller to weigh, and defaulting it off would mean a finding thrown away for
/// no consideration.
///
/// [`Off`](Self::Off) exists all the same, for the caller who wants a report to
/// contain only what was asked for, and for reproducing a run that predates any
/// of this.
///
/// # Why the higher levels are not
///
/// From [`Active`](Self::Active) upward this costs packets. Not, today, unusual
/// ones: what it sends is a SYN and a ping, and the SYN is byte-for-byte the
/// segment a port scan already sends. What it is, is extra. A host is asked
/// several more times than classifying its ports required, and it is asked at
/// addresses a caller may only have meant to enumerate. Traffic sent for a
/// second purpose has to be asked for even when its shape gives nothing away,
/// which is the whole reason this is a dial and not a default.
///
/// It also becomes true in the older sense as the tiers fill in.
/// [`Aggressive`](Self::Aggressive) is where a deliberately malformed probe
/// would live, traffic identified by how a stack mishandles it and so by
/// construction what an intrusion-detection system was written to notice. None
/// is sent yet; the level is documented for what it does rather than for what it
/// is named after.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum OsDetection {
    /// Level 0. Identify nothing, and record nothing about the stacks that
    /// answered.
    Off,

    /// Level 1, and the default. Read the operating system out of replies the
    /// scan already drew, and send nothing extra.
    ///
    /// Answers at the level of a family, meaning the shape of a stack rather than
    /// its version, and only for hosts that replied to something. A host that
    /// answered no probe at all leaves nothing to read.
    #[default]
    Passive,

    /// Level 2. Everything [`Passive`](Self::Passive) reads, plus probes of this
    /// engine's own aimed at the hosts whose replies were not enough.
    ///
    /// Ordinary, well-formed packets. Nothing here is malformed, and nothing
    /// carries a flag combination a real connection does not. Two probes:
    ///
    /// - **A series of SYNs**, to a host with an open or closed TCP port. The
    ///   same segment a SYN scan sends, repeated from a fresh source port each
    ///   time, because whether a stack's IP identifier counts or is random,
    ///   whether its sequence numbers are hashed or stepped, and how fast its
    ///   timestamp clock ticks are policies, visible across several replies and
    ///   in no single one. These are the features a release-level rule turns on.
    /// - **One SNMP request**, to a host whose kernel is still unknown. On a Unix
    ///   host `sysDescr` is the output of `uname -a`, so an agent that answers
    ///   states the exact kernel, the one thing no amount of packet analysis can
    ///   establish and what a known-vulnerability lookup keys on. Sent with
    ///   the default `public` community, read-only, for one object.
    /// - **One ICMP echo**, to a host that answered no TCP probe at all. A stock
    ///   Windows firewall drops rather than refuses, so a desktop with nothing
    ///   exposed emits no segment any TCP rule could read; a ping is the one
    ///   packet it still answers.
    ///
    /// None of them touches the port list. A detection level says how hard to
    /// look at a host, not which ports to scan, and a level that quietly widened
    /// `--ports` would send probes at a port the caller excluded.
    ///
    /// The traffic is unremarkable in shape but it is extra, and it is addressed
    /// at hosts the caller may only have meant to enumerate. It is spent where
    /// the passive evidence was thin rather than on everything.
    Active,

    /// Level 3. The same probes [`Active`](Self::Active) sends, more of them,
    /// and at every host rather than only the unsettled ones.
    ///
    /// Twice the samples per host, and hosts already named with high confidence
    /// are followed too. That is what somebody measuring wants, since a reading
    /// from a machine whose operating system they already know is how a rule gets
    /// authored, and it is more traffic, sustained longer, at more
    /// addresses, which is why it is a level of its own.
    ///
    /// # What this level does not yet do
    ///
    /// It sends no deliberately malformed probe. Reserved fields set, flag
    /// combinations no connection produces, and headers that disagree with their
    /// own lengths separate stacks that agree on everything legal, and they are
    /// the obvious next tier. They are not here because this engine authors
    /// rules from what it has measured through its own probes, and nothing has
    /// yet measured those. When they arrive they arrive at this level; until
    /// then this is the honest description of it rather than a promise.
    Aggressive,
}

impl OsDetection {
    /// Every level, ordered from least effort to most. The index of a level in
    /// this array is its [`level`](Self::level) number.
    pub const ALL: [OsDetection; 4] = [
        OsDetection::Off,
        OsDetection::Passive,
        OsDetection::Active,
        OsDetection::Aggressive,
    ];

    /// The name this level is written under, wherever it arrives as text.
    pub const fn name(self) -> &'static str {
        match self {
            OsDetection::Off => "off",
            OsDetection::Passive => "passive",
            OsDetection::Active => "active",
            OsDetection::Aggressive => "aggressive",
        }
    }

    /// The number this level is written as, for a front end that offers it as a
    /// dial rather than a word.
    ///
    /// # Examples
    ///
    /// ```
    /// use zond_engine::config::OsDetection;
    ///
    /// assert_eq!(OsDetection::default().level(), 1);
    /// ```
    pub const fn level(self) -> u8 {
        match self {
            OsDetection::Off => 0,
            OsDetection::Passive => 1,
            OsDetection::Active => 2,
            OsDetection::Aggressive => 3,
        }
    }

    /// The level with this number, or `None` past the highest there is.
    ///
    /// Not saturating. A caller who writes `9` meaning as much as possible has
    /// written something this engine does not offer, and giving them the top
    /// level would hide that, which is the reasoning that makes
    /// [`from_str`](Self::from_str) refuse a name it does not know rather than
    /// fall back to the default.
    pub const fn from_level(level: u8) -> Option<Self> {
        match level {
            0 => Some(OsDetection::Off),
            1 => Some(OsDetection::Passive),
            2 => Some(OsDetection::Active),
            3 => Some(OsDetection::Aggressive),
            _ => None,
        }
    }

    /// Whether identification happens at all.
    pub const fn is_enabled(self) -> bool {
        !matches!(self, OsDetection::Off)
    }

    /// Whether this level may put probes of its own on the wire.
    ///
    /// The question every caller with a reason to care is actually asking. A
    /// scan that must add no traffic of its own, and a report that has to say
    /// whether it did, both turn on this and not on which level was chosen.
    ///
    /// # Examples
    ///
    /// ```
    /// use zond_engine::config::OsDetection;
    ///
    /// assert!(!OsDetection::Passive.is_active(), "the default sends nothing");
    /// assert!(OsDetection::Aggressive.is_active());
    /// ```
    pub const fn is_active(self) -> bool {
        matches!(self, OsDetection::Active | OsDetection::Aggressive)
    }
}

impl fmt::Display for OsDetection {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.name())
    }
}

/// The error parsing an [`OsDetection`] returns, carrying the values that would
/// have worked so a front end can print it verbatim.
///
/// The list is built from [`OsDetection::ALL`] rather than spelled here, so a
/// level added to the enum is a level this message names.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UnknownOsDetection {
    /// What the caller wrote.
    pub input: String,
}

impl fmt::Display for UnknownOsDetection {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "unknown OS detection level '{}', ", self.input)?;
        expected_levels(&OsDetection::ALL, OsDetection::name, f)
    }
}

impl std::error::Error for UnknownOsDetection {}

impl FromStr for OsDetection {
    type Err = UnknownOsDetection;

    /// Parses a level by name or by number, ignoring case and surrounding
    /// whitespace, so a choice arriving as text - from an argument, a form
    /// field, a settings file - needs no mapping table of its own.
    ///
    /// Both spellings are accepted because both are how this is written in
    /// practice: a settings file says `passive`, and a command line says `2`.
    /// Splitting them across two entry points would put the correspondence
    /// between the word and the number in whoever called this, and two front ends
    /// would eventually disagree about it.
    ///
    /// # Examples
    ///
    /// ```
    /// use zond_engine::config::OsDetection;
    ///
    /// assert_eq!("Aggressive".parse(), Ok(OsDetection::Aggressive));
    /// assert_eq!("0".parse(), Ok(OsDetection::Off));
    /// assert!("maximum".parse::<OsDetection>().is_err());
    /// ```
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        parse_level(s, &Self::ALL, Self::name, Self::from_level).ok_or_else(|| UnknownOsDetection {
            input: s.to_string(),
        })
    }
}

/// How far a scan may go to identify what is listening behind an open port.
///
/// The port-scan phase establishes that a port is *open*; naming what is on it
/// is a second pass, and unlike the first it needs a real connection. That is
/// the cost this dial governs. It is worth governing separately because the two
/// have different audiences: a scan mapping what exists wants the ports, and a
/// scan auditing what is deployed wants the names, and the second costs a
/// conversation with every open port.
///
/// Ordered by what each level puts on the wire, so a caller can compare two
/// levels and a report can record which was asked for.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum ServiceDetection {
    /// Level 0. Do not connect. A port keeps whatever its number implies and
    /// nothing more.
    ///
    /// The fastest and the quietest: after a raw scan, no connection is ever
    /// completed, so nothing appears in the target's logs and nothing is read
    /// from any service. What it costs is every version and every product: a port
    /// reported `open http` on the strength of being port 80, which may be
    /// anything at all.
    Off,
    /// Level 1. Connect and listen. Send nothing.
    ///
    /// For services that greet on connect, such as SSH, SMTP, FTP and IRC, this
    /// is the whole of what a probe would have learned anyway, obtained without
    /// putting a single byte on the wire. For everything else it
    /// establishes only that the port accepts connections.
    ///
    /// The level to reach for against equipment that must not be sent anything
    /// unexpected. Industrial controllers, medical devices and old embedded
    /// stacks have all been knocked over by a well-formed request they did not
    /// anticipate, and on those networks the right amount to send is nothing.
    Banner,
    /// Level 2, and the default. Connect, listen, and ask.
    ///
    /// Sends each port the probes its service registered and, where nothing
    /// registers the port, the one generic request worth asking of anything.
    /// That last part is what identifies the long tail: an open port on a number
    /// nobody registered is most often an HTTP server, and one request names it.
    ///
    /// The default, because it is both the most informative level and, against
    /// an unrecognised port, the *fastest*. The alternative to asking is waiting
    /// for a greeting that never comes and then guessing at TLS, which costs two
    /// seconds per port to learn nothing. A scan that asks gets an answer in a
    /// round trip.
    #[default]
    Probe,
    /// Level 3. Everything above, and then every question the corpus has.
    ///
    /// A port that walked the whole collection and still said nothing gets the
    /// probes authored for *other* services, in rarity order. That is what
    /// reaches a service which speaks only when spoken to and is not on the
    /// port its own probe is registered against.
    ///
    /// Paid only where everything else drew a blank, which on an ordinary host
    /// is a port or two, and costing a connection and a round trip per probe.
    Thorough,
}

impl ServiceDetection {
    /// Every level, ordered from least effort to most. The index of a level in
    /// this array is its [`level`](Self::level) number.
    pub const ALL: [ServiceDetection; 4] = [
        ServiceDetection::Off,
        ServiceDetection::Banner,
        ServiceDetection::Probe,
        ServiceDetection::Thorough,
    ];

    /// The name this level is written under, wherever it arrives as text.
    pub const fn name(self) -> &'static str {
        match self {
            ServiceDetection::Off => "off",
            ServiceDetection::Banner => "banner",
            ServiceDetection::Probe => "probe",
            ServiceDetection::Thorough => "thorough",
        }
    }

    /// The number this level is written as, for a front end that offers it as a
    /// dial rather than a word.
    pub const fn level(self) -> u8 {
        match self {
            ServiceDetection::Off => 0,
            ServiceDetection::Banner => 1,
            ServiceDetection::Probe => 2,
            ServiceDetection::Thorough => 3,
        }
    }

    /// The level with this number, or `None` past the highest there is.
    pub const fn from_level(level: u8) -> Option<Self> {
        match level {
            0 => Some(ServiceDetection::Off),
            1 => Some(ServiceDetection::Banner),
            2 => Some(ServiceDetection::Probe),
            3 => Some(ServiceDetection::Thorough),
            _ => None,
        }
    }

    /// Whether this level opens a connection at all.
    ///
    /// The boundary that matters to a target: below it the scan is invisible to
    /// every application log on the host, and at or above it every open port
    /// records a connection.
    ///
    /// ```
    /// use zond_engine::config::ServiceDetection;
    ///
    /// assert!(!ServiceDetection::Off.connects());
    /// assert!(ServiceDetection::default().connects());
    /// ```
    pub const fn connects(self) -> bool {
        !matches!(self, ServiceDetection::Off)
    }

    /// Whether this level sends anything once connected.
    ///
    /// ```
    /// use zond_engine::config::ServiceDetection;
    ///
    /// assert!(!ServiceDetection::Banner.sends());
    /// assert!(ServiceDetection::Probe.sends());
    /// ```
    pub const fn sends(self) -> bool {
        matches!(self, ServiceDetection::Probe | ServiceDetection::Thorough)
    }

    /// How far up the corpus's rarity scale this level reaches, for a probe
    /// nothing registered against the port being asked.
    ///
    /// The scale runs 1 to 9 and is the one the imported corpora are authored
    /// on; see [`Probe::rarity`](crate::fingerprint::Probe::rarity). Zero
    /// reaches nothing, which is what every level below [`Probe`] wants.
    ///
    /// The default stops at 1 because only the bottom of the scale is authored
    /// so far. It is a floor to raise as the corpus fills in, not a judgement
    /// that rarity 2 is too expensive.
    ///
    /// ```
    /// use zond_engine::config::ServiceDetection;
    ///
    /// assert_eq!(ServiceDetection::Banner.probe_intensity(), 0);
    /// assert_eq!(ServiceDetection::Thorough.probe_intensity(), 9);
    /// ```
    ///
    /// [`Probe`]: Self::Probe
    pub const fn probe_intensity(self) -> u8 {
        match self {
            ServiceDetection::Off | ServiceDetection::Banner => 0,
            ServiceDetection::Probe => 1,
            ServiceDetection::Thorough => 9,
        }
    }
}

impl fmt::Display for ServiceDetection {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.name())
    }
}

/// The error parsing a [`ServiceDetection`] returns, carrying the values that
/// would have worked so a front end can print it verbatim.
///
/// The list is built from [`ServiceDetection::ALL`] rather than spelled here, so
/// a level added to the enum is a level this message names.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UnknownServiceDetection {
    /// What the caller wrote.
    pub input: String,
}

impl fmt::Display for UnknownServiceDetection {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "unknown service detection level '{}', ", self.input)?;
        expected_levels(&ServiceDetection::ALL, ServiceDetection::name, f)
    }
}

impl std::error::Error for UnknownServiceDetection {}

impl FromStr for ServiceDetection {
    type Err = UnknownServiceDetection;

    /// Parses a level by name or by number, on the same terms
    /// [`OsDetection`] does and for the same reason.
    ///
    /// ```
    /// use zond_engine::config::ServiceDetection;
    ///
    /// assert_eq!("banner".parse(), Ok(ServiceDetection::Banner));
    /// assert_eq!("0".parse(), Ok(ServiceDetection::Off));
    /// assert_eq!("3".parse(), Ok(ServiceDetection::Thorough));
    /// assert!("exhaustive".parse::<ServiceDetection>().is_err());
    /// ```
    fn from_str(input: &str) -> Result<Self, Self::Err> {
        parse_level(input, &Self::ALL, Self::name, Self::from_level).ok_or_else(|| {
            UnknownServiceDetection {
                input: input.to_string(),
            }
        })
    }
}

/// A multiplier on how long a scan is willing to wait.
///
/// Positive and finite, and a type rather than an `f64` because the values that
/// are neither cannot be honoured. A scale of zero asks for no patience at all,
/// a negative one asks for less than none, and a NaN compares false against
/// every bound a policy has. Each used to be accepted here, discarded without a
/// word where the policy is built, and then written into the report as though it
/// had applied.
///
/// That last part is what makes this a type. [`ZondConfig`] is the record of how
/// a scan was run as well as the instruction for running it, and a field that
/// could not change a finding has no business in the record of one.
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
pub struct TimeoutScale(f64);

impl TimeoutScale {
    /// The scale `factor` names, or `None` if no schedule could be built from
    /// it: zero, negative, infinite, or NaN.
    ///
    /// # Examples
    ///
    /// ```
    /// use zond_engine::config::TimeoutScale;
    ///
    /// assert!(TimeoutScale::new(2.5).is_some());
    /// assert!(TimeoutScale::new(0.0).is_none());
    /// assert!(TimeoutScale::new(f64::NAN).is_none());
    /// ```
    pub fn new(factor: f64) -> Option<Self> {
        (factor.is_finite() && factor > 0.0).then_some(Self(factor))
    }

    /// The multiplier, as the number a duration is scaled by.
    pub const fn get(self) -> f64 {
        self.0
    }
}

impl fmt::Display for TimeoutScale {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

/// User control over retransmission, applied on top of each scanner's own
/// profile.
///
/// Comparable so a report can state whether two runs were asked for the same
/// effort. Not [`Eq`]: `timeout_scale` is a float, and a scale nobody can write
/// down exactly is not a scale two runs should be claimed to share.
///
/// Non-exhaustive and [`Default`]-constructed. Every override here is optional
/// and every one of them is a *narrower* type than the field it sets, so a value
/// that reaches this struct is one the engine can honour; see
/// [`TimeoutScale`] for why that matters to the report as much as to the scan.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct RetryConfig {
    /// How hard the scan tries before the fields below override any part of it.
    pub effort: ScanEffort,
    /// Replaces the attempt budget outright, whatever `effort` implies. One
    /// attempt disables retransmission.
    ///
    /// Non-zero because a probe that is never sent is not a scan setting. Zero
    /// used to be accepted here and raised to one where the policy is built.
    pub max_attempts: Option<NonZeroU8>,
    /// Multiplies how long the scan is willing to wait.
    ///
    /// Deliberately does not touch the shortest timeout a policy allows. That
    /// floor is not a preference to be traded away, it is what the protocol
    /// costs: retrying a UDP probe sooner than the target is permitted to answer
    /// is not a faster scan, it is a wasted packet.
    pub timeout_scale: Option<TimeoutScale>,
    /// Whether a host that answers nothing at all may have its budget cut.
    /// Turning this off spends the full budget on every port of every silent
    /// address, which is thorough and expensive.
    pub dampen_silent_hosts: bool,
}

impl Default for RetryConfig {
    fn default() -> Self {
        Self {
            effort: ScanEffort::default(),
            max_attempts: None,
            timeout_scale: None,
            dampen_silent_hosts: true,
        }
    }
}

/// The knobs a probing strategy is built from, carried together so adding one
/// does not mean threading another parameter through every constructor.
///
/// Not every strategy reads every field: local discovery builds its own
/// Ethernet frames and so has no use for [`SendMode`], while every strategy that
/// sends a probe at all has a use for [`RetryConfig`]. `max_probe_rate` is read
/// by routed host discovery and by the raw port scanners, and it means something
/// different to each: the sweep and the UDP scan are paced by it, while a TCP
/// port scan paces itself by a congestion window and treats it only as a
/// ceiling. The unprivileged paths pace themselves by their connection
/// concurrency instead.
///
/// Non-exhaustive, like the [`ZondConfig`] it is built from: a knob added there
/// that a strategy has to read is added here too, and neither should be a major
/// version. Built by [`ZondConfig::probe_tuning`] and, in tests, from
/// [`Default`].
#[non_exhaustive]
#[derive(Debug, Clone, Default)]
pub struct ProbeTuning {
    /// Which layer a strategy puts its probes on the wire through, where it has
    /// the choice.
    pub send_mode: SendMode,

    /// How many attempts a probe gets and how long each waits, as an effort
    /// level with optional overrides.
    pub retry: RetryConfig,

    /// The most probes per second a strategy may emit, or `None` for the pacing
    /// each one arrives at on its own.
    ///
    /// Non-zero because a ceiling of zero probes per second is not a slower
    /// scan, it is no scan. Zero used to be accepted and then read as `None` at
    /// three separate call sites.
    pub max_probe_rate: Option<NonZeroU32>,

    /// The fewest probes per second a strategy should emit, or `None` for
    /// whatever pace it arrives at.
    ///
    /// Read at the same four places as [`max_probe_rate`](Self::max_probe_rate)
    /// and means as many different things: a floor under a pace where the rate
    /// is the pace, and a floor under a ceiling where it is only a ceiling.
    ///
    /// Non-zero for the same reason: a floor of zero is what the absence of a
    /// floor already says.
    pub min_probe_rate: Option<NonZeroU32>,

    /// Which segment a TCP port probe carries. Read only by the raw TCP port
    /// scanner: host discovery asks whether anything is there, which every one
    /// of these techniques answers equally badly, so it stays on SYN.
    pub tcp_technique: TcpScanTechnique,
    /// Which chunk an SCTP port probe carries. Read only by the raw SCTP port
    /// scanner, and for the reason above: a sweep sends an INIT whichever
    /// technique a port scan was asked for, since a COOKIE-ECHO draws nothing
    /// from the open port a sweep is hoping to hear from.
    pub sctp_technique: SctpScanTechnique,

    /// How far a strategy may go to identify the operating system behind a host.
    ///
    /// Read by the raw TCP port scanner, which is where the replies that carry a
    /// stack's shape arrive. At [`OsDetection::Passive`] it changes no packet and
    /// no timing, reading a reply the scan already drew, so it is here rather
    /// than in a phase of its own.
    pub os_detection: OsDetection,

    /// How far a strategy may go to name what is behind an open port.
    ///
    /// Read by every strategy that fingerprints: the raw scanners, which do it
    /// as a second pass over the ports they found, and the connect scanner,
    /// which does it inline over the connection it already holds. Both consult
    /// the same level, so turning it off means no connection is completed for
    /// identification by either route.
    pub service_detection: ServiceDetection,

    /// What the caller has chosen to change about the packets each strategy
    /// emits, over the defaults it would otherwise send.
    ///
    /// A default profile is inert: a strategy handed one sends exactly what it
    /// would without it. Read wherever a strategy chooses a field a caller may
    /// override: the source port a probe leaves from today, and the hop limit,
    /// spoofed address, fragmentation and decoys as those land. See
    /// [`EvasionProfile`].
    pub evasion: EvasionProfile,

    /// Whether the capture admits ICMP errors for a technique that reaches its
    /// verdict without them. See [`ZondConfig::icmp_evidence`].
    pub icmp_evidence: bool,

    /// Source addresses to send every probe from, overriding what the routing
    /// table would choose. One per family at most is used. Empty means the host
    /// decides. Set to send from a chosen interface when the default route is a
    /// VPN the link-layer path cannot traverse.
    pub send_source: Vec<IpAddr>,
}

/// A third party whose IP-ID counter an idle scan reads to learn a target's
/// ports without ever addressing the target as itself.
///
/// The idle (or zombie) scan is the quietest technique this engine has: it
/// forges its probes to carry the zombie's source address, so the target's
/// answers go to the zombie and never to the scanner. What the target said is
/// read indirectly, off the one thing the zombie's replies leak: a global IP-ID
/// counter that advances by one for every packet the zombie sends. Read
/// the counter, forge a probe, read it again: an open port drew an answer the
/// zombie had to reset, advancing the counter an extra step, and a closed or
/// filtered one did not.
///
/// It follows that the zombie has to be the right kind of host, one whose IP-ID
/// is a single shared counter, and that the forged probe needs a self-built
/// Ethernet frame to carry a source address the kernel would never
/// choose. A scan that cannot have either is refused rather than run quietly
/// wrong; see the idle port scanner.
///
/// Non-exhaustive. A zombie is qualified on more than its address and its port
/// already, and what the scan has to be told about one will grow before what it
/// concludes does.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct IdleScan {
    /// The zombie's address.
    ///
    /// It has to be a host with a single global IP-ID counter, a counting
    /// generator in the terms the OS-detection series reads, and idle and
    /// reachable enough that its counter moves for this scan's probes and little
    /// else. A busy zombie's own traffic is noise the scan has to see through,
    /// and one whose counter is random or per-connection carries no signal at
    /// all; both are caught when the scan qualifies it, and an unsuitable zombie
    /// is refused with the counter class it was found to have.
    pub zombie: IpAddr,

    /// A port on the zombie to probe for its counter, or `None` for the engine's
    /// default.
    ///
    /// Any port serves in principle, since an unsolicited SYN/ACK draws a reset
    /// whether the port is open or closed and it is the reset's IP-ID the scan
    /// reads, but the zombie's own filter must not drop the probe, so a caller
    /// that knows a port the zombie answers on can name it here.
    pub zombie_port: Option<u16>,
}

impl IdleScan {
    /// An idle scan through `zombie`, on whichever port the engine picks.
    pub const fn new(zombie: IpAddr) -> Self {
        Self {
            zombie,
            zombie_port: None,
        }
    }

    /// Names the port on the zombie to read its counter from.
    ///
    /// For a zombie whose filter drops the engine's default. See
    /// [`zombie_port`](Self::zombie_port).
    #[must_use]
    pub const fn with_port(mut self, port: u16) -> Self {
        self.zombie_port = Some(port);
        self
    }
}

/// What a scan does, and what it is allowed to put on the wire.
///
/// Every field here changes packets or timing. Nothing about rendering, so no
/// banner and no verbosity and no terminal or keyboard handling, since none of
/// that is the engine's business: it emits `tracing` events and installs no
/// subscriber, so what a run looks like is decided entirely by whoever embeds
/// the crate. A front end's own settings belong to the front end; the engine
/// carries them nowhere and holds no opinion about them.
///
/// That boundary is worth keeping because this type is also the record of *how a
/// scan was run*. [`ScanSettings`](crate::report::ScanSettings) is derived
/// from it into every report, and a field that cannot change a finding has no
/// business in the record of one.
///
/// Non-exhaustive and [`Default`]-constructed, so the next knob is an additive
/// change rather than a major version. Start from
/// [`default`](Default::default) and set the fields the scan needs:
///
/// ```
/// use zond_engine::ZondConfig;
///
/// let mut cfg = ZondConfig::default();
/// cfg.traceroute = true;
/// ```
#[non_exhaustive]
#[derive(Debug, Clone)]
pub struct ZondConfig {
    /// Forbids the scan from generating any DNS traffic of its own: no A, AAAA
    /// or PTR queries, and no name resolution to go with the addresses it finds.
    ///
    /// Set when the traffic itself is the problem. A query to a resolver the
    /// target operates announces the scan to whoever runs it, and on an
    /// engagement that can be the whole of what goes wrong. The cost is hosts
    /// reported by address alone.
    ///
    /// It governs what this engine sends and nothing else. Traffic the host's
    /// own stack generates for its own reasons is outside anything this crate
    /// can promise.
    pub no_dns: bool,

    /// Whether discovery may probe the whole segment rather than only the
    /// addresses it was given.
    ///
    /// A segment sweep sends the ICMPv6 all-nodes echo, which every IPv6
    /// neighbour may answer, and records the ones that do even though nobody
    /// named them. That is the right behaviour for `zond lan`, where the caller
    /// asked about a network and an IPv6 neighbour with no address in the IPv4
    /// range is found through this and nothing else. It is the wrong behaviour
    /// for
    /// `zond <address>`: scanning one host should not wake its neighbours, and a
    /// report listing eight machines when one was asked about is both surprising
    /// and, on someone else's network, indiscreet.
    ///
    /// Off by default, so the surprising behaviour is the one that has to be
    /// asked for. Only the front end knows which the user meant, since the engine
    /// receives an already-resolved set of addresses and cannot tell `lan` from
    /// the range it expanded to, so this has to be set by whoever parsed the
    /// target expression.
    pub segment_sweep: bool,

    /// Whether a port scan should take its targets on trust rather than probing
    /// them for liveness first.
    ///
    /// Off by default, so [`scan`](crate::scan) establishes that a target is
    /// there before spending a probe on each of its ports. An address nothing
    /// answers for otherwise comes back with every port filtered, which is a
    /// thousand lines of the scan reporting its own silence, and on a wide port
    /// range it is most of the run's cost.
    ///
    /// Set it when the liveness probe is the thing that is wrong: a host behind
    /// a firewall that drops ICMP and answers nothing on the discovery ports is
    /// reported down and never scanned, and it may well be up. That is the trade:
    /// the check is what stops a dead address costing a full scan, and turning it
    /// off is what reaches a host that will not answer a knock.
    ///
    /// The liveness phase probes the addresses it was given and nothing else. It
    /// is not a segment sweep; see [`segment_sweep`](Self::segment_sweep).
    pub assume_up: bool,

    /// Whether to measure the route to each host that answered.
    ///
    /// Off by default, and it is the one detection setting that is off for a
    /// reason other than traffic volume. A trace costs roughly one probe per
    /// router per host and says nothing about the host itself. It is a finding
    /// about the network in between, which is a different question from
    /// the one a port scan was asked. Somebody mapping a network wants it and
    /// somebody auditing a server does not, and neither should pay for the
    /// other's answer.
    ///
    /// Only hosts that answered something are traced. A path is measured
    /// backwards from the target, which needs the target's distance, which is
    /// read out of a reply it sent, so a host that answered nothing has no path
    /// this engine can measure and is skipped rather than probed thirty times for
    /// nothing. See
    /// [`traceroute`](crate::scanner::strategy::topology::traceroute).
    ///
    /// Needs raw sockets, like every other probe this engine builds by hand. An
    /// unprivileged run records the refusal rather than reporting an empty path,
    /// which would read as a network with no routers in it.
    pub traceroute: bool,

    /// Whether to characterise the filter in front of each host that answered.
    ///
    /// Off by default, and off for the same reason a traceroute is: it costs a
    /// handful of extra probes per live host and answers a different question
    /// from the one a port scan was asked: what the filtering between the scanner
    /// and a host is doing, rather than what the host runs. A firewall
    /// tester wants it; an inventory scan does not.
    ///
    /// A pass of its own, run after the ports are known and only against hosts
    /// that answered, sending deliberately-shaped diagnostic probes whose results
    /// it reads as [`Filtering`](crate::model::host::Filtering) conclusions. It
    /// does not touch the port verdicts. A bad-checksum probe, the one it sends
    /// today, would report every port filtered if it were the setting a scan ran
    /// under, which is why it is a separate pass rather than a scan option.
    pub characterise: bool,

    /// Which IP protocols to ask each host that answered whether it takes
    /// delivery of, one layer below the ports.
    ///
    /// Empty by default, which runs no pass at all, and empty for the reason
    /// [`characterise`](Self::characterise) is off: it costs a probe per host
    /// per protocol and answers a different question from the one a port scan
    /// was asked. What it finds is what a firewall's *protocol* policy is, which
    /// on a perimeter review is often the more revealing of the two, and what a
    /// host with no open TCP port is nonetheless terminating: a tunnel endpoint
    /// answers for 47, 50 or 51 and a router for 89 or 112.
    ///
    /// [`DEFAULT_PROTOCOLS`](crate::scanner::strategy::protocols::DEFAULT_PROTOCOLS)
    /// is the set worth asking about, for a caller who wants the pass without
    /// choosing the numbers. The whole `0..=255` range is what nmap's protocol
    /// scan walks and is a poor default here, since each number costs a raw
    /// socket; a caller who wants the sweep asks for it.
    ///
    /// A pass of its own, run after the ports are known and only against hosts
    /// that answered, whose results are
    /// [`IpProtocolState`](crate::model::host::IpProtocolState) verdicts on the
    /// host. It does not touch the port verdicts.
    pub ip_protocols: BTreeSet<u8>,

    /// Whether to establish what each TLS port *accepts*, rather than only what
    /// one handshake negotiated.
    ///
    /// Off by default, and off because of what it costs rather than what it
    /// finds. Service detection completes one handshake per TLS port and records
    /// the version and suite that came out of it. This offers the endpoint each
    /// version in turn and narrows the cipher list until it stops answering, so
    /// the report says what the endpoint *would* negotiate: the question every
    /// PCI scan, ASV report and internal audit actually asks, and the one a
    /// single handshake cannot answer.
    ///
    /// The cost is connections. A current server accepting a handful of suites
    /// costs a dozen; one accepting everything under three versions costs a few
    /// dozen, and that is the configuration this exists to find. Each is a bare
    /// TCP connection carrying one ClientHello, torn down before any handshake
    /// completes, so no session is ever established and no application sees one.
    /// A target's connection log sees every one of them.
    ///
    /// A pass of its own, run after service detection, since what it needs first
    /// is the list of ports that speak TLS at all. Bounded per host by
    /// [`host_timeout`](Self::host_timeout), which is worth setting alongside
    /// this on anything unattended.
    ///
    /// ```
    /// # use zond_engine::ZondConfig;
    /// # use std::time::Duration;
    /// let mut cfg = ZondConfig::default();
    /// cfg.tls_enumeration = true;
    /// cfg.host_timeout = Some(Duration::from_secs(120));
    /// ```
    pub tls_enumeration: bool,

    /// Scan TCP ports through a third-party zombie rather than by addressing the
    /// target directly, when set. See [`IdleScan`].
    ///
    /// This replaces the ordinary TCP port scan wholesale: the technique in
    /// [`tcp_technique`](Self::tcp_technique) does not apply, because every probe
    /// is a forged SYN read through the zombie's counter rather than a segment
    /// whose own reply is classified. It is TCP-only: a UDP port cannot be read
    /// this way, and probing one directly would announce the scanner the idle
    /// technique exists to hide, so UDP targets are left unprobed. It needs the
    /// privilege and the self-built frame a spoofed source address requires, and
    /// a suitable zombie; lacking any of these the scan is refused, never run
    /// under its own address instead.
    pub idle_scan: Option<IdleScan>,

    /// Addresses this scan may not probe, whatever else it was asked to cover.
    ///
    /// Empty by default. Everything else in this struct decides *how* a scan is
    /// run; this is the only field that decides where it may not go, and it is
    /// the only one whose failure to be honoured is somebody's contract rather
    /// than somebody's result. An engagement scoped as "10.0.0.0/8, except the
    /// cardholder segment" has no other way to be expressed, and a scanner that
    /// cannot express it cannot be pointed at that network at all.
    ///
    /// It is enforced twice, before the first packet and again at every finding,
    /// and the reasons for both are in [`Exclusions`]. Read that before changing
    /// anything here: the second enforcement exists because a segment sweep
    /// learns addresses that were never in the target list, and losing it turns
    /// a guarantee back into a filter.
    ///
    /// Narrowing only. No value here can make a scan send a packet it would not
    /// otherwise have sent, which is what makes it safe to accept from a settings
    /// file when [`segment_sweep`](Self::segment_sweep) is not. See
    /// `import::settings::Settings`, where that asymmetry is the argument for
    /// which keys a document is allowed to carry.
    pub exclusions: Exclusions,

    /// Whether identifying detail should be masked wherever the scan's findings
    /// leave the process: hostnames, hardware addresses, and the host part of an
    /// IPv6 address.
    ///
    /// For a report going somewhere that needs a network's shape without knowing
    /// which device is which: a client, an auditor, a screenshot in an issue.
    ///
    /// The engine does not mask anything itself; a scan holds what it found. This
    /// records the caller's intent, and it reaches the point of use through
    /// [`ScanSettings`](crate::report::ScanSettings) and the export layer's
    /// own [`Redaction`](crate::export::Redaction) policy. Masking on the way out
    /// rather than on the way in is deliberate: the alternative is a report that
    /// has quietly lost data nobody can recover.
    pub redact: bool,

    /// How raw SYN probes are placed on the wire. Defaults to
    /// [`SendMode::Auto`], which is correct on every supported platform;
    /// override it only to force Layer-2 sends for host-stack-bypass scanning.
    pub send_mode: SendMode,

    /// The fastest a scan may put probes on the wire, in probes per second.
    /// `None` leaves each scanner's own default in force.
    ///
    /// This is a coverage control before it is a politeness one. A probe's
    /// chance of being answered falls as the rate rises: on a policed path a
    /// burst loses most of its first attempt and the loss is recovered, if at
    /// all, by retransmitting into a quieter moment. Lowering the rate buys
    /// coverage on the first attempt instead, and raising it trades coverage
    /// for the time a large range takes to emit.
    ///
    /// It is a ceiling on a TCP port scan rather than its pace. That scan
    /// discovers how fast each target will answer and settles there, which is
    /// almost always well below any rate worth configuring; see
    /// [`congestion`](crate::scanner::pacing::congestion). Setting this lowers
    /// the ceiling the window may reach and is the right knob for a target that
    /// must not be pushed at all, but on an ordinary scan it will not be what
    /// decides the pace. The discovery sweep and the UDP port scan *are* paced
    /// by it, because neither is given evidence it could adapt on.
    ///
    /// Non-zero: a ceiling of zero is not a slower scan but no scan, and the
    /// value reaches the report, which must not record a ceiling that was never
    /// applied.
    pub max_probe_rate: Option<NonZeroU32>,

    /// The slowest a scan may put probes on the wire, in probes per second.
    /// `None` leaves each scanner's own pace in force.
    ///
    /// The knob for a plan large enough that finishing it is in doubt. A scan
    /// given [`scan_timeout`](Self::scan_timeout) can spend the whole budget on
    /// a fraction of its targets and report the rest as
    /// [`timed_out`](crate::report::ScanPhase::timed_out); this is what makes a
    /// wall-clock bound and a large range compatible, by refusing to settle
    /// below a pace that would finish in time.
    ///
    /// It reaches the same four strategies as
    /// [`max_probe_rate`](Self::max_probe_rate) and means what the rate means to
    /// each. The discovery sweep and the UDP port scan are paced by the rate, so
    /// a floor raises their pace. A TCP port scan is paced by its congestion
    /// window and reads the rate only as a ceiling, so a floor raises the
    /// ceiling and leaves the window to decide as before. Nothing here overrides
    /// that window: pushing a target harder than it is answering is the failure
    /// the window exists to prevent, and a floor that could force it would trade
    /// coverage for a number.
    ///
    /// A floor above an explicit [`max_probe_rate`](Self::max_probe_rate) does
    /// not lift it. The two are a throughput wish and a safety limit, and the
    /// safety limit wins.
    ///
    /// Non-zero: a floor of zero is what `None` already says, and the value
    /// reaches the report, which must not record a floor that was never applied.
    pub min_probe_rate: Option<NonZeroU32>,

    /// The shortest gap between two probes aimed at one host, or `None` to let
    /// every pass send as fast as its own pacing allows.
    ///
    /// The knob for what an operator actually knows about a target: this
    /// appliance falls over above twenty probes a second, or this sensor fires
    /// at more than one every hundred milliseconds. Both of those are per source
    /// and destination, which is the one shape
    /// [`max_probe_rate`](Self::max_probe_rate) cannot express: the same setting
    /// that spaces probes at one host also throttles the scan across a whole
    /// range.
    ///
    /// A duration rather than a rate because that is what the gate holds, and
    /// converting a rate would round. See `pacing_for` for what a rounded rate
    /// costs: a bound the report records and the scan never applied.
    ///
    /// ## What this is not
    ///
    /// It is not a substitute for the plan's keyed order, and not made
    /// redundant by it. A permutation runs over the plan's host-and-port index
    /// space, so a scan of many hosts already interleaves them and each one's
    /// share of the rate falls out low; that is a consequence of the arithmetic
    /// rather than a bound, and it offers nothing at all to a scan of one
    /// address, which is the case somebody worried about a fragile target is
    /// usually running.
    ///
    /// It is also not a ceiling the engine can beat by waiting. A probe held
    /// here is deferred rather than dropped, so a scan spaced slower than its
    /// plan is large takes longer instead of asking less: with
    /// [`scan_timeout`](Self::scan_timeout) set, the two meet and the report
    /// says which hosts the budget left part-scanned.
    ///
    /// Read by the raw port scanners, the routed sweep and the active
    /// identification pass. The passive listener sends nothing, and the
    /// timestamp series is timed rather than paced: its probe spacing is the
    /// measurement, so slowing it would change what it reads rather than how
    /// politely it reads it.
    ///
    /// ## The unprivileged paths do not honour this yet
    ///
    /// A connect scan ignores it, which matters because that is the path a
    /// non-root caller gets. This is a gap rather than a decision, and it is not
    /// the argument [`max_probe_rate`](Self::max_probe_rate) makes about those
    /// paths pacing themselves by their connection concurrency: concurrency
    /// bounds how many probes are in flight at once and says nothing about how
    /// close together two of them reach one address.
    ///
    /// What it needs is a gate that claims a host's slot in the same operation
    /// that checks it. The privileged paths check and then record, in that
    /// order, because a send the kernel refuses must not spend the slot; a
    /// connect scan runs its probes as concurrent tasks, so two aimed at one
    /// address would both find it ready and both proceed. Until that primitive
    /// exists, a caller who needs the gap enforced needs the privileged path.
    ///
    /// ## What a gap counts
    ///
    /// One probe, which is one packet everywhere but the identification pass.
    /// That pass asks an IPv4 target for an echo and a timestamp back to back
    /// and treats the pair as the probe, since deferring one half of a question
    /// would leave the other half unanswerable. So a gap of 100 ms admits at
    /// most two packets a tenth of a second at one IPv4 address while that pass
    /// runs, and one everywhere else. The number is stated here rather than left
    /// for somebody to find in a capture.
    pub host_probe_interval: Option<Duration>,

    /// The longest a scan will keep working on one host before leaving it with
    /// what it has, or `None` for no bound.
    ///
    /// The clock starts on the first probe aimed at an address and covers every
    /// later pass that sends to it: the port scan, the service pass, and the
    /// identification, path and detection passes after that. Once it expires
    /// the host is left alone, and the address is written into
    /// [`ScanPhase::timed_out`](crate::report::ScanPhase::timed_out) so a short
    /// port list is not read as a quiet machine.
    ///
    /// Reverse lookup is outside it. A PTR query is traffic to a resolver
    /// rather than to the host, so it costs the host none of its budget, and
    /// [`no_dns`](Self::no_dns) is the setting that governs whether it happens
    /// at all.
    ///
    /// The bound is for a host that answers slowly rather than one that does
    /// not answer at all. Silence already costs a known number of probes,
    /// because the retry schedule ends; a tarpit, a rate-limited appliance or a
    /// stack that replies to one probe in ten costs whatever it decides to.
    ///
    /// Discovery is outside it. A liveness sweep spends a fixed schedule per
    /// address and finishes whether or not anything replies, so there is no
    /// unbounded time there for a per-host budget to bound. See
    /// [`scan_timeout`](Self::scan_timeout) for the bound that does reach it.
    ///
    /// What it stops is new probes rather than the ones already in flight, so a
    /// host may go on answering for as long as the retry schedule of its last
    /// window takes to run out. That tail is bounded by the schedule and does
    /// not grow with how slowly the host answers, which is the thing this is
    /// here to bound.
    ///
    /// Zero expires before the first probe, which is a scan that asks nothing
    /// and records every host as cut short.
    pub host_timeout: Option<Duration>,

    /// The longest the whole call may run before it winds down, or `None` for
    /// no bound.
    ///
    /// Measured from the moment the scan is assembled, and it reaches every
    /// phase: discovery, the port scan, and everything that enriches what they
    /// found. When it expires the strategies stop on their next pass and the
    /// run ends the way an aborted one does, except that each scanner records
    /// [`StopReason::TimedOut`](crate::report::StopReason::TimedOut) rather
    /// than `Aborted`, since nobody asked it to stop.
    ///
    /// This is what makes an unattended run safe to schedule. The rest of this
    /// struct bounds a probe, a retry or a host, and none of those bounds the
    /// product: a range with enough slow addresses in it has no finishing time
    /// a caller can work out in advance.
    ///
    /// Winding down is not cancelling. What was found is kept, and the ports
    /// the scan never reached are recorded with its silence verdict rather than
    /// left off the host.
    ///
    /// It bounds this call and not the job behind it, so each sitting of a
    /// resumed scan is given the budget afresh. A job that must finish inside
    /// one is the caller's to bound, by counting the sittings they start.
    pub scan_timeout: Option<Duration>,

    /// Which segment a TCP port probe carries, and so what its answers mean.
    ///
    /// Defaults to [`TcpScanTechnique::Syn`], which is the only technique that
    /// identifies an open port positively and the only one the unprivileged
    /// connect fallback can approximate. The rest need raw sockets; asking for
    /// one without them records a failure rather than quietly substituting a
    /// connect scan, because the two answer different questions.
    ///
    /// Affects the port-scan phase only. [`discover`](crate::scanner::discover)
    /// is unaffected.
    pub tcp_technique: TcpScanTechnique,

    /// Which chunk an SCTP port probe carries, and so what its answers mean.
    ///
    /// Defaults to [`SctpScanTechnique::Init`], the only technique that names an
    /// open SCTP port. [`CookieEcho`](SctpScanTechnique::CookieEcho) trades that
    /// for passage: it draws an answer only from a port with nothing behind it,
    /// so its best verdict is open-or-filtered, and it crosses filters written
    /// against the INIT chunk a scan is expected to send.
    ///
    /// Both need raw sockets, and neither has an unprivileged form. Affects the
    /// port-scan phase only: a discovery sweep asks whether an address is there
    /// and sends an INIT whatever this says, since a COOKIE-ECHO draws nothing
    /// from a host whose port is open.
    pub sctp_technique: SctpScanTechnique,

    /// How hard the scan tries before accepting silence as an answer.
    ///
    /// Every probing path has its own schedule, tuned to what its protocol
    /// requires; this scales those rather than replacing them, so raising or
    /// lowering the effort cannot hand a scanner a schedule its protocol cannot
    /// satisfy. Defaults to
    /// [`ScanEffort::Balanced`].
    pub retry: RetryConfig,

    /// How far the scan goes to identify the operating system behind each host.
    ///
    /// Defaults to [`OsDetection::Passive`], which reads what the replies the
    /// scan already drew happen to say and emits nothing of its own. The higher
    /// levels send probes and have to be asked for; see [`OsDetection`] for what
    /// each one puts on the wire.
    pub os_detection: OsDetection,

    /// How far the scan goes to identify what is listening behind each open
    /// port.
    ///
    /// Defaults to [`ServiceDetection::Probe`], which connects to every open
    /// port and asks it what it is. That is the level worth having, since a port
    /// state without a service name answers half the question, but it is also the
    /// one that completes connections, so a scan that must stay out of the
    /// target's application logs turns it off. Affects the port-scan phase only.
    pub service_detection: ServiceDetection,

    /// How intrusive a detection the scan may run against an identified service.
    ///
    /// After service detection names a port, the flow corpus can probe it further
    /// to conclude what is *wrong* with it, not just what it is. This is the
    /// ceiling on how far that goes: the default permits passive and active-benign
    /// detections, and a detection that mutates, exploits, or degrades the target
    /// runs only where the operator raises the ceiling to it. Read by the
    /// detection phase, after service detection, and only when it ran.
    pub detection: DetectionEnvelope,

    /// What the scan changes about the packets it emits, over the defaults.
    ///
    /// Defaults to an inert profile, so a scan that set nothing here is
    /// indistinguishable from one run before the option existed. Carried into
    /// [`probe_tuning`](Self::probe_tuning) for the strategies to read, and (once
    /// the provenance surface lands) into the report, so a scan that evaded
    /// something says so. See [`EvasionProfile`].
    pub evasion: EvasionProfile,

    /// Whether to capture ICMP errors for a technique whose verdict does not
    /// depend on them, such as a SYN scan. On by default.
    ///
    /// An ICMP error is a firewall answering, and a scan too outrun to read
    /// silence as a verdict can still report it, so the difference between a
    /// refused port and an unreached one is worth the errors the capture copies
    /// up. A caller on a link noisy with ICMP turns it off. The other TCP
    /// techniques read ICMP for their verdicts regardless.
    pub icmp_evidence: bool,

    /// Source addresses to force, one per family. See [`ZondConfig::send_source`].
    pub send_source: Vec<IpAddr>,
}

impl Default for ZondConfig {
    /// Hand-written so [`icmp_evidence`](Self::icmp_evidence) defaults on; every
    /// other field takes its own type's default.
    fn default() -> Self {
        Self {
            icmp_evidence: true,
            send_source: Vec::new(),
            no_dns: Default::default(),
            segment_sweep: Default::default(),
            assume_up: Default::default(),
            traceroute: Default::default(),
            characterise: Default::default(),
            ip_protocols: Default::default(),
            tls_enumeration: Default::default(),
            idle_scan: Default::default(),
            exclusions: Default::default(),
            redact: Default::default(),
            send_mode: Default::default(),
            max_probe_rate: Default::default(),
            min_probe_rate: Default::default(),
            host_probe_interval: Default::default(),
            host_timeout: Default::default(),
            scan_timeout: Default::default(),
            tcp_technique: Default::default(),
            sctp_technique: Default::default(),
            retry: Default::default(),
            os_detection: Default::default(),
            service_detection: Default::default(),
            detection: Default::default(),
            evasion: Default::default(),
        }
    }
}

impl ZondConfig {
    /// The probe-level knobs, bundled for the strategies that need them.
    ///
    /// `self` is destructured with every field named, so a knob added above and
    /// not carried here is a compile error rather than a setting that silently
    /// reaches no strategy. The fields listed and dropped are the ones a probing
    /// strategy has no use for: they govern which phases run and where a scan may
    /// go, which is the orchestrator's business rather than a probe's.
    pub fn probe_tuning(&self) -> ProbeTuning {
        let Self {
            send_mode,
            retry,
            max_probe_rate,
            min_probe_rate,
            tcp_technique,
            sctp_technique,
            os_detection,
            service_detection,
            evasion,
            icmp_evidence,
            send_source,

            // Read elsewhere. Named so that adding a field forces this decision
            // rather than skipping it.
            no_dns: _,
            segment_sweep: _,
            assume_up: _,
            traceroute: _,
            characterise: _,
            ip_protocols: _,
            tls_enumeration: _,
            idle_scan: _,
            exclusions: _,
            redact: _,
            detection: _,

            // The two wall-clock bounds. Neither is a probe's business: the
            // scan's rides on the `ScanHandle` every probing loop already
            // reads, and the host's is held by the context the strategies
            // share.
            host_timeout: _,
            scan_timeout: _,

            // The per-host gap, which goes the same way as the host budget and
            // for the same reason: a bound on one host has to be one map every
            // pass consults, not a copy per strategy. Two passes each holding
            // their own would each allow the whole gap.
            host_probe_interval: _,
        } = self;

        ProbeTuning {
            send_mode: *send_mode,
            retry: *retry,
            max_probe_rate: *max_probe_rate,
            min_probe_rate: *min_probe_rate,
            tcp_technique: *tcp_technique,
            sctp_technique: *sctp_technique,
            os_detection: *os_detection,
            service_detection: *service_detection,
            evasion: evasion.clone(),
            icmp_evidence: *icmp_evidence,
            send_source: send_source.clone(),
        }
    }
}

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

#[cfg(test)]
mod tests {

    /// The capture knob reaches the strategies, which is the whole of what it
    /// does: a scan asked for the evidence and the tuning has to carry it.
    #[test]
    fn icmp_evidence_reaches_the_probe_tuning_and_is_on_unless_declined() {
        let mut cfg = ZondConfig::default();
        assert!(
            cfg.probe_tuning().icmp_evidence,
            "an error is a verdict a scan that was outrun cannot reach any other way"
        );

        cfg.icmp_evidence = false;
        assert!(
            !cfg.probe_tuning().icmp_evidence,
            "and a caller may decline it"
        );
    }
    use super::*;
    use std::num::NonZeroU8;

    /// The three scales are one vocabulary, so what holds for one holds for all
    /// three. Written per type, they drifted: `ScanEffort` took no number, and
    /// the module documentation promised that all three did.
    #[test]
    fn every_scale_agrees_with_its_own_numbering() {
        fn check<T: Copy + std::fmt::Debug + PartialEq>(
            all: &[T],
            name: fn(T) -> &'static str,
            level: fn(T) -> u8,
            from_level: fn(u8) -> Option<T>,
        ) {
            for (index, value) in all.iter().copied().enumerate() {
                assert_eq!(usize::from(level(value)), index, "{value:?}");
                assert_eq!(from_level(level(value)), Some(value), "{value:?}");
                assert!(!name(value).is_empty());
            }
            let past_the_end = all.len() as u8;
            assert_eq!(
                from_level(past_the_end),
                None,
                "a level this engine does not offer is refused, not rounded down"
            );
        }

        check(
            &ScanEffort::ALL,
            ScanEffort::name,
            ScanEffort::level,
            ScanEffort::from_level,
        );
        check(
            &OsDetection::ALL,
            OsDetection::name,
            OsDetection::level,
            OsDetection::from_level,
        );
        check(
            &ServiceDetection::ALL,
            ServiceDetection::name,
            ServiceDetection::level,
            ServiceDetection::from_level,
        );
    }

    /// Both spellings are one setting for every scale, including the one that
    /// used to accept only the word while the module documentation said
    /// otherwise. A front end reading `2` from a flag and `balanced` from a
    /// settings file must not get two different scans.
    #[test]
    fn every_scale_parses_the_same_by_name_and_by_number() {
        for effort in ScanEffort::ALL {
            assert_eq!(effort.name().parse(), Ok(effort));
            assert_eq!(effort.name().to_uppercase().parse(), Ok(effort));
            assert_eq!(format!("  {}  ", effort.level()).parse(), Ok(effort));
        }
        assert!("4".parse::<ScanEffort>().is_err());
        assert!("maximum".parse::<ScanEffort>().is_err());

        for detection in OsDetection::ALL {
            assert_eq!(detection.name().parse(), Ok(detection));
            assert_eq!(detection.level().to_string().parse(), Ok(detection));
        }
        for detection in ServiceDetection::ALL {
            assert_eq!(detection.name().parse(), Ok(detection));
            assert_eq!(detection.level().to_string().parse(), Ok(detection));
        }
    }

    /// The message a front end prints is built from the levels themselves, so a
    /// level added to a scale is a level the message names.
    ///
    /// The three messages used to spell their own lists, and nothing compared
    /// them against `ALL`: both spellings would still parse and only the
    /// sentence a caller reads would be wrong.
    #[test]
    fn a_parse_error_names_every_level_that_would_have_worked() {
        let effort = "maximum".parse::<ScanEffort>().unwrap_err().to_string();
        for level in ScanEffort::ALL {
            assert!(effort.contains(level.name()), "{effort} omits {level}");
        }
        assert!(effort.contains("0 to 3"), "{effort}");

        let os = "9".parse::<OsDetection>().unwrap_err().to_string();
        for level in OsDetection::ALL {
            assert!(os.contains(level.name()), "{os} omits {level}");
        }

        let service = "exhaustive"
            .parse::<ServiceDetection>()
            .unwrap_err()
            .to_string();
        for level in ServiceDetection::ALL {
            assert!(service.contains(level.name()), "{service} omits {level}");
        }
        assert!(service.contains("0 to 3"), "{service}");
    }

    /// A scale no schedule can be built from is refused where it is set.
    ///
    /// It used to be accepted here, discarded without a word where the policy is
    /// built, and then written into the report as though it had applied. That
    /// last part is why this is a type: `ZondConfig` is the record of how a scan
    /// ran as well as the instruction for running it.
    #[test]
    fn a_retry_override_can_only_hold_a_value_a_scan_could_honour() {
        for factor in [0.0, -1.0, -0.0, f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
            assert_eq!(TimeoutScale::new(factor), None, "scale {factor}");
        }
        assert_eq!(TimeoutScale::new(2.5).map(TimeoutScale::get), Some(2.5));

        // The smallest positive float is a scale, absurd but honourable: it says
        // what it does and the schedule it produces is the one asked for.
        assert!(TimeoutScale::new(f64::MIN_POSITIVE).is_some());
    }

    /// Every override in a retry configuration is a narrower type than the field
    /// it sets, so what reaches a strategy is what a scan can honour.
    #[test]
    fn the_retry_overrides_are_unset_by_default() {
        let retry = RetryConfig::default();
        assert_eq!(retry.max_attempts, None);
        assert_eq!(retry.timeout_scale, None);
        assert_eq!(retry.effort, ScanEffort::Balanced);
        assert!(retry.dampen_silent_hosts);
    }

    /// The knobs a strategy reads arrive intact.
    ///
    /// `probe_tuning` enumerated seven fields by hand, had eight call sites and
    /// no test: a knob added to both structs and forgotten here would reach no
    /// strategy, silently, which is the defect `Host::merge` had. It
    /// destructures `self` now, so the omission is a compile error; this is the
    /// half that catches a field wired to the wrong place.
    #[test]
    fn every_probe_level_knob_reaches_the_strategies() {
        let cfg = ZondConfig {
            send_mode: SendMode::Ethernet,
            retry: RetryConfig {
                effort: ScanEffort::Thorough,
                max_attempts: NonZeroU8::new(7),
                timeout_scale: TimeoutScale::new(3.5),
                dampen_silent_hosts: false,
            },
            // Two rates, and deliberately different numbers: the failure this
            // half exists to catch is a bound carried from the other one, which
            // a shared value would let through.
            max_probe_rate: NonZeroU32::new(1234),
            min_probe_rate: NonZeroU32::new(567),
            tcp_technique: TcpScanTechnique::Xmas,
            sctp_technique: SctpScanTechnique::CookieEcho,
            os_detection: OsDetection::Aggressive,
            service_detection: ServiceDetection::Banner,
            evasion: EvasionProfile::default(),
            ..Default::default()
        };

        let tuning = cfg.probe_tuning();
        assert_eq!(tuning.send_mode, cfg.send_mode);
        assert_eq!(tuning.retry, cfg.retry);
        assert_eq!(tuning.max_probe_rate, cfg.max_probe_rate);
        assert_eq!(tuning.min_probe_rate, cfg.min_probe_rate);
        assert_eq!(tuning.tcp_technique, cfg.tcp_technique);
        assert_eq!(tuning.sctp_technique, cfg.sctp_technique);
        assert_eq!(tuning.os_detection, cfg.os_detection);
        assert_eq!(tuning.service_detection, cfg.service_detection);
        assert_eq!(tuning.evasion, cfg.evasion);
    }

    /// The two boundaries that matter to a target, and they are different ones.
    ///
    /// `connects` is what its application logs would record; `sends` is what its
    /// services would be handed. A level that connected but sent nothing, and a
    /// level that did neither, look identical in every count a scan reports and
    /// could hardly be more different to whoever runs the machine.
    #[test]
    fn each_service_detection_level_says_what_it_puts_on_the_wire() {
        assert!(!ServiceDetection::Off.connects());
        assert!(!ServiceDetection::Off.sends());

        assert!(ServiceDetection::Banner.connects());
        assert!(
            !ServiceDetection::Banner.sends(),
            "listening is the whole of what this level does"
        );

        assert!(ServiceDetection::Probe.connects());
        assert!(ServiceDetection::Probe.sends());

        assert!(
            ServiceDetection::default().sends(),
            "the default asks, because asking is both the informative answer and \
             the fast one"
        );
    }

    /// Where the wire cost begins. The default level promises to emit nothing at
    /// all, and that promise is what makes it safe to leave on for every scan, so
    /// which levels answer `true` here is a behavioural contract rather than an
    /// implementation detail.
    #[test]
    fn os_detection_sends_nothing_below_the_active_level() {
        assert!(!OsDetection::Off.is_active());
        assert!(!OsDetection::Passive.is_active());
        assert!(OsDetection::Active.is_active());
        assert!(OsDetection::Aggressive.is_active());

        assert!(!OsDetection::default().is_active(), "the default is silent");
        assert!(OsDetection::default().is_enabled(), "and it is still on");
    }
}