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
// 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
//! # How many questions a scan may have outstanding
//!
//! A scan has to decide how hard to push, and the decision cannot be made in
//! advance. The right answer for a Linux server on a switch is thousands of
//! probes in flight; the right answer for the consumer router next to it is a
//! few dozen, and asking that router at the server's pace does not merely
//! annoy it — it manufactures findings. Probed faster than it will answer, a
//! router reports six hundred ports `filtered` with no more hesitation than it
//! reports the three that really are, and every one of those verdicts is a
//! claim about somebody's firewall that is actually a claim about our send rate.
//!
//! [`CongestionWindow`] makes the decision from evidence instead: it bounds how
//! many probes a scan may have outstanding, grows that bound while answers keep
//! arriving, and cuts it when the answers show the target is being outrun.
//!
//! ## Why a window and not a rate
//!
//! A configured rate is a guess, and it is wrong in both directions at once —
//! too fast for the router, too slow for the server, and no rate is right for a
//! scan that meets both. It is also unanchored: nothing about "four hundred
//! probes a second" refers to anything the target does.
//!
//! A window refers to exactly that. Probes leave as earlier ones are answered,
//! so the send rate settles at the rate the target is *resolving* them, whatever
//! that rate happens to be. It needs no clock, it needs no configuration, and it
//! is self-correcting: a target that slows down is asked more slowly without
//! anybody deciding anything.
//!
//! The engine still has a rate ceiling, and it still means something — but it is
//! a backstop against a defect in this file, not the thing that paces a scan.
//!
//! ## The loss signal, and why it is not the timeout
//!
//! TCP congestion control reduces on a timeout, because for TCP a lost segment
//! means a full queue. A port scanner cannot borrow that rule, because for a
//! scanner an unanswered probe usually means a firewall. Reducing on silence
//! would slow a scan to a crawl against exactly the hosts that are silent by
//! policy — and it would do it worst on the wide, heavily filtered ranges where
//! finishing at all is the whole difficulty.
//!
//! So the rule is narrower, and it turns on *who* is silent:
//!
//! > **Silence from a host that has never spoken is not congestion. Silence from
//! > a host that is otherwise answering us is.**
//!
//! A machine that replies to seven hundred probes and drops two hundred is not
//! running a two-hundred-port block list; it is failing to keep up. A machine
//! that replies to nothing is behind a firewall, or is not there, and asking it
//! more slowly discovers nothing at either. That one distinction separates the
//! cases a timeout-driven controller confuses:
//!
//! | What is happening | What the controller sees | What it does |
//! |---|---|---|
//! | Host answers everything | Answers on the first ask | Grows to the ceiling |
//! | Address is a black hole | Nothing ever answers | Grows; finishes at speed |
//! | Host is being outrun | Timeouts, from a host that talks | Cuts the window |
//! | Host is being outrun badly | Answers arriving only on retries | Cuts the window |
//!
//! The last two are the same fault seen at different times, and both are needed.
//! A recovery is the stronger evidence — the port demonstrably wanted to answer —
//! but it arrives late, and it arrives *not at all* when the retries are lost as
//! well as the first attempt.
//!
//! ## What the narrower rule cost, measured
//!
//! The first version of this file cut only on recoveries, on the reasoning that
//! a timeout might be a firewall. Against a Raspberry Pi on a home network it
//! never cut once, and three consecutive scans of the same host reported this:
//!
//! - eleven ports were open across the three runs; **each run found exactly
//! seven**, and only one port was found by all three;
//! - roughly two hundred and forty ports came back `filtered` each time, and the
//! set was reshuffled every run — port 53 filtered once and open twice, port 22
//! open twice and filtered once.
//!
//! Nothing on that host was filtered. Every one of those verdicts was this
//! scanner's own send rate, reported as somebody's firewall — which is precisely
//! the failure the module was written to prevent, arrived at by a different
//! route.
//!
//! The arithmetic says why the recovery signal never fired. At a quarter of
//! probes lost and three *independent* attempts, an open port is missed one time
//! in seventy: eleven open ports should have come back as nearly eleven, not
//! seven. Seven means the attempts were not independent — all three of them fell
//! inside the same congested moment, so nothing was ever recovered on a retry and
//! the controller was handed no evidence at all. A signal that only fires once
//! the target has recovered is a signal that goes quiet exactly when the target
//! is worst off.
//!
//! ## What occupies the window
//!
//! A probe holds a slot **from its first send until its first outcome**, and its
//! first outcome is either an answer or the expiry of its round-trip budget.
//! After that it is in the retry schedule rather than in flight, and it holds
//! nothing.
//!
//! That line is not a detail; getting it wrong is the difference between a
//! working scanner and an unusable one. Hold the slot until the probe is
//! finally resolved and a firewalled port occupies the window for its whole
//! retry lifetime — most of two seconds, against a round trip of one
//! millisecond. A thousand filtered ports through a window of thirty-two is then
//! a minute of waiting for silence the scan had already heard, and the target
//! that is hardest to finish throttles the scan exactly as a congested one does.
//! Which is the confusion this whole module exists not to make.
//!
//! Retries are not readmitted. They are real packets and they count toward the
//! damping below, but a question already given up on once does not take a slot
//! back from a question nobody has asked yet.
//!
//! ## Growth, reduction and damping
//!
//! Growth is TCP's, because TCP's is right here: exponential while the window is
//! below [`WindowLimits::slow_start_threshold`], linear above it. Slow start is
//! what gets a scan up to speed in a handful of round trips instead of a
//! thousand; the threshold is what stops it overshooting a target's capacity by
//! a factor of two before it notices.
//!
//! **A probe that timed out against a silent host grows the window exactly as an
//! answered one does.** That reads backwards until the rule above is taken
//! seriously: nothing that host does is evidence about capacity, and asking it
//! more slowly discovers nothing. Against an address that answers nothing at all
//! — a firewalled host, a dead address in a range — this is what lets the scan
//! open up and finish, instead of creeping through at whatever window it
//! happened to start with.
//!
//! So every probe yields exactly one signal, and the caller decides which by
//! answering one question about it: did anything about this outcome say the
//! target is failing to keep up?
//!
//! Reduction halves, and then **refuses to halve again until the window's worth
//! of probes has been released**. Without that, one overloaded moment collapses
//! the window: a burst of fifty probes that all needed retries is fifty
//! recoveries arriving together, and fifty halvings is the floor. One reduction
//! per window of sends is the same rule TCP applies for the same reason, phrased
//! in probes rather than in round trips because a scanner already counts probes
//! and would have to invent the round trip.
//!
//! ## What is deliberately not a signal
//!
//! A frame the kernel's capture buffer dropped is loss too, and unlike a
//! timeout it is unambiguous — the reply arrived and this process was too busy
//! to take it. It is not wired in here, because it does not need to be: the
//! probe whose reply was dropped times out, is sent again, and is answered, and
//! that is a recovery like any other. Reading the counter as well would react
//! one round trip sooner and cost a poll in the receive loop for a case the
//! controller already handles. The counter is reported to the operator instead,
//! by [`ProbeAudit`](crate::scanner::audit::ProbeAudit), because a receive path
//! that cannot keep up is a fact about their machine rather than about the
//! network, and no amount of pacing makes that the right thing not to say.
//!
//! ## Where it applies, and where it deliberately does not
//!
//! TCP port scanning, where silence is exceptional and an answer is the norm.
//! **Not UDP**: a UDP probe's ordinary outcome *is* silence, and the ledger
//! cannot tell which attempt a reply answered because a UDP probe carries
//! nothing for the reply to echo. Both halves of the signal are missing, so a
//! UDP scan keeps a window that does not move — [`WindowLimits::fixed`] — and
//! stays paced by the fixed rate its ICMP rate limiter demands. A controller fed
//! no evidence is not a conservative controller, it is a random one.
use fmt;
/// The bounds a [`CongestionWindow`] moves within, and where it starts.
///
/// Declared per scanner beside its retry policy and deadline profile, since what
/// counts as a reasonable number of outstanding questions is a property of the
/// protocol and of what answers it.
/// How many probes a scan may keep outstanding, adapted to what the targets are
/// managing to answer.
///
/// A scanner reads [`capacity`](Self::capacity) to decide whether to admit
/// another target, and reports three things back: that a probe was sent, that
/// one was answered, and that one was answered *only after being sent again*.
/// The last is the loss signal and the reason this type can tell a slow host
/// apart from a firewalled one; the module documentation has the argument.
/// What a [`CongestionWindow`] did over one run.
///
/// Instrumentation rather than telemetry: it says whether pacing engaged and how
/// hard, which is the difference between "this host is firewalled" and "this
/// host was asked too fast", and that difference is otherwise invisible in
/// everything else a scan reports.
// ╔════════════════════════════════════════════╗
// ║ ████████╗███████╗███████╗████████╗███████╗ ║
// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
// ║ ██║ █████╗ ███████╗ ██║ ███████╗ ║
// ║ ██║ ██╔══╝ ╚════██║ ██║ ╚════██║ ║
// ║ ██║ ███████╗███████║ ██║ ███████║ ║
// ║ ╚═╝ ╚══════╝╚══════╝ ╚═╝ ╚══════╝ ║
// ╚════════════════════════════════════════════╝