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
// 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
//! # Send one probe and collect what answers
//!
//! [`protocols::craft`](crate::protocols::craft) builds a segment and
//! [`ProbeTransport`] carries one, and between the two sit half a dozen
//! decisions: which source address this host would use for the destination,
//! which interface a link-local address is valid on, which filter the capture
//! has to be opened with for the reply to be seen at all, and how long to wait.
//!
//! Every one of those is a decision this crate already knows how to make, and
//! every one of them, got wrong, produces the same symptom: no reply, which
//! reads as a filtered port rather than as a mistake.
//!
//! ```no_run
//! use std::time::Duration;
//! use zond_engine::protocols::craft::{Packet, Tcp, tcp_flags};
//! use zond_engine::transport::exchange::Exchange;
//! use zond_engine::transport::probe::ProbeKind;
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! // The filter decides what can come back, so it is named rather than guessed.
//! let mut exchange = Exchange::open(ProbeKind::TcpProbe {
//! reply_port: 50_000,
//! icmp_errors: true,
//! })?;
//!
//! let probe = Packet::new().push(Tcp::new(50_000, 80).with_flags(tcp_flags::SYN));
//! let replies = exchange
//! .send(&probe, "192.0.2.10".parse()?, Duration::from_millis(500))
//! .await?;
//!
//! for reply in &replies {
//! println!("{} answered {} bytes", reply.source, reply.bytes.len());
//! }
//! # Ok(())
//! # }
//! ```
//!
//! ## The segment stops at Layer 4
//!
//! What goes to [`send`](Exchange::send) is a transport segment: a TCP header
//! and its payload, a UDP datagram, an ICMP message. The IP header is placed by
//! whichever backend the send mode chose, from the destination and the
//! [`Emission`], because that is the seam
//! [`ProbeSender`](crate::transport::probe::ProbeSender) draws and both
//! backends draw it in the same place. A raw socket lets the kernel stamp the
//! header; a link-layer sender builds it along with the frame.
//!
//! So a packet whose *IP header* is wrong on purpose does not go out this way.
//! Everything below that line is reachable: a TCP header claiming a data offset
//! it does not have, a UDP length that counts the wrong bytes, an ICMP message
//! of a type nothing answers. [`Field::Exact`](crate::protocols::craft::Field)
//! is how each of those is written, and none of it is checked on the way past.
//!
//! ## Which replies come back
//!
//! Whatever the capture's filter admitted, in arrival order, until `wait` runs
//! out or [`MAX_REPLIES`] have been collected.
//!
//! They are not narrowed to the address the probe went to, and that is
//! deliberate: an ICMP error comes from a router in the path rather than from
//! the destination, and it is often the only thing that answers. Narrowing by
//! source would drop the most informative reply a probe can draw. What narrows
//! the traffic is the [`ProbeKind`] the exchange was opened with, which is why
//! that stays the caller's to choose.
//!
//! [`capture_counts`](Exchange::capture_counts) says how many frames the kernel
//! discarded before this could read them, which is the difference between a
//! quiet destination and a receive path that could not keep up.
use IpAddr;
use ;
use crateCaptureCounts;
use cratePacket;
use cratePacketError;
use crateSourceResolver;
use crateCapturedSegment;
use crate;
/// The most replies one [`send`](Exchange::send) collects.
///
/// A bound rather than a setting. The capture admits everything its filter
/// matches, which on a busy segment is other people's traffic as well as this
/// probe's answers, and a caller waiting a second for one reply should not be
/// handed a hundred thousand. A caller that wants the whole stream holds a
/// [`ProbeTransport`] and reads it directly.
pub const MAX_REPLIES: usize = 256;
/// What stopped a probe from going out, or from being built at all.
/// One probe out, and what answered.
///
/// Holds the transport, the interface table the source address is chosen from,
/// and the [`Emission`] every probe leaves under. See the module documentation
/// for where the segment it takes stops.