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
// 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 a scanning strategy is
//!
//! Two traits, one per phase, and the error a strategy fails with.
//! [`discover`](crate::scanner::discover) and [`scan`](crate::scanner::scan)
//! know nothing about any strategy beyond these methods.
//!
//! ## How the submodules are arranged
//!
//! By the phase a strategy serves, which is the same axis
//! [`ScanKind`](crate::report::ScanKind) and
//! [`PhaseRecorder`](crate::scanner::recorder::PhaseRecorder) are written in.
//! Transport and privilege vary *inside* a category rather than naming one,
//! because varying over them is what these two traits are for.
//!
//! | module | what it is |
//! |---|---|
//! | [`local`], [`routed`], [`connect`] | which hosts are there: at the link layer, through a gateway, or by ordinary connect |
//! | [`ports`] | which ports are open |
//! | [`identify`] | what a machine is, asked of hosts already found |
//! | [`topology`] | what is between here and a host |
//! | [`passive`] | what a link already carries, having sent nothing |
//! | [`composite`] | routes each target to a strategy that covers its protocol |
//! | `raw`, `frames`, `icmp_error`, `sweep` | not strategies, and internal: what they are built from, what they read, and what they all keep track of |
//!
//! Arranged by the target's network position instead, the two axes cross:
//! `routed` would mean "reached through a gateway" for one strategy and "opens a
//! raw socket" for the ten others that would sit underneath it, including every
//! port scanner, both operating-system probes and the trace. What each of them
//! *is* decides where it sits.
//!
//! ## Findings go to the context, not to the return value
//!
//! Neither trait returns what it found. A strategy writes hosts and ports into
//! the [`ScanContext`] it was built with, and its run method reports only
//! whether the attempt itself got to the end. That is what makes an ARP sweep,
//! a raw SYN scan and a plain TCP connect interchangeable to a caller: build
//! one, run it, read the store, and it is what lets several unrelated
//! strategies write into a single live view while they are still running, which
//! a return value cannot do.
//!
//! It also draws the line between the two ways a scan goes wrong. A target that
//! did not answer is a *finding*, and it lands in the store. A strategy that
//! could not open its socket is a *failure*, and it comes back as
//! [`StrategyError`]. Only the second is an `Err`, because only the second means
//! the absence of hosts proves nothing.
//!
//! ## The two traits are the same shape
//!
//! Both carry a [`kind`](HostScanner::kind), both take `&mut self`, both return
//! `Result<(), StrategyError>`. Where they differ they differ for a reason:
//! a [`PortScanner`] is fed its targets on a channel and declares which
//! protocols it covers, because several of them run at once and something has
//! to route each target to one that can take it; a [`HostScanner`] owns its
//! targets from construction, because a sweep is aimed at a segment rather than
//! dispatched a target at a time.
//!
//! Neither consumes `self`. A strategy runs once in practice, but taking
//! `self: Box<Self>` to say so would force every caller to box a scanner it
//! already owns, and the orchestrator is not the only caller.

use async_trait::async_trait;
use tokio::sync::mpsc;

use crate::journal::settle::Outcome;
use crate::model::port::{PortState, Protocol};
use crate::model::target::PlannedTarget;
use crate::report::ScannerKind;
use crate::scanner::session::ScanContext;

/// Why one scanning strategy could not start, or could not finish.
///
/// This is not how a scan fails. A scan runs several strategies and carries
/// on with whatever survives, so one of these is recorded in the report's
/// [`failures`](crate::report::ScanReport::failures) and announced on
/// the event stream rather than returned from
/// [`discover`](crate::scanner::discover) or [`scan`](crate::scanner::scan). It
/// reaches a caller directly when they build and run a strategy themselves.
///
/// The variants are the layers a strategy is assembled from, because that is
/// what determines whether anything can be done about it. A [`Transport`],
/// [`Channel`] or [`Capture`] failure is most often missing privileges, which
/// the same unprivileged fallback answers for a scan, though not always, and
/// the capture error underneath says which; an [`Interface`] failure is about
/// one interface and the scan of every other one is unaffected.
///
/// [`Transport`]: StrategyError::Transport
/// [`Channel`]: StrategyError::Channel
/// [`Capture`]: StrategyError::Capture
/// [`Interface`]: StrategyError::Interface
#[non_exhaustive]
#[derive(Debug, thiserror::Error)]
pub enum StrategyError {
    /// The raw probe transport could not be opened.
    #[error(transparent)]
    Transport(#[from] crate::transport::probe::TransportError),

    /// The link-layer channel a local sweep needs could not be opened.
    #[error(transparent)]
    Channel(#[from] crate::transport::channel::ChannelError),

    /// Nothing could be captured on the links a listener was given.
    ///
    /// The capture's own error, whole, because a listener has nothing else to
    /// fail at and that error already names each link and what refused it.
    #[error(transparent)]
    Capture(#[from] crate::transport::capture::CaptureError),

    /// The interface this strategy was given cannot be probed from.
    #[error("{interface} cannot be probed from: {reason}")]
    Interface {
        /// The interface in question.
        interface: String,
        /// What is missing.
        reason: &'static str,
    },

    /// The transport a port scan was handed was opened for another kind of
    /// probe, so its capture would admit none of the scan's answers.
    ///
    /// Refused rather than run, because a scan that hears nothing files every
    /// port as the silence it reads, which looks exactly like a filtered
    /// network. Every port it was handed is recorded as one nobody asked about.
    #[error(
        "{} transport cannot hear {} port scan's answers",
        .kind.spoken(),
        spoken_protocol(*.protocol)
    )]
    MismatchedTransport {
        /// The kind the transport was opened for.
        kind: crate::transport::probe::ProbeKind,
        /// The protocol of the port scan it was handed to.
        protocol: crate::model::port::Protocol,
    },

    /// The strategy's probes could not be built. A bug or an impossible target
    /// rather than an environment problem, since a probe is built from values
    /// this engine chose.
    #[error("the probes for this strategy could not be built: {0}")]
    Probe(String),

    /// A strategy panicked.
    ///
    /// Always a bug in the engine, never a fact about the network, and reported
    /// rather than swallowed: the task it killed would otherwise take the
    /// evidence with it, and the scan would look merely empty.
    #[error("the {scanner:?} scanner panicked: {detail}")]
    Panicked {
        /// Which strategy went down.
        scanner: ScannerKind,
        /// What the runtime said about it.
        detail: String,
    },
}

/// A port scan's protocol in words, with its article, as
/// [`StrategyError::MismatchedTransport`] names the scan it was handed.
const fn spoken_protocol(protocol: crate::model::port::Protocol) -> &'static str {
    use crate::model::port::Protocol;
    match protocol {
        Protocol::Tcp => "a TCP",
        Protocol::Udp => "a UDP",
        Protocol::Sctp => "an SCTP",
    }
}

/// A strategy that finds which hosts, among the targets it was built with, are
/// reachable.
///
/// The discovery half of the pair. Implementations differ entirely in how they
/// ask, ARP and ICMPv6 on a local segment, raw TCP SYN through a gateway, an
/// ordinary connect attempt where neither is possible, and not at all in what a
/// caller does with them.
#[async_trait]
pub trait HostScanner: Send {
    /// Identifies the strategy, so a failure can be attributed to it in the
    /// report and on the event stream.
    fn kind(&self) -> ScannerKind;

    /// Probes every target this strategy owns and records what answered in the
    /// shared store.
    ///
    /// Returns `Ok` when the run reached its end, including an end forced by
    /// [`ScanHandle::abort`](crate::scanner::handle::ScanHandle::abort), and
    /// `Err` only when the strategy itself could not do its job.
    async fn discover_hosts(&mut self) -> Result<(), StrategyError>;
}

/// A strategy that classifies the ports of targets handed to it one at a time.
///
/// The port-scan half of the pair. Where a [`HostScanner`] is aimed at a segment
/// it owns, this consumes the shuffled [`PlannedTarget`] stream a
/// [`Dispatcher`](crate::scanner::dispatcher::Dispatcher) produces, so that
/// several strategies can share one stream of work and none of them has to know
/// how the targets were ordered.
#[async_trait]
pub trait PortScanner: Send {
    /// Identifies the strategy, so a failure can be attributed to it in the
    /// report and on the event stream.
    fn kind(&self) -> ScannerKind;

    /// The transport protocols this strategy can actually probe.
    ///
    /// Read when a scan is assembled, to decide which protocols still need an
    /// unprivileged fallback, and again by
    /// [`CompositePortScanner`](crate::scanner::strategy::composite::CompositePortScanner)
    /// to route each target, so a strategy that under-reports its coverage is
    /// simply never given that work, rather than given it and failing.
    fn supported_protocols(&self) -> Vec<Protocol>;

    /// Probes every target arriving on `targets` and records each port's state
    /// in the shared store.
    ///
    /// Returns `Ok` when the run reached its end, including an end forced by
    /// [`ScanHandle::abort`](crate::scanner::handle::ScanHandle::abort), and
    /// `Err` only when the strategy itself could not do its job.
    async fn scan(&mut self, targets: mpsc::Receiver<PlannedTarget>) -> Result<(), StrategyError>;

    /// Second-pass service identification, run once after a successful
    /// [`scan`](PortScanner::scan) that was not aborted.
    ///
    /// A raw strategy classifies port state from a single exchange and never
    /// holds a connection to fingerprint through, so it opens one here for each
    /// open port. A connect strategy fingerprints inline while it still holds
    /// the live stream, and takes the default no-op. Putting this on the trait
    /// keeps "does this strategy need a second pass?" in the type rather than in
    /// a branch at every call site.
    async fn detect_services(&mut self, _ctx: &ScanContext) {}
}

/// Records `target`, which no scanner asked about, as a port nobody asked
/// about: on its host as [`PortState::Unasked`], and owed to a resume.
///
/// The one account of a port left unprobed that holds whoever leaves it: a
/// scanner stopped with it still queued, a scanner that refused its whole
/// plan, and a router with no scanner left to hand it to. Left off the host
/// instead, a truncated port list reads the same as a complete one, a host the
/// scan never reached is missing from the report altogether, and a port list
/// whose shape depends on how a run ended reads, compared with another scan's,
/// as the network moving. The outcome carries no position, so a resume asks
/// the question this sitting did not.
pub(crate) fn record_unasked(ctx: &ScanContext, target: &PlannedTarget) {
    let port =
        crate::fingerprint::baseline_port(target.port(), target.protocol(), PortState::Unasked);
    ctx.update_host(target.ip(), |host| {
        host.add_port(port);
    });
    ctx.record_outcome(Outcome::Unasked);
}

pub mod composite;
pub mod connect;
// The reader two scanners share for what an ICMP error says: a UDP port scan
// reads a port's verdict out of one, and a trace reads a router's identity out
// of one. Neither owns it, and it is a parser rather than a strategy.
pub(crate) mod icmp_error;
// The readers two strategies share: a local sweep interprets the replies its
// probes draw with them, and a listener interprets frames nobody asked for with
// the same ones. A frame that proves a host is there proves it either way.
//
// Named for what it reads rather than for the phase that reads it: `discovery`
// collided with `scanner::discover` and `ScanKind::Discovery`, neither of which
// this is.
pub(crate) mod frames;
pub mod local;
// What a machine is, asked of hosts a scan has already found. Neither of these
// discovers anything: they revisit what the store holds and read a stack off
// what answers.
pub mod identify;
pub mod passive;
// Which ports are open, and the machinery all four raw port scanners share.
pub mod ports;
// Which IP protocols a host takes delivery of, one layer below the ports. Runs
// after them, and only against hosts that answered, for the reason `topology`
// gives about its own two passes.
pub mod protocols;
// What every raw strategy is built from: how a probe reaches the wire, and the
// timings a probe over a routed path is held to.
pub(crate) mod raw;
pub mod routed;
// What the three probing sweeps keep track of in common.
pub(crate) mod sweep;
// What is between here and a host, rather than what is at it. Both passes here
// run after the ports are known, because what reaches a host is what decides
// how to ask about the path to it.
pub mod topology;