nadzoring.dns_lookup.trace module

DNS trace routing for tracking the full resolution delegation chain.

nadzoring.dns_lookup.trace._create_hop(nameserver: str) → dict[str, Any][source]

Initialise a new hop entry for DNS trace tracking.

Parameters:

nameserver – IP address of the nameserver for this hop.

Returns:

Dict with nameserver, records, response_time, next, and error keys set to their zero/null defaults.

nadzoring.dns_lookup.trace._get_delegation_info(current_domain: Name, current_ns: str, hop: dict[str, Any]) → str | None[source]

Resolve the next-hop nameserver IP via NS delegation records.

Parameters:

  • current_domain – Domain to query for NS records.

  • current_ns – IP address of the nameserver to ask.

  • hop – Hop dict updated in-place with delegation record strings or an "error" key on failure.

Returns:

IP address of the next nameserver, or None when delegation cannot be determined.

nadzoring.dns_lookup.trace._query_nameserver(domain: str, nameserver: str) → tuple[Answer | None, float | None, str | None][source]

Query a specific nameserver for A records of domain.

Parameters:

  • domain – Domain name to query.

  • nameserver – IP address of the nameserver to query.

Returns:

Three-tuple of (answers, response_time_ms, error_message). response_time_ms is None only on timeout; error_message is None on success.

nadzoring.dns_lookup.trace.trace_dns(domain: str, nameserver: str | None = None) → dict[str, Any][source]

Trace the complete DNS resolution path for domain.

Follows the delegation chain from the specified (or root) nameserver to the authoritative answer, similar to dig +trace. Loop detection and a maximum-hop limit prevent infinite recursion.

Parameters:

  • domain – Domain name to trace (e.g. "example.com").

  • nameserver – Starting nameserver IP. Defaults to a.root-servers.net (198.41.0.4) when None.

Returns:

Dict with domain, hops (list of hop dicts), and final_answer (the authoritative hop, or None).

Examples

>>> result = trace_dns("example.com")
>>> for hop in result["hops"]:
...     print(hop["nameserver"], hop["response_time"])