zond-engine 0.17.0

The core networking library powering Zond. Raw packet injection, protocol parsing, service and OS fingerprinting, and asynchronous network scanning.
Documentation
// 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 the unprivileged paths cannot measure for themselves
//!
//! The timeouts and concurrency ceilings every TCP-connect path runs against.
//! The connect port scanner, the connect discovery sweep, the service-detection
//! pass and the detection tiers all open the same kind of connection for the
//! same purpose, so they share one set of numbers. Spelled separately in each,
//! a budget gets tuned in one place and left behind in the others, and nothing
//! reports the disagreement.
//!
//! Only the connect paths need constants at all. A raw scanner measures the
//! round trips it is getting and sizes its own patience from them, through
//! [`AdaptiveDeadline`](crate::scanner::pacing::deadline::AdaptiveDeadline). A
//! connect probe cannot: it sends one SYN, the kernel owns the retransmission,
//! and the scanner never sees a round trip it could learn from. Its numbers come
//! from what the protocol guarantees instead, and each one below says which
//! guarantee.

use std::time::Duration;

/// How long a single TCP connect probe waits before treating silence as a drop.
/// Shared by the connect port and host scanners and by the service-detection
/// connect, which all open the same kind of connection for the same purpose.
///
/// The value is set against **the host stack's first SYN retransmission**, and
/// that is the only thing that decides it. A connect probe sends one SYN and has
/// no retransmission of its own: the operating system's is the only second
/// attempt it gets, and RFC 6298 puts the initial retransmission timeout at one
/// second, which is what Linux and the BSDs both use. A budget at or below a
/// second therefore expires while that retransmission is still in flight, and
/// every host that ignores a first SYN - a rate limiter, a busy embedded stack,
/// any of the SYN-flood mitigations common in consumer routers - is reported
/// `Filtered` when it is merely slow to answer the first time. That failure is
/// silent, total, and looks exactly like a firewall.
///
/// So it sits above one second by enough to cover a round trip on top, and well
/// below three, where the *second* retransmission would arrive: one extra
/// attempt is worth waiting for, a third is a scan that has stopped being a
/// scan. What it costs is half a second per genuinely filtered port, paid only
/// on the unprivileged path, which is the right way round - the raw scanners
/// retransmit for themselves and size their own patience from measured round
/// trips.
///
/// A refusal has to arrive inside the same budget. Unix stacks report one at
/// the first reset. Windows resends a refused SYN until its SYN retransmissions
/// run out, which at its default count outlasts this budget, so there every
/// connection the engine makes keeps only the one retransmission this value
/// waits for.
pub const CONNECT_PROBE_TIMEOUT: Duration = Duration::from_millis(1500);

/// The initial retransmission timeout a host TCP stack uses for a SYN
/// (RFC 6298 §2.1), which [`CONNECT_PROBE_TIMEOUT`] has to outlive.
#[cfg(test)]
const HOST_SYN_RETRANSMIT: Duration = Duration::from_secs(1);

/// How many targets the connect port scan and the passes after it (service
/// detection, detections, TLS enumeration) work on at once.
///
/// A pace, not a guard on the socket table. What keeps the process's table
/// from filling is its descriptor budget, what the soft file limit leaves
/// once a reserve for the rest of the process is set aside, which every
/// connection a scan opens takes a share of before its socket and waits
/// for when there is none; a table full for other reasons is waited out
/// rather than read as the target's answer. This is how many conversations a
/// pass keeps going, enough that a wide scan is not queued one port deep and
/// few enough that one host is not asked fifty things at the same instant.
pub const CONNECT_CONCURRENCY: usize = 50;

/// How many of one port's detection flows run at once.
///
/// A port's flows are independent conversations that happen to share an address,
/// and an HTTP port attracts dozens of them: forty-seven against the built-in
/// corpus, forty-three of them asking a different question, so a shared reply
/// cache collapses almost none of it. Run one after another that is forty-seven
/// round trips in a row, and a host 140ms away spends ten seconds on detections
/// for a scan whose ports were settled in one.
///
/// It does not raise what a scan opens at once. [`CONNECT_CONCURRENCY`] is still
/// the ceiling on sockets in flight, held by the gate the detection phase
/// acquires a probe through, so this changes how that budget is spent rather
/// than how large it is: it keeps a scan of one host with four web ports from
/// queueing its work one deep, and leaves a scan of two hundred doing the same
/// total work it would one flow at a time.
pub const DETECTION_FLOW_CONCURRENCY: usize = 8;

/// How many connect probes the unprivileged discovery sweep keeps in flight.
/// Far higher than [`CONNECT_CONCURRENCY`] because each probe is a bare liveness
/// check against a handful of ports, not a full fingerprint conversation.
///
/// A ceiling, and not always the one that binds. Each probe in flight holds a
/// socket, and the process may hold only so many: every connect probe takes its
/// socket from a budget of half the process's descriptor limit, less under a
/// very small one, shared by every scan the process runs, so a shell's default
/// of 256 or 1,024 holds a sweep below this and slows it rather than letting
/// it lose the addresses it has no socket for.
pub const DISCOVERY_CONCURRENCY: usize = 2048;

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

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

    /// The boundary the connect budget must stay clear of, and the reason it is
    /// the value it is.
    ///
    /// A connect probe sends one SYN; the host stack's retransmission is the
    /// only second attempt it gets. Set at or below that boundary, the budget
    /// expires while the answer is in flight and reports a live, refusing host
    /// as filtered - measured against a router that ignores a first SYN and
    /// answers the retransmission, where the refusal lands at 1.01 s to 1.04 s
    /// and a one-second budget missed every one of them.
    ///
    /// The upper bound matters too: past the second retransmission the probe is
    /// waiting for an attempt nobody should wait for.
    #[test]
    fn a_connect_probe_outlives_one_host_retransmission_and_not_two() {
        assert!(
            CONNECT_PROBE_TIMEOUT > HOST_SYN_RETRANSMIT,
            "a budget of {CONNECT_PROBE_TIMEOUT:?} expires while the host stack's \
             retransmission is still in flight, and reports refusing hosts as filtered"
        );
        assert!(
            CONNECT_PROBE_TIMEOUT < HOST_SYN_RETRANSMIT * 3,
            "a budget of {CONNECT_PROBE_TIMEOUT:?} waits for a second retransmission"
        );
    }
}