zond-engine 0.13.0

A lightweight, fast, and highly concurrent networking backend for packet crafting, protocol fingerprinting, and host discovery.
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

//! # Raw Transport-Layer Sockets (Send Path)
//!
//! Wraps `pnet`'s raw transport-layer (Layer 4) sockets for *sending* probes,
//! so async scanning code never touches the blocking socket API directly.
//!
//! This module deliberately opens no receiver. Receiving TCP/UDP over a raw
//! socket works on Linux but is silently dead on macOS/BSD, whose kernels
//! never deliver those protocols to raw sockets - so replies are captured at
//! the link layer via [`crate::transport::capture`] instead, and every scanner
//! pairs this send-only handle with that capture through
//! [`crate::transport::probe::ProbeTransport`].
//!
//! A raw socket is bound to one address family: an IPv4 socket can neither
//! send to nor receive from an IPv6 destination, and vice versa. TCP scanning
//! needs both, since targets can be either, so [`open_sender`] opens one
//! socket per address family for [`TransportType::TcpLayer4`].
//! [`TransportType::UdpLayer4`] stays IPv4-only, since nothing in this crate
//! currently needs UDP over IPv6. [`TransportType::IcmpLayer4`] opens both, and
//! is the only way this crate can put an ICMP message on the wire for a host it
//! cannot reach at the link layer — the echo builders in
//! [`crate::protocols::icmp`] emit whole Ethernet frames and therefore need a
//! neighbour.

use std::net::IpAddr;
use std::sync::{Arc, Mutex};

use anyhow::Context;
use pnet::{
    packet::{Packet, ip::IpNextHeaderProtocols},
    transport::{
        self, TransportChannelType, TransportProtocol, TransportReceiver, TransportSender,
    },
};

const TRANSPORT_BUFFER_SIZE: usize = 4096;
const CHANNEL_TYPE_UDP_V4: TransportChannelType =
    TransportChannelType::Layer4(TransportProtocol::Ipv4(IpNextHeaderProtocols::Udp));
const CHANNEL_TYPE_TCP_V4: TransportChannelType =
    TransportChannelType::Layer4(TransportProtocol::Ipv4(IpNextHeaderProtocols::Tcp));
const CHANNEL_TYPE_TCP_V6: TransportChannelType =
    TransportChannelType::Layer4(TransportProtocol::Ipv6(IpNextHeaderProtocols::Tcp));
const CHANNEL_TYPE_ICMP_V4: TransportChannelType =
    TransportChannelType::Layer4(TransportProtocol::Ipv4(IpNextHeaderProtocols::Icmp));
const CHANNEL_TYPE_ICMP_V6: TransportChannelType =
    TransportChannelType::Layer4(TransportProtocol::Ipv6(IpNextHeaderProtocols::Icmpv6));

/// Which transport-layer protocol, and address family coverage, to open a capture for.
#[derive(Debug, Clone, Copy)]
pub enum TransportType {
    /// Raw TCP segments, over both IPv4 and IPv6 where available.
    TcpLayer4,
    /// Raw UDP datagrams, over IPv4 only.
    UdpLayer4,
    /// Raw ICMP messages, over both IPv4 and IPv6 where available.
    ///
    /// The two families are **different protocols**, not one protocol over two
    /// address sizes: ICMP is next-header 1 and ICMPv6 is 58, they number their
    /// message types differently, and ICMPv6 checksums cover a pseudo-header
    /// while ICMPv4 checksums cover the message alone. A caller therefore builds
    /// a different message per family, and this opens a socket for each.
    ///
    /// This is the only path by which this crate can send an ICMP message to a
    /// host that is not on the local segment. The echo builders in
    /// [`protocols::icmp`] produce whole Ethernet frames, which need a
    /// destination hardware address and so only reach an on-link neighbour.
    ///
    /// [`protocols::icmp`]: crate::protocols::icmp
    IcmpLayer4,
}

/// Routes an outgoing packet to whichever underlying raw socket matches its
/// destination's address family.
///
/// A [`TransportType::UdpLayer4`] handle only ever has an IPv4 sender, so
/// sending to an IPv6 destination through it fails with a clear error rather
/// than silently doing nothing.
pub struct TransportSenderHandle {
    v4: Option<Arc<Mutex<Socket>>>,
    v6: Option<Arc<Mutex<Socket>>>,
}

/// One raw socket, and the hop limit currently set on it.
///
/// The two travel under one lock because they have to be changed together: a
/// hop limit is socket state, not packet state, so setting it and sending are
/// one operation and a second thread must not send in between.
struct Socket {
    sender: TransportSender,
    /// What `IP_TTL` (or `IPV6_UNICAST_HOPS`) was last set to on this socket,
    /// or `None` before anything set it.
    ///
    /// Tracked so that a scan sending millions of probes at one hop limit pays
    /// for one `setsockopt` rather than one per probe. It starts as `None`
    /// rather than as this engine's default, so the first send states the value
    /// explicitly instead of trusting a kernel default that is only usually 64 —
    /// a host tuned otherwise would silently send probes that expire early, and
    /// an expired probe is indistinguishable from a host that did not answer.
    hop_limit: Option<u8>,
}

impl Socket {
    fn new(sender: TransportSender) -> Arc<Mutex<Self>> {
        Arc::new(Mutex::new(Self {
            sender,
            hop_limit: None,
        }))
    }
}

impl TransportSenderHandle {
    /// Sends `packet` to `destination`, expiring after `hop_limit` routers.
    ///
    /// The hop limit is applied to the socket rather than written into the
    /// packet, because a Layer-4 socket has the kernel build the IP header and
    /// there is no header here to write it into. That makes it *sticky*, which
    /// is why the value in force is tracked alongside the socket: what a caller
    /// asks for is what goes out, whatever the previous send asked for.
    pub fn send_to<T: Packet>(
        &self,
        packet: T,
        destination: IpAddr,
        hop_limit: u8,
    ) -> anyhow::Result<usize> {
        let socket = match destination {
            IpAddr::V4(_) => self.v4.as_ref(),
            IpAddr::V6(_) => self.v6.as_ref(),
        }
        .with_context(|| format!("no open transport socket for {destination}'s address family"))?;

        let mut socket = socket.lock().unwrap();

        if socket.hop_limit != Some(hop_limit) {
            socket
                .sender
                .set_ttl(hop_limit)
                .with_context(|| format!("failed to set a hop limit of {hop_limit}"))?;
            socket.hop_limit = Some(hop_limit);
        }

        socket
            .sender
            .send_to(packet, destination)
            .with_context(|| format!("failed to send to {destination}"))
    }
}

/// Opens only the outgoing half of a raw transport capture: the raw
/// socket(s) needed to *send* segments, with no receiver threads.
///
/// Sending over a raw Layer-4 socket works on every supported OS - it's only
/// *receiving* TCP/UDP this way that BSD-derived kernels refuse - so the
/// [`RawIpSender`](crate::transport::probe::RawIpSender) pairs this send-only
/// handle with a `libpcap` capture for replies instead of the (silently dead
/// on macOS) raw-socket receiver.
pub fn open_sender(transport_type: TransportType) -> anyhow::Result<TransportSenderHandle> {
    match transport_type {
        TransportType::TcpLayer4 => {
            let (v4_tx, _v4_rx) = open_channel(CHANNEL_TYPE_TCP_V4)?;
            // IPv6 raw sockets aren't available on every host; TCP scanning
            // still works over IPv4 alone, so a failure here isn't fatal.
            let v6 = open_channel(CHANNEL_TYPE_TCP_V6)
                .ok()
                .map(|(v6_tx, _v6_rx)| Socket::new(v6_tx));
            Ok(TransportSenderHandle {
                v4: Some(Socket::new(v4_tx)),
                v6,
            })
        }
        TransportType::UdpLayer4 => {
            let (v4_tx, _v4_rx) = open_channel(CHANNEL_TYPE_UDP_V4)?;
            Ok(TransportSenderHandle {
                v4: Some(Socket::new(v4_tx)),
                v6: None,
            })
        }
        TransportType::IcmpLayer4 => {
            let (v4_tx, _v4_rx) = open_channel(CHANNEL_TYPE_ICMP_V4)?;
            // Same reasoning as TCP: a host without IPv6 raw sockets can still
            // be probed over IPv4, so a failure here is a narrower transport
            // rather than no transport.
            let v6 = open_channel(CHANNEL_TYPE_ICMP_V6)
                .ok()
                .map(|(v6_tx, _v6_rx)| Socket::new(v6_tx));
            Ok(TransportSenderHandle {
                v4: Some(Socket::new(v4_tx)),
                v6,
            })
        }
    }
}

fn open_channel(
    channel_type: TransportChannelType,
) -> anyhow::Result<(TransportSender, TransportReceiver)> {
    let (tx, rx) = transport::transport_channel(TRANSPORT_BUFFER_SIZE, channel_type)?;
    Ok((tx, rx))
}