zond-engine 0.14.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

//! # Forward name resolution
//!
//! Turns the names a person writes, such as `example.com`, `raspberrypi.local`
//! and `nas`, into the addresses a scan can probe. This is the half of
//! resolution that runs before a scan, deciding what it will cover. The reverse
//! half, which
//! attaches names to hosts a scan has already found, lives in
//! [`crate::scanner::rdns`] and answers the opposite question.
//!
//! ## Three kinds of name, one entry point
//!
//! [`Resolver::resolve`] routes a name by how it is resolved, not by asking the
//! caller to know:
//!
//! - A `.local` name is a multicast name (RFC 6762): it is resolved by asking
//!   the link over multicast DNS, not by asking a unicast server. A unicast
//!   lookup of one fails everywhere the host has no mDNS-aware resolver, which
//!   on Linux is the common case, so the engine speaks mDNS itself rather than
//!   hoping the system does.
//! - Any other name goes to the system's unicast resolver, which applies the
//!   host's own search domains and returns A and AAAA records alike.
//! - A single-label name (`nas`) is tried unicast first, and if nothing answers
//!   and mDNS is enabled, again as `nas.local`, which on a home network is often
//!   what the author meant by it.
//!
//! ## Why a resolver, and not just the hook
//!
//! [`crate::model::parse`] already has the seam a name passes through: a
//! [`HostLookup`](crate::model::parse::target::HostLookup) supplied in a
//! [`TargetContext`](crate::model::parse::target::TargetContext). What it does
//! not have is anything to fill it with, because resolving a name means speaking
//! DNS and mDNS, which a target grammar must not do on its own behalf. This
//! module is what fills it, and it does so without the parse layer learning
//! anything about DNS: the engine resolves the names and hands the answers in.
//!
//! ## The synchronous seam, and the two passes
//!
//! That hook is synchronous, called once per name while a target expression is
//! parsed, and resolution is asynchronous and slow, mDNS especially so. Blocking
//! inside the hook would turn a file of two hundred
//! names into two hundred sequential round trips. So resolution is done in two
//! passes, and this module ships both rather than describing them:
//!
//! 1. [`resolve_names`] finds every name in a set of target expressions and
//!    resolves them concurrently into a map.
//! 2. [`to_target_map`] and [`to_set`] then build with a hook that reads the
//!    map, so the parse itself never waits on the network.
//!
//! A caller that only needs one name resolved can reach for [`Resolver::resolve`]
//! directly; a caller assembling a scan wants [`to_target_map`] or [`to_set`],
//! which do the whole of it.
//!
//! ## What it does not decide
//!
//! Whether a scan is allowed to resolve at all, which is what
//! [`ZondConfig::no_dns`](crate::config::ZondConfig::no_dns) means at request
//! time, is the caller's policy rather than this module's: a resolver that
//! refused to run would
//! be a strange thing to hold. A front end that must not emit DNS supplies no
//! resolver, and the parse layer then refuses a name with
//! [`NoHostLookup`](crate::model::parse::target::TargetParseError::NoHostLookup)
//! rather than covering less than its input said.

mod links;
mod mdns;
mod targets;

pub use links::{LinkError, for_listening, for_listening_on};
pub use targets::{
    DiscoveryTargets, for_discovery, for_discovery_with, for_exclusion, for_exclusion_with,
    resolve_names, to_set, to_target_map,
};

use std::fmt;
use std::net::IpAddr;
use std::time::Duration;

use hickory_resolver::TokioResolver;

use crate::warn;

/// The default mDNS reply window. See [`ResolveConfig::mdns_timeout`] for why it
/// is a whole second.
const DEFAULT_MDNS_TIMEOUT: Duration = Duration::from_secs(1);

/// The shortest window that can hear a conformant responder.
///
/// RFC 6762 §6.3 permits a responder to defer a reply by up to half a second so
/// it can aggregate answers, so a window below that closes while a correct
/// implementation is still waiting to speak. A caller asking for less has asked
/// for a lookup that cannot succeed, and gets this instead: unlike the scan
/// settings in [`ZondConfig`](crate::config::ZondConfig), nothing here is
/// carried into a report, so raising a window costs nobody a record that says
/// one thing while the run did another.
const MIN_MDNS_TIMEOUT: Duration = Duration::from_millis(500);

/// How a [`Resolver`] behaves, independent of the host it reads its unicast
/// configuration from.
///
/// Non-exhaustive and [`Default`]-constructed, like
/// [`ZondConfig`](crate::config::ZondConfig): the next thing worth saying about
/// how a name is resolved is an additive change rather than a major version.
#[non_exhaustive]
#[derive(Debug, Clone, Copy)]
pub struct ResolveConfig {
    /// Whether `.local` names are resolved over multicast, and whether a
    /// single-label name falls back to one.
    ///
    /// Off leaves a `.local` name unresolved rather than silently sending it to
    /// a unicast server that will answer NXDOMAIN for it. For an environment
    /// where multicast is filtered or unwanted, or where the only names in play
    /// are global.
    pub mdns: bool,

    /// How long to listen for mDNS replies before accepting that a `.local`
    /// name has no answer on the segment.
    ///
    /// A responder may defer a reply by up to half a second to aggregate
    /// answers (RFC 6762 §6.3), and one on a busy or sleepy device can take
    /// longer, so the default is a whole second: short enough not to stall a
    /// scan, long enough that a device answering slowly is found rather than
    /// declared absent.
    ///
    /// A window shorter than the half second the RFC permits is raised to it.
    /// Below that the lookup cannot hear a correct responder at all, so it is a
    /// preference the protocol overrules rather than a value to refuse: zero was
    /// accepted here and produced a listener that closed before it opened.
    pub mdns_timeout: Duration,
}

impl Default for ResolveConfig {
    fn default() -> Self {
        Self {
            mdns: true,
            mdns_timeout: DEFAULT_MDNS_TIMEOUT,
        }
    }
}

/// Resolves names to addresses over unicast DNS and multicast DNS.
///
/// Cheap to clone, the unicast resolver it holds being reference-counted, so it
/// can be shared across the concurrent lookups [`resolve_names`] runs.
#[derive(Clone)]
pub struct Resolver {
    /// The system unicast resolver, or `None` when the host's resolver
    /// configuration could not be read. A resolver with no unicast half still
    /// answers `.local` names; it simply has nothing to ask for the rest.
    unicast: Option<TokioResolver>,
    config: ResolveConfig,
}

impl Resolver {
    /// Builds a resolver from the host's own unicast configuration, with mDNS
    /// enabled.
    ///
    /// Reading the resolver configuration can fail, as in a container with no
    /// `resolv.conf`, and that is not fatal: the resolver is returned with no
    /// unicast half, so `.local` names still resolve while global names come
    /// back empty. The failure is logged rather than raised, because a scan that
    /// resolves fewer names is still a scan.
    pub fn from_system() -> Self {
        Self::with_config(ResolveConfig::default())
    }

    /// Builds a resolver with an explicit [`ResolveConfig`].
    pub fn with_config(config: ResolveConfig) -> Self {
        Self {
            unicast: build_unicast(),
            config,
        }
    }

    /// Resolves one name to every address it stands for, in first-seen order.
    ///
    /// An empty result means nothing answered for the name, which a caller treats
    /// the same as a name that resolved to nothing, since both are a target that
    /// is not there. Routing is by name: see the module
    /// documentation for how `.local`, global, and single-label names differ.
    pub async fn resolve(&self, name: &str) -> Vec<IpAddr> {
        let name = name.trim_end_matches('.');

        if is_multicast_local(name) {
            return self.resolve_mdns(name).await;
        }

        let unicast = self.resolve_unicast(name).await;
        if !unicast.is_empty() || !is_single_label(name) {
            return unicast;
        }

        // A bare `nas` that unicast could not place is, on a home or office
        // segment, most often `nas.local`. Tried only after unicast so a real
        // search-domain match is never shadowed by a multicast one.
        self.resolve_mdns(&format!("{name}.local")).await
    }

    /// The unicast half: A and AAAA through the system resolver, or nothing when
    /// there is no resolver or the name has no records.
    async fn resolve_unicast(&self, name: &str) -> Vec<IpAddr> {
        let Some(resolver) = &self.unicast else {
            return Vec::new();
        };

        match resolver.lookup_ip(name).await {
            Ok(lookup) => lookup.iter().collect(),
            // A name with no records is an ordinary answer, not a failure worth
            // surfacing: it resolves to nothing, which is what an empty vector
            // says.
            Err(_) => Vec::new(),
        }
    }

    /// The multicast half, honouring the config's mDNS switch.
    async fn resolve_mdns(&self, name: &str) -> Vec<IpAddr> {
        if !self.config.mdns {
            return Vec::new();
        }
        let window = self.config.mdns_timeout.max(MIN_MDNS_TIMEOUT);
        mdns::resolve(name, window).await
    }
}

impl fmt::Debug for Resolver {
    /// Says what this resolver can do rather than dumping the unicast client.
    ///
    /// Hand-written because the type it holds is a third party's and printing
    /// its internals would put that crate's shape in this one's output. What a
    /// caller debugging a resolution wants is the two facts that decide where a
    /// name goes: whether there is a unicast half at all, and whether multicast
    /// is on.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Resolver")
            .field("unicast", &self.unicast.is_some())
            .field("config", &self.config)
            .finish()
    }
}

/// Builds the system unicast resolver, logging and swallowing the two failures
/// that leave a host unable to resolve global names.
fn build_unicast() -> Option<TokioResolver> {
    let Ok(builder) = TokioResolver::builder_tokio() else {
        warn!("no system resolver configuration found; global names will not resolve");
        return None;
    };
    let Ok(resolver) = builder.build() else {
        warn!("could not build the system resolver; global names will not resolve");
        return None;
    };
    Some(resolver)
}

/// Whether `name` is resolved over multicast: a multi-label name whose last
/// label is `local`.
///
/// A bare `local` is not one. It is a single-label name the fallback path may try
/// as `local.local`, rather than a `.local` host in its own right.
fn is_multicast_local(name: &str) -> bool {
    name.contains('.')
        && name
            .rsplit('.')
            .next()
            .is_some_and(|tld| tld.eq_ignore_ascii_case("local"))
}

/// Whether `name` is a single label, and so a candidate for the `.local`
/// fallback once unicast has had its say.
fn is_single_label(name: &str) -> bool {
    !name.is_empty() && !name.contains('.')
}

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

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

    /// The routing predicate decides which protocol a name is resolved by, so a
    /// misclassification sends a `.local` host to a unicast server that cannot
    /// answer for it, or a global name to a multicast group that will not.
    #[test]
    fn only_a_dotted_local_name_is_a_multicast_name() {
        assert!(is_multicast_local("raspberrypi.local"));
        assert!(is_multicast_local("Printer.LOCAL"));
        assert!(is_multicast_local("host.sub.local"));

        assert!(!is_multicast_local("example.com"));
        assert!(!is_multicast_local("localhost"));
        // A bare `local` has no host part; it is a short name, not a `.local`
        // one.
        assert!(!is_multicast_local("local"));
    }

    /// A window too short to hear a conformant responder is raised to one that
    /// can, rather than producing a lookup that closes before it opens.
    ///
    /// RFC 6762 §6.3 lets a responder defer a reply half a second to aggregate
    /// answers, so half a second is the floor the protocol sets. Zero used to be
    /// accepted here and reached the listener as written.
    ///
    /// Raised rather than refused, unlike the overrides in
    /// [`RetryConfig`](crate::config::RetryConfig): nothing in a
    /// [`ResolveConfig`] is carried into a report, so a window the engine
    /// overrules costs nobody a record claiming a run did something it did not.
    #[test]
    fn a_window_shorter_than_the_protocol_allows_is_raised_to_it() {
        for asked in [Duration::ZERO, Duration::from_millis(1), MIN_MDNS_TIMEOUT] {
            assert_eq!(asked.max(MIN_MDNS_TIMEOUT), MIN_MDNS_TIMEOUT);
        }

        // A window the caller meant is the window they get.
        let generous = Duration::from_secs(5);
        assert_eq!(generous.max(MIN_MDNS_TIMEOUT), generous);
        assert_eq!(
            DEFAULT_MDNS_TIMEOUT.max(MIN_MDNS_TIMEOUT),
            DEFAULT_MDNS_TIMEOUT,
            "the default is above the floor, or the floor is the default"
        );
    }

    /// A resolver says what it can do rather than printing a third party's
    /// client, and it says it at all, which it could not before.
    #[test]
    fn a_resolver_reports_the_two_facts_that_decide_where_a_name_goes() {
        let rendered = format!("{:?}", Resolver::with_config(ResolveConfig::default()));

        assert!(rendered.starts_with("Resolver"), "{rendered}");
        assert!(rendered.contains("unicast"), "{rendered}");
        assert!(rendered.contains("mdns: true"), "{rendered}");
    }

    #[test]
    fn a_single_label_is_a_fallback_candidate_and_a_dotted_name_is_not() {
        assert!(is_single_label("nas"));
        assert!(!is_single_label("nas.local"));
        assert!(!is_single_label("example.com"));
        assert!(!is_single_label(""));
    }
}