zond-engine 0.18.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
// 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

//! # TLS transport
//!
//! The I/O half of TLS fingerprinting: complete a handshake against an open port
//! and capture the certificate chain the peer presents. Interpreting that chain
//! is the analyzer's job (see [`TlsCertAnalyzer`]); this module only gathers
//! bytes.
//!
//! ## Why we complete a real handshake
//!
//! In TLS 1.3 the server's `Certificate` message is *encrypted*, so a cert
//! cannot be scraped by parsing raw handshake records, the handshake must
//! actually complete. We therefore run a real rustls client, but with a
//! verifier that [accepts any certificate](AcceptAnyServerCert): a scanner
//! wants the *presented* chain, not a trust decision, and the ports we probe
//! routinely serve expired, self-signed, or wrong-host certs that a validating
//! client would reject before we ever see them.
//!
//! ## Crypto provider
//!
//! We pin the pure-Rust **ring** provider rather than rustls's default
//! `aws-lc-rs`, which needs cmake/NASM at build time and is a known Windows-build
//! friction point for a cross-platform product.
//!
//! [`TlsCertAnalyzer`]: super::tls_cert::TlsCertAnalyzer

use std::sync::{Arc, OnceLock};
use std::time::Duration;

use rustls::client::danger::{HandshakeSignatureValid, ServerCertVerified, ServerCertVerifier};
use rustls::pki_types::{CertificateDer, ServerName, UnixTime};
use rustls::{DigitallySignedStruct, SignatureScheme};
use tokio::net::TcpStream;
use tokio::time::timeout;
use tokio_rustls::TlsConnector;

use super::response::TlsInfo;

/// A completed TLS client tunnel over a TCP socket. The transport reads and
/// probes *through* this to fingerprint the protocol carried inside.
pub type TlsTunnel = tokio_rustls::client::TlsStream<TcpStream>;

/// How long to wait for a handshake on a port where we *expect* TLS (an
/// implicit-TLS port). Patient: a handshake is the whole point here, worth
/// waiting out a slow server.
pub(super) const TLS_HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(3);

/// A tighter budget for a *speculative* handshake on a silent, non-standard
/// port. The prior probability of TLS there is low, and a real TLS server on a
/// reachable open port completes well under a second; the extra patience would
/// mostly buy tarpits. Since this is paid on every silent port, it is where
/// latency blast-radius on a many-port host concentrates.
pub(super) const SPECULATIVE_TLS_TIMEOUT: Duration = Duration::from_millis(1_500);

/// Ports that speak TLS immediately on connect (no `STARTTLS` upgrade), where we
/// go straight to a handshake instead of waiting for a plaintext banner that
/// will never come.
const IMPLICIT_TLS_PORTS: &[u16] = &[
    443,  // https
    465,  // smtps
    636,  // ldaps
    989,  // ftps-data
    990,  // ftps
    993,  // imaps
    995,  // pop3s
    2376, // docker over tls
    3269, // ldaps, the Active Directory global catalog
    5061, // sip-tls
    5671, // amqps
    5986, // winrm https
    6697, // ircs
    8443, // https-alt
    8883, // mqtts
];

/// Whether `port` is a well-known implicit-TLS port.
pub fn is_tls_port(port: u16) -> bool {
    IMPLICIT_TLS_PORTS.contains(&port)
}

/// A certificate verifier that accepts everything.
///
/// Sound **only** because we are fingerprinting, not establishing a trusted
/// channel: we complete the handshake purely to read the presented chain and
/// send no sensitive data over it. Never reuse this config for a real client.
#[derive(Debug)]
struct AcceptAnyServerCert;

impl ServerCertVerifier for AcceptAnyServerCert {
    fn verify_server_cert(
        &self,
        _end_entity: &CertificateDer<'_>,
        _intermediates: &[CertificateDer<'_>],
        _server_name: &ServerName<'_>,
        _ocsp_response: &[u8],
        _now: UnixTime,
    ) -> Result<ServerCertVerified, rustls::Error> {
        Ok(ServerCertVerified::assertion())
    }

    fn verify_tls12_signature(
        &self,
        _message: &[u8],
        _cert: &CertificateDer<'_>,
        _dss: &DigitallySignedStruct,
    ) -> Result<HandshakeSignatureValid, rustls::Error> {
        Ok(HandshakeSignatureValid::assertion())
    }

    fn verify_tls13_signature(
        &self,
        _message: &[u8],
        _cert: &CertificateDer<'_>,
        _dss: &DigitallySignedStruct,
    ) -> Result<HandshakeSignatureValid, rustls::Error> {
        Ok(HandshakeSignatureValid::assertion())
    }

    fn supported_verify_schemes(&self) -> Vec<SignatureScheme> {
        // Advertise the common schemes so servers pick one we will "verify".
        vec![
            SignatureScheme::RSA_PKCS1_SHA256,
            SignatureScheme::RSA_PKCS1_SHA384,
            SignatureScheme::RSA_PKCS1_SHA512,
            SignatureScheme::ECDSA_NISTP256_SHA256,
            SignatureScheme::ECDSA_NISTP384_SHA384,
            SignatureScheme::ECDSA_NISTP521_SHA512,
            SignatureScheme::RSA_PSS_SHA256,
            SignatureScheme::RSA_PSS_SHA384,
            SignatureScheme::RSA_PSS_SHA512,
            SignatureScheme::ED25519,
        ]
    }
}

/// The process-wide connector, built once. The rustls config is immutable and
/// internally reference-counted, so every handshake shares it cheaply.
fn connector() -> &'static TlsConnector {
    static CONNECTOR: OnceLock<TlsConnector> = OnceLock::new();
    CONNECTOR.get_or_init(|| {
        let config = rustls::ClientConfig::builder_with_provider(Arc::new(
            rustls::crypto::ring::default_provider(),
        ))
        .with_safe_default_protocol_versions()
        .expect("ring provider supports the default TLS versions")
        .dangerous()
        .with_custom_certificate_verifier(Arc::new(AcceptAnyServerCert))
        .with_no_client_auth();
        TlsConnector::from(Arc::new(config))
    })
}

/// Handshake on a port where TLS is *expected*, an implicit-TLS port. Patient
/// (see [`TLS_HANDSHAKE_TIMEOUT`]).
pub async fn handshake(
    stream: TcpStream,
    server: ServerName<'static>,
) -> Option<(TlsTunnel, TlsInfo)> {
    handshake_within(stream, server, TLS_HANDSHAKE_TIMEOUT).await
}

/// *Speculative* handshake on a silent, un-probed port that might be TLS on a
/// non-standard port. Tighter budget (see [`SPECULATIVE_TLS_TIMEOUT`]) because
/// the prior is low and this cost is paid on every silent port.
pub async fn speculative_handshake(
    stream: TcpStream,
    server: ServerName<'static>,
) -> Option<(TlsTunnel, TlsInfo)> {
    handshake_within(stream, server, SPECULATIVE_TLS_TIMEOUT).await
}

/// Completes a TLS handshake over `stream` within `budget`, which allows for
/// the path (see [`on_path`](super::on_path)), returning the live tunnel and
/// the certificate chain the peer presented (owned DER).
///
/// `server` is who the handshake asks for, from
/// [`Authority::server_name`](super::authority::Authority::server_name): the
/// name a target reached the address by, which goes on the wire as the server
/// name indication, or the address, which puts none there. A server holding
/// several sites at one address picks the certificate by it, and one keeping
/// no certificate for a nameless client refuses the handshake without it, so
/// the name is what reaches the site the target named. Without one, what comes
/// back is whatever certificate the default site serves. The accept-any
/// verifier means the name never decides whether the handshake completes on
/// this side. The tunnel is returned so the caller can re-probe *through* it;
/// the certificate may be empty (anonymous handshake) without failing. Returns
/// `None` only on timeout or handshake failure.
async fn handshake_within(
    stream: TcpStream,
    server: ServerName<'static>,
    budget: Duration,
) -> Option<(TlsTunnel, TlsInfo)> {
    let connect = connector().connect(server, stream);

    let given = super::on_path(budget);
    let Ok(done) = timeout(given, connect).await else {
        // A handshake with no answer in time, which the identification is
        // told as it is told a read that heard nothing.
        super::tell(|tally| tally.ran_out(given));
        return None;
    };
    let tls = done.ok()?;

    let connection = tls.get_ref().1;

    let certificates: Vec<Vec<u8>> = connection
        .peer_certificates()
        .unwrap_or(&[])
        .iter()
        .map(|der| der.as_ref().to_vec())
        .collect();

    // Read off the live connection: these are gone the moment the tunnel is.
    let version = protocol_version_name(connection.protocol_version());
    let cipher_suite = connection
        .negotiated_cipher_suite()
        .and_then(|suite| suite.suite().as_str());
    let alpn = connection
        .alpn_protocol()
        .map(|protocol| String::from_utf8_lossy(protocol).into_owned());

    Some((
        tls,
        TlsInfo {
            certificates,
            version,
            cipher_suite,
            alpn,
        },
    ))
}

/// How long to wait on the legacy probe.
///
/// Reached only after a modern handshake has already failed on this port, so it
/// is paid on a port that has otherwise been given up on. A server old enough to
/// need it is old enough to answer promptly.
pub(super) const LEGACY_PROBE_TIMEOUT: Duration = Duration::from_millis(1_500);

/// A ClientHello offering the versions rustls will not.
///
/// Fixed bytes, because everything in it is a constant: TLS 1.0, six RSA and
/// 3DES suites a legacy server actually implements, null compression, and **no
/// extension block at all**. A hello with no extensions is what an SSLv3-era
/// stack expects, and it is what keeps this free of the negotiation a modern
/// handshake needs. The random is fixed too; nothing here is a security context,
/// only a question.
const LEGACY_CLIENT_HELLO: &[u8] = &[
    // Record: handshake, TLS 1.0, 55 bytes.
    // Handshake: client hello, 51 bytes, offering TLS 1.0.
    // Then a fixed 32-byte random, no session to resume, six cipher suites a
    // legacy server actually implements, and null compression.
    0x16, 0x03, 0x01, 0x00, 0x37, 0x01, 0x00, 0x00, 0x33, 0x03, 0x01, 0x5a, 0x0d, 0x00, 0x00, 0x5a,
    0x0d, 0x00, 0x00, 0x5a, 0x0d, 0x00, 0x00, 0x5a, 0x0d, 0x00, 0x00, 0x5a, 0x0d, 0x00, 0x00, 0x5a,
    0x0d, 0x00, 0x00, 0x5a, 0x0d, 0x00, 0x00, 0x5a, 0x0d, 0x00, 0x00, 0x00, 0x00, 0x0c, 0x00, 0x2f,
    0x00, 0x35, 0x00, 0x0a, 0x00, 0x05, 0x00, 0x3c, 0x00, 0x3d, 0x01, 0x00,
];

/// What a peer that refused a modern handshake turns out to speak.
///
/// rustls implements TLS 1.2 and 1.3 and implements neither 1.0
/// nor 1.1, so a server offering only the older versions fails
/// [`handshake`] and, without this, is reported as a port that answered nothing
/// at all. For a security scanner that is the wrong way round: "this host still
/// negotiates TLS 1.0" is among the most actionable single facts a scan can
/// report, and it is the one configuration the modern handshake cannot see.
///
/// One ClientHello and the version out of the answer. No tunnel comes back and
/// none is wanted, the finding *is* the version, and nothing is worth carrying
/// over a channel this weak anyway.
///
/// `None` where the peer said nothing, or said something that is not TLS. A
/// server that answers with an alert spoke TLS and refused these terms, which is
/// itself an answer and is reported as [`REFUSED`].
pub async fn legacy_version(stream: TcpStream) -> Option<&'static str> {
    timeout(
        super::on_path(LEGACY_PROBE_TIMEOUT),
        legacy_exchange(stream),
    )
    .await
    .unwrap_or_default()
}

/// What a peer speaking TLS says when it will not accept the terms offered.
///
/// Recorded rather than discarded: it establishes the port speaks TLS, which is
/// more than a scan that gave up on it knew, even though it leaves the version
/// unsettled.
pub const REFUSED: &str = "TLS (version not established)";

/// Sends [`LEGACY_CLIENT_HELLO`] and reads the version out of the answer.
async fn legacy_exchange(mut stream: TcpStream) -> Option<&'static str> {
    use tokio::io::{AsyncReadExt, AsyncWriteExt};

    stream.write_all(LEGACY_CLIENT_HELLO).await.ok()?;

    // A ServerHello is small and this reads the first record and no more. The
    // buffer is the largest a record header can promise for the part that
    // matters; nothing beyond the version is read, so nothing beyond it is kept.
    let mut buffer = [0u8; 128];
    let read = stream.read(&mut buffer).await.ok()?;
    server_version(&buffer[..read])
}

/// The version a TLS server named in its first record, or [`REFUSED`] where it
/// answered with an alert.
///
/// Every offset is checked against what actually arrived: these bytes are a
/// remote host's and the walk must terminate on any input rather than merely on
/// a well-formed one.
///
/// ```text
/// 16 03 01 00 4a | 02 00 00 46 | 03 01 | ...
/// └── record ──┘ └─ handshake ┘ └ version
/// ```
fn server_version(record: &[u8]) -> Option<&'static str> {
    // Record header: content type, version, length. The record's own version is
    // not the answer: servers write the negotiated one in the ServerHello and
    // a conservative one here.
    let content_type = *record.first()?;

    // An alert is a peer speaking TLS and declining the terms. It settles that
    // the port speaks TLS and nothing more.
    if content_type == 0x15 {
        return Some(REFUSED);
    }
    if content_type != 0x16 {
        return None; // not a TLS record at all
    }

    // Handshake header: type, three-byte length, then the version.
    let body = record.get(5..)?;
    if *body.first()? != 0x02 {
        return None; // a handshake, but not a ServerHello
    }
    let version = body.get(4..6)?;
    version_name(u16::from_be_bytes([version[0], version[1]]))
}

/// The name a version number goes by, for the versions worth naming.
fn version_name(version: u16) -> Option<&'static str> {
    match version {
        0x0300 => Some("SSLv3"),
        0x0301 => Some("TLSv1.0"),
        0x0302 => Some("TLSv1.1"),
        // A server that answers this hello with 1.2 was reachable by the modern
        // connector and something else stopped it. Named honestly rather than
        // filed under a version this probe did not establish.
        0x0303 => Some("TLSv1.2"),
        _ => None,
    }
}

/// The negotiated version under the name the RFCs give it.
///
/// Spelled out rather than taken from `Debug`, which renders `TLSv1_3`, a
/// string no reader of a report expects and no other tool prints. Only the two
/// versions [`connector`] offers are named; anything else is reported as
/// unknown rather than guessed at.
fn protocol_version_name(version: Option<rustls::ProtocolVersion>) -> Option<&'static str> {
    match version? {
        rustls::ProtocolVersion::TLSv1_3 => Some("TLSv1.3"),
        rustls::ProtocolVersion::TLSv1_2 => Some("TLSv1.2"),
        _ => None,
    }
}

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

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn implicit_tls_ports_are_recognised() {
        assert!(is_tls_port(443));
        assert!(is_tls_port(993));
        assert!(!is_tls_port(80));
        assert!(!is_tls_port(22));
    }

    /// A server that speaks only TLS 1.0 is a finding, not a silence.
    ///
    /// rustls implements 1.2 and 1.3 and implements neither 1.0
    /// nor 1.1, so such a server fails the modern handshake. Without this probe
    /// it would be reported as a port that answered nothing, which loses the
    /// identification and the finding together, and "this host still negotiates
    /// TLS 1.0" is among the most actionable things a scan can say.
    #[test]
    fn a_legacy_server_hello_names_its_version() {
        // Record header, then a ServerHello naming the version.
        let hello = |version: [u8; 2]| {
            let mut record = vec![0x16, 0x03, 0x01, 0x00, 0x4a, 0x02, 0x00, 0x00, 0x46];
            record.extend_from_slice(&version);
            record.extend_from_slice(&[0u8; 32]); // random
            record
        };

        assert_eq!(server_version(&hello([0x03, 0x00])), Some("SSLv3"));
        assert_eq!(server_version(&hello([0x03, 0x01])), Some("TLSv1.0"));
        assert_eq!(server_version(&hello([0x03, 0x02])), Some("TLSv1.1"));
        assert_eq!(server_version(&hello([0x03, 0x03])), Some("TLSv1.2"));
        assert_eq!(server_version(&hello([0x03, 0x09])), None, "not a version");
    }

    /// An alert is a peer speaking TLS and declining these terms, which settles
    /// that the port speaks TLS and nothing more. Reported as exactly that.
    #[test]
    fn an_alert_establishes_tls_without_establishing_a_version() {
        // Alert, TLS 1.0, two bytes: fatal, handshake_failure.
        assert_eq!(
            server_version(&[0x15, 0x03, 0x01, 0x00, 0x02, 0x02, 0x28]),
            Some(REFUSED)
        );
    }

    /// Anything that is not a TLS record names nothing, and a truncated one is
    /// refused rather than read past.
    #[test]
    fn what_is_not_a_server_hello_names_nothing() {
        assert_eq!(server_version(b"HTTP/1.1 200 OK"), None);
        assert_eq!(server_version(b"SSH-2.0-OpenSSH_9.6p1"), None);
        assert_eq!(server_version(&[]), None);
        // A well-formed record header with nothing behind it.
        assert_eq!(server_version(&[0x16, 0x03, 0x01, 0x00, 0x4a]), None);
        // A handshake that is not a ServerHello.
        assert_eq!(
            server_version(&[0x16, 0x03, 0x01, 0x00, 0x04, 0x01, 0x00, 0x00, 0x00]),
            None
        );
        // A ServerHello cut off before its version.
        assert_eq!(
            server_version(&[0x16, 0x03, 0x01, 0x00, 0x04, 0x02, 0x00, 0x00, 0x46]),
            None
        );
    }

    /// The hello is a fixed record and its own length fields have to agree with
    /// it, or a server drops it without a word and the port reads as silent.
    #[test]
    fn the_client_hello_declares_its_own_length_correctly() {
        let record_length = u16::from_be_bytes([LEGACY_CLIENT_HELLO[3], LEGACY_CLIENT_HELLO[4]]);
        assert_eq!(
            usize::from(record_length),
            LEGACY_CLIENT_HELLO.len() - 5,
            "the record length must count everything after the header"
        );

        let handshake_length = u32::from_be_bytes([
            0,
            LEGACY_CLIENT_HELLO[6],
            LEGACY_CLIENT_HELLO[7],
            LEGACY_CLIENT_HELLO[8],
        ]);
        assert_eq!(
            handshake_length as usize,
            LEGACY_CLIENT_HELLO.len() - 9,
            "the handshake length must count everything after its own header"
        );
        assert_eq!(LEGACY_CLIENT_HELLO[0], 0x16, "a handshake record");
        assert_eq!(LEGACY_CLIENT_HELLO[5], 0x01, "a client hello");
    }

    proptest::proptest! {
        /// These bytes come off a socket a scanner opened to a stranger, so the
        /// walk has to terminate on any input rather than merely on a well-formed
        /// one.
        #[test]
        fn the_version_walk_never_panics(record in proptest::collection::vec(proptest::prelude::any::<u8>(), 0..256)) {
            let _ = server_version(&record);
        }
    }

    #[test]
    fn connector_builds_with_ring_provider() {
        // Exercises the accept-any config + ring provider path; a panic here
        // would mean the process cannot perform any TLS fingerprinting.
        let _ = connector();
    }
}