mod hosts;
mod links;
mod mdns;
mod targets;
mod unicast;
pub use links::{LinkError, for_listening, for_listening_on};
#[cfg(feature = "import-request")]
pub(crate) use targets::for_request;
pub use targets::{
DiscoveryTargets, PortScanTargets, for_discovery, for_discovery_with, for_exclusion,
for_exclusion_with, for_port_scan, resolve_names, to_set, to_target_map,
};
use std::fmt;
use std::net::IpAddr;
use std::time::Duration;
use crate::warn;
pub(crate) use hosts::HostsTable;
pub(crate) use unicast::{DnsConfig, Reverse, ScopedServers, Unicast, covers, reverse_name};
const DEFAULT_MDNS_TIMEOUT: Duration = Duration::from_secs(1);
const MIN_MDNS_TIMEOUT: Duration = Duration::from_millis(500);
#[non_exhaustive]
#[derive(Debug, Clone, Copy)]
pub struct ResolveConfig {
pub mdns: bool,
pub mdns_timeout: Duration,
}
impl Default for ResolveConfig {
fn default() -> Self {
Self {
mdns: true,
mdns_timeout: DEFAULT_MDNS_TIMEOUT,
}
}
}
#[derive(Clone)]
pub struct Resolver {
origin: Origin,
config: ResolveConfig,
asks: bool,
}
#[derive(Clone)]
enum Origin {
System,
#[cfg(test)]
Given(std::sync::Arc<dyn Fn() -> (String, DnsConfig) + Send + Sync>),
}
pub(crate) struct Snapshot {
hosts: HostsTable,
unicast: Option<Unicast>,
}
impl Resolver {
pub fn from_system() -> Self {
Self::with_config(ResolveConfig::default())
}
pub fn with_config(config: ResolveConfig) -> Self {
Self {
origin: Origin::System,
config,
asks: true,
}
}
pub fn hosts_file_only() -> Self {
Self {
origin: Origin::System,
config: ResolveConfig::default(),
asks: false,
}
}
#[cfg(test)]
pub(crate) fn given(
config: ResolveConfig,
read: impl Fn() -> (String, DnsConfig) + Send + Sync + 'static,
) -> Self {
Self {
origin: Origin::Given(std::sync::Arc::new(read)),
config,
asks: true,
}
}
pub(crate) fn snapshot(&self) -> Snapshot {
let (hosts, dns) = match &self.origin {
Origin::System => (
HostsTable::read_system(),
self.asks.then(DnsConfig::read_system),
),
#[cfg(test)]
Origin::Given(read) => {
let (hosts, dns) = read();
(HostsTable::parse(&hosts), self.asks.then_some(dns))
}
};
Snapshot {
hosts,
unicast: dns.map(Unicast::from_config),
}
}
pub async fn resolve(&self, name: &str) -> Vec<IpAddr> {
self.resolve_in(&self.snapshot(), name).await
}
pub(crate) async fn resolve_in(&self, snapshot: &Snapshot, name: &str) -> Vec<IpAddr> {
let name = name.trim_end_matches('.');
if let Some(listed) = from_hosts(snapshot, name) {
return listed;
}
let Some(unicast) = &snapshot.unicast else {
return Vec::new();
};
if is_multicast_local(name) {
return self.resolve_local(unicast, name).await;
}
let answered = unicast.lookup(name).await;
if !answered.is_empty() || !is_single_label(name) {
return answered;
}
let local = format!("{name}.local");
if let Some(listed) = from_hosts(snapshot, &local) {
return listed;
}
self.resolve_local(unicast, &local).await
}
async fn resolve_local(&self, unicast: &Unicast, name: &str) -> Vec<IpAddr> {
if unicast.claims(name) {
let unicast = unicast.lookup(name).await;
if !unicast.is_empty() {
return unicast;
}
}
self.resolve_mdns(name).await
}
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 Snapshot {
pub(crate) async fn reverse(&self, ip: IpAddr) -> Reverse {
if let Some(name) = self.hosts.name_of(ip) {
return Reverse::Listed(name.to_owned());
}
match (&self.unicast, self.reverse_route(ip)) {
(Some(unicast), ReverseRoute::Scoped(_) | ReverseRoute::Global) => {
unicast.reverse(ip).await
}
_ => Reverse::Unasked,
}
}
pub(crate) fn reverse_route(&self, ip: IpAddr) -> ReverseRoute {
match &self.unicast {
_ if self.hosts.name_of(ip).is_some() => ReverseRoute::Local,
Some(unicast) if !ip.is_loopback() => unicast
.reverse_scope(ip)
.map_or(ReverseRoute::Global, ReverseRoute::Scoped),
_ => ReverseRoute::Local,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum ReverseRoute {
Local,
Scoped(usize),
Global,
}
fn from_hosts(snapshot: &Snapshot, name: &str) -> Option<Vec<IpAddr>> {
let answer = snapshot.hosts.lookup(name)?;
for unused in &answer.shadowed {
warn!("{name}: hosts line for {unused} ignored (earlier line wins)");
}
Some(answer.addresses)
}
impl fmt::Debug for Resolver {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let origin = match self.origin {
Origin::System => "system",
#[cfg(test)]
Origin::Given(_) => "given",
};
f.debug_struct("Resolver")
.field("origin", &origin)
.field("config", &self.config)
.field("asks", &self.asks)
.finish()
}
}
fn is_multicast_local(name: &str) -> bool {
name.contains('.')
&& name
.rsplit('.')
.next()
.is_some_and(|tld| tld.eq_ignore_ascii_case("local"))
}
fn is_single_label(name: &str) -> bool {
!name.is_empty() && !name.contains('.')
}
#[cfg(test)]
mod tests {
use super::*;
#[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"));
assert!(!is_multicast_local("local"));
}
#[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);
}
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"
);
}
#[test]
fn a_resolver_reports_what_it_reads_and_whether_multicast_is_on() {
let rendered = format!("{:?}", Resolver::with_config(ResolveConfig::default()));
assert!(rendered.starts_with("Resolver"), "{rendered}");
assert!(rendered.contains("origin: \"system\""), "{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(""));
}
use std::collections::HashMap;
use std::net::{Ipv4Addr, SocketAddr};
use std::sync::{Arc, Mutex};
use hickory_resolver::config::{NameServerConfig, ResolverConfig, ResolverOpts};
use hickory_resolver::proto::op::{Message, MessageType, ResponseCode};
use hickory_resolver::proto::rr::rdata::{A, PTR, SOA};
use hickory_resolver::proto::rr::{Name, RData, Record, RecordType};
use crate::logging::logged;
use unicast::ScopedServers;
struct FakeDns {
at: SocketAddr,
records: Arc<Mutex<HashMap<String, Ipv4Addr>>>,
names: Arc<Mutex<HashMap<String, String>>>,
asked: Arc<Mutex<Vec<String>>>,
serving: tokio::task::JoinHandle<()>,
}
impl FakeDns {
async fn start(records: &[(&str, Ipv4Addr)]) -> Self {
let socket = tokio::net::UdpSocket::bind("127.0.0.1:0")
.await
.expect("a loopback socket binds");
let at = socket.local_addr().expect("a bound socket has an address");
let records = Arc::new(Mutex::new(
records
.iter()
.map(|(name, ip)| (format!("{name}."), *ip))
.collect::<HashMap<_, _>>(),
));
let asked = Arc::new(Mutex::new(Vec::new()));
let names = Arc::new(Mutex::new(HashMap::new()));
let (held, noted) = (Arc::clone(&records), Arc::clone(&asked));
let reverse = Arc::clone(&names);
let serving = tokio::spawn(async move {
let mut buf = [0u8; 1500];
while let Ok((len, from)) =
crate::testing::loopback::recv_from_this_process(&socket, &mut buf).await
{
let Ok(query) = Message::from_vec(&buf[..len]) else {
continue;
};
let Some(question) = query.queries.first().cloned() else {
continue;
};
let name = question.name().to_ascii().to_ascii_lowercase();
noted
.lock()
.expect("unpoisoned")
.push(format!("{name} {}", question.query_type()));
let known = held.lock().expect("unpoisoned").get(&name).copied();
let named = reverse.lock().expect("unpoisoned").get(&name).cloned();
let mut reply = Message::response(query.metadata.id, query.metadata.op_code);
reply.metadata.message_type = MessageType::Response;
reply.metadata.recursion_desired = query.metadata.recursion_desired;
reply.metadata.recursion_available = true;
reply.add_query(question.clone());
match known {
_ if question.query_type() == RecordType::PTR && named.is_some() => {
let host = named.expect("checked above");
reply.add_answer(Record::from_rdata(
question.name().clone(),
300,
RData::PTR(PTR(Name::from_ascii(&host).expect("a host name"))),
));
}
Some(ip) if question.query_type() == RecordType::A => {
reply.add_answer(Record::from_rdata(
question.name().clone(),
300,
RData::A(A(ip)),
));
}
Some(_) => {}
None => {
reply.metadata.response_code = ResponseCode::NXDomain;
let zone = Name::from_ascii("example.").expect("a zone name");
let soa =
SOA::new(zone.clone(), zone.clone(), 1, 3600, 600, 86400, 3600);
reply.add_authority(Record::from_rdata(zone, 3600, RData::SOA(soa)));
}
}
let bytes = reply.to_vec().expect("a reply encodes");
let _ = socket.send_to(&bytes, from).await;
}
});
Self {
at,
records,
names,
asked,
serving,
}
}
fn name(&self, ip: IpAddr, host: &str) {
self.names
.lock()
.expect("unpoisoned")
.insert(format!("{}.", reverse_name(ip)), format!("{host}."));
}
fn asked(&self) -> Vec<String> {
self.asked.lock().expect("unpoisoned").clone()
}
fn add(&self, name: &str, ip: Ipv4Addr) {
self.records
.lock()
.expect("unpoisoned")
.insert(format!("{name}."), ip);
}
fn as_global(&self, search: &[&str]) -> (ResolverConfig, ResolverOpts) {
let mut server = NameServerConfig::udp(self.at.ip());
for connection in &mut server.connections {
connection.port = self.at.port();
}
let search = search
.iter()
.map(|s| s.parse().expect("a search domain parses"))
.collect();
let mut opts = ResolverOpts::default();
opts.attempts = 1;
(ResolverConfig::from_parts(None, search, vec![server]), opts)
}
}
impl Drop for FakeDns {
fn drop(&mut self) {
self.serving.abort();
}
}
fn no_mdns() -> ResolveConfig {
ResolveConfig {
mdns: false,
..ResolveConfig::default()
}
}
fn v4(s: &str) -> IpAddr {
s.parse().expect("a test address parses")
}
fn resolver_over(
hosts: &str,
global: Result<(ResolverConfig, ResolverOpts), String>,
scoped: Vec<ScopedServers>,
) -> Resolver {
let hosts = hosts.to_owned();
Resolver::given(no_mdns(), move || {
(
hosts.clone(),
DnsConfig {
global: global.clone(),
scoped: scoped.clone(),
},
)
})
}
#[tokio::test]
async fn a_name_the_hosts_file_lists_is_answered_without_asking_dns() {
let dns = FakeDns::start(&[]).await;
let resolver = resolver_over(
"198.51.100.7 box.example\n",
Ok(dns.as_global(&[])),
Vec::new(),
);
assert_eq!(
resolver.resolve("box.example").await,
vec![v4("198.51.100.7")]
);
assert_eq!(
dns.asked(),
Vec::<String>::new(),
"the hosts name reached DNS"
);
}
#[test]
fn a_stale_hosts_line_for_a_name_is_neither_scanned_nor_silent() {
let resolver = resolver_over(
"198.51.100.23 box.example\n198.51.100.99 box.example\n",
Err("none configured".into()),
Vec::new(),
);
let runtime = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.expect("a runtime builds");
let mut resolved = Vec::new();
let lines = logged(|| resolved = runtime.block_on(resolver.resolve("box.example")));
assert_eq!(resolved, vec![v4("198.51.100.23")]);
let warned: Vec<_> = lines.iter().filter(|l| l.verbosity == 0).collect();
assert!(
warned
.iter()
.any(|l| l.message.contains("box.example") && l.message.contains("198.51.100.99")),
"no default-verbosity line names the unused address: {lines:?}"
);
}
#[tokio::test]
async fn a_local_name_the_hosts_file_lists_resolves_from_it() {
let resolver = resolver_over(
"198.51.100.161 forest.corp.local corp.local\n",
Err("none configured".into()),
Vec::new(),
);
for name in ["forest.corp.local", "corp.local"] {
assert_eq!(
resolver.resolve(name).await,
vec![v4("198.51.100.161")],
"{name}"
);
}
}
#[tokio::test]
async fn a_local_name_under_a_searched_domain_is_asked_of_unicast_dns() {
let dns = FakeDns::start(&[("dc01.corp.local", Ipv4Addr::new(198, 51, 100, 10))]).await;
let resolver = resolver_over("", Ok(dns.as_global(&["corp.local"])), Vec::new());
assert_eq!(
resolver.resolve("dc01.corp.local").await,
vec![v4("198.51.100.10")]
);
let before = dns.asked().len();
assert_eq!(
resolver.resolve("printer.local").await,
Vec::<IpAddr>::new()
);
assert_eq!(
dns.asked().len(),
before,
"a link-only name reached unicast DNS"
);
}
#[tokio::test]
async fn a_name_under_a_scoped_domain_is_asked_of_that_domains_server_alone() {
let global = FakeDns::start(&[("www.example", Ipv4Addr::new(203, 0, 113, 80))]).await;
let scoped =
FakeDns::start(&[("host.corp.example", Ipv4Addr::new(198, 51, 100, 20))]).await;
let resolver = resolver_over(
"",
Ok(global.as_global(&[])),
vec![ScopedServers {
domain: "corp.example".into(),
servers: Ok(vec![scoped.at]),
}],
);
assert_eq!(
resolver.resolve("host.corp.example").await,
vec![v4("198.51.100.20")]
);
assert!(
global.asked().iter().all(|q| !q.contains("corp.example")),
"the scoped name reached the global server: {:?}",
global.asked()
);
assert_eq!(
resolver.resolve("www.example").await,
vec![v4("203.0.113.80")]
);
assert!(
scoped.asked().iter().all(|q| !q.contains("www.example")),
"a global name reached the scoped server: {:?}",
scoped.asked()
);
}
#[test]
fn the_hosts_file_answers_when_no_dns_server_is_configured() {
let resolver = resolver_over(
"198.51.100.5 hostsonly\n",
Err("no nameservers found in config".into()),
Vec::new(),
);
let runtime = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.expect("a runtime builds");
let (mut listed, mut global) = (Vec::new(), Vec::new());
let lines = logged(|| {
listed = runtime.block_on(resolver.resolve("hostsonly"));
global = runtime.block_on(resolver.resolve("www.example"));
});
assert_eq!(listed, vec![v4("198.51.100.5")]);
assert_eq!(global, Vec::<IpAddr>::new());
assert!(
lines
.iter()
.any(|l| l.verbosity == 0 && l.message.contains("no DNS server configured")),
"{lines:?}"
);
}
#[tokio::test]
async fn a_kept_resolver_sees_names_that_appeared_after_it_was_built() {
let dns = FakeDns::start(&[]).await;
let hosts = Arc::new(Mutex::new(String::new()));
let global = dns.as_global(&[]);
let file = Arc::clone(&hosts);
let resolver = Resolver::given(no_mdns(), move || {
(
file.lock().expect("unpoisoned").clone(),
DnsConfig {
global: Ok(global.clone()),
scoped: Vec::new(),
},
)
});
assert_eq!(
resolver.resolve("newbox.example").await,
Vec::<IpAddr>::new()
);
assert_eq!(
resolver.resolve("record.example").await,
Vec::<IpAddr>::new()
);
*hosts.lock().expect("unpoisoned") = "198.51.100.44 newbox.example\n".into();
dns.add("record.example", Ipv4Addr::new(198, 51, 100, 45));
assert_eq!(
resolver.resolve("record.example").await,
vec![v4("198.51.100.45")]
);
assert_eq!(
resolver.resolve("newbox.example").await,
vec![v4("198.51.100.44")]
);
}
#[tokio::test]
async fn an_address_under_a_scoped_reverse_zone_is_asked_of_that_zones_server_alone() {
let global = FakeDns::start(&[]).await;
global.name(v4("203.0.113.80"), "www.example");
let scoped = FakeDns::start(&[]).await;
scoped.name(v4("198.51.100.20"), "host.corp.example");
let resolver = resolver_over(
"",
Ok(global.as_global(&[])),
vec![ScopedServers {
domain: "100.51.198.in-addr.arpa".into(),
servers: Ok(vec![scoped.at]),
}],
);
let snapshot = resolver.snapshot();
assert_eq!(
snapshot.reverse_route(v4("198.51.100.20")),
ReverseRoute::Scoped(0)
);
assert_eq!(
snapshot.reverse_route(v4("203.0.113.80")),
ReverseRoute::Global
);
assert_eq!(snapshot.reverse_route(v4("127.0.0.9")), ReverseRoute::Local);
assert_eq!(
snapshot.reverse(v4("198.51.100.20")).await,
Reverse::Named("host.corp.example.".into())
);
assert_eq!(
global.asked(),
Vec::<String>::new(),
"an address in the scoped zone reached the global resolver"
);
assert_eq!(
snapshot.reverse(v4("203.0.113.80")).await,
Reverse::Named("www.example.".into())
);
assert_eq!(
scoped.asked(),
vec!["20.100.51.198.in-addr.arpa. PTR".to_string()],
"an address outside the zone reached its server"
);
}
#[tokio::test]
async fn an_address_the_hosts_file_lists_is_named_by_its_first_line_and_asked_of_nobody() {
let global = FakeDns::start(&[]).await;
global.name(v4("198.51.100.23"), "from-dns.example");
let resolver = resolver_over(
"198.51.100.23 old-box.example\n198.51.100.23 new-box.example\n",
Ok(global.as_global(&[])),
Vec::new(),
);
assert_eq!(
resolver.snapshot().reverse(v4("198.51.100.23")).await,
Reverse::Listed("old-box.example".into())
);
assert_eq!(global.asked(), Vec::<String>::new());
}
#[tokio::test]
async fn a_loopback_address_is_named_by_the_hosts_file_or_not_at_all() {
let global = FakeDns::start(&[]).await;
let resolver = resolver_over(
"127.0.0.1 localhost\n",
Ok(global.as_global(&[])),
Vec::new(),
);
let snapshot = resolver.snapshot();
assert_eq!(
snapshot.reverse(v4("127.0.0.1")).await,
Reverse::Listed("localhost".into())
);
assert_eq!(snapshot.reverse(v4("127.0.0.9")).await, Reverse::Unasked);
assert_eq!(snapshot.reverse(v4("::1")).await, Reverse::Unasked);
assert_eq!(global.asked(), Vec::<String>::new());
}
#[test]
fn with_no_dns_server_configured_reverse_lookups_say_so_once() {
let resolver = resolver_over(
"198.51.100.5 hostsonly\n",
Err("no nameservers found in config".into()),
Vec::new(),
);
let runtime = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.expect("a runtime builds");
let mut answers = Vec::new();
let lines = logged(|| {
let snapshot = resolver.snapshot();
for ip in ["198.51.100.5", "198.51.100.6", "198.51.100.7"] {
answers.push(runtime.block_on(snapshot.reverse(v4(ip))));
}
});
assert_eq!(
answers,
vec![
Reverse::Listed("hostsonly".into()),
Reverse::Unasked,
Reverse::Unasked
]
);
let said: Vec<_> = lines
.iter()
.filter(|l| l.verbosity == 0 && l.message.contains("no DNS server configured"))
.collect();
assert_eq!(said.len(), 1, "{lines:?}");
}
#[tokio::test]
async fn a_hosts_file_only_resolver_answers_listed_names_and_asks_nobody() {
let dns = FakeDns::start(&[("www.example", Ipv4Addr::new(203, 0, 113, 80))]).await;
let mut resolver =
resolver_over("198.51.100.9 box.htb\n", Ok(dns.as_global(&[])), Vec::new());
resolver.asks = false;
assert_eq!(resolver.resolve("box.htb").await, vec![v4("198.51.100.9")]);
for name in ["www.example", "printer.local", "nas"] {
assert_eq!(resolver.resolve(name).await, Vec::<IpAddr>::new(), "{name}");
}
assert_eq!(dns.asked(), Vec::<String>::new());
}
}