dnsname 0.1.4

Canonical registrable-domain (eTLD+1) and public-suffix resolution, backed by the Public Suffix List
Documentation

dnsname - canonical eTLD+1 and public-suffix resolution

santh status

Canonical registrable-domain (eTLD+1) and public-suffix resolution for network scanning, asset mapping, and security telemetry. Backed by the Mozilla Public Suffix List via the psl crate. Handles multi-label public suffixes (example.co.uk -> example.co.uk), normalizes case/FQDN dots, rejects hostnames with control bytes or interior whitespace, and excludes IP literals (IPv4/IPv6, including bracketed [::1] and zone-scoped fe80::1%eth0).

Quick Start

Add dnsname to Cargo.toml:

[dependencies]
dnsname = "=0.1.2"

Resolve registrable domains and public suffixes in Rust:

use dnsname::{registrable_domain, public_suffix, is_subdomain_of, same_registrable_domain};

// Registrable domain (eTLD+1)
assert_eq!(registrable_domain("a.b.example.co.uk").as_deref(), Some("example.co.uk"));
assert_eq!(registrable_domain("com"), None); // Bare public suffix has no eTLD+1
assert_eq!(registrable_domain("1.2.3.4"), None); // IP literals return None

// Public suffix
assert_eq!(public_suffix("a.example.co.uk").as_deref(), Some("co.uk"));

// Subdomain matching & domain comparison
assert!(is_subdomain_of("a.example.com", "example.com"));
assert!(same_registrable_domain("mail.example.com", "www.example.com"));

etld_plus_one and apex_domain are provided as direct aliases for registrable_domain.

When to Use / When Not to Use

When to Use

  • Determining the organizational boundary (eTLD+1) of hostnames.
  • Grouping target hostnames by registrable domain to prevent redundant scanning or enforce rate limits.
  • Checking label-based subdomain ownership between hostnames.

When Not to Use

  • Normalizing URLs or host cache keys (use scanclient::urlutil::registrable_domain when keeping full host with www. stripped).
  • Decoding internationalized domain names (IDNA/Punycode). Pass A-label (xn--...) hosts directly.
  • Parsing full URL components (strip scheme, port, path, and userinfo before calling dnsname).

Compared to Alternatives

Direct usage of the psl crate requires callers to handle input normalization, FQDN trailing dot stripping, ASCII lowercasing, non-ASCII/control-byte rejection, and IP literal exclusion (1.2.3.4, [::1]) manually. Naive psl usage without IP literal checks treats IP octets as domain labels (e.g. grouping 1.2.3.4 under a bogus 3.4 TLD). dnsname wraps psl with zero-copy normalization and strict safety guarantees.

Hand-rolled "last two labels" splitters (e.g. splitting shop.example.co.uk on . and taking the last two parts) produce incorrect results for multi-label public suffixes, returning co.uk instead of example.co.uk. dnsname uses the full Public Suffix List rules to return the correct registrable domain.

How it Fits in Santh

dnsname is a foundational utility crate in libs/scanner/dnsname. It depends on psl (pinned snapshot) and has no unsafe code (#![forbid(unsafe_code)]). It is consumed by scanner and discovery crates across the workspace (e.g. gossan, wafrift, scald, sear, daylight) to ensure consistent domain resolution across the entire fleet.

License

MIT