dnsname - canonical eTLD+1 and public-suffix resolution
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:
[]
= "=0.1.2"
Resolve registrable domains and public suffixes in Rust:
use ;
// Registrable domain (eTLD+1)
assert_eq!;
assert_eq!; // Bare public suffix has no eTLD+1
assert_eq!; // IP literals return None
// Public suffix
assert_eq!;
// Subdomain matching & domain comparison
assert!;
assert!;
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_domainwhen keeping full host withwww.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