nadzoring.dns_lookup package¶

DNS lookup module for domain name resolution and DNS record checking.

nadzoring.dns_lookup.benchmark_dns_servers(domain: str = 'google.com', servers: list[str] | None = None, record_type: RecordType = 'A', queries: int = 10, max_workers: int = 5, progress_callback: Callable[[str, int], None] | None = None, *, parallel: bool = True) → list[BenchmarkResult][source]¶

Benchmark multiple DNS servers and compare their performance.

Tests each server either in parallel (via ThreadPoolExecutor) or sequentially, then sorts results by average response time.

Parameters:

domain – Domain to query. Defaults to "google.com".
servers – Server IPs to benchmark. None uses get_public_dns_servers().
record_type – DNS record type to query. Defaults to "A".
queries – Queries per server. Defaults to 10.
max_workers – Thread pool size when parallel is True. Defaults to 5.
progress_callback – Called after each server completes with (server_ip, 1-based_index).
parallel – Run benchmarks concurrently when True (default).

Returns:

List of BenchmarkResult dicts sorted by avg_response_time ascending (fastest first).

Examples

>>> results = benchmark_dns_servers(servers=["8.8.8.8", "1.1.1.1"])
>>> fastest = results[0]
>>> print(f"{fastest['server']}: {fastest['avg_response_time']:.2f}ms")

nadzoring.dns_lookup.check_dns(domain: str, nameserver: str | None = None, record_types: list[str] | None = None, *, validate_mx: bool = False, validate_txt: bool = False) → DetailedCheckResult[source]¶

Perform a comprehensive DNS check with detailed per-record information.

Queries the specified record types and optionally validates MX priorities and SPF/DKIM TXT records.

Parameters:

domain – Domain name to check (e.g. "example.com").
nameserver – Optional nameserver IP. None uses the system default.
record_types – Record types to query. Defaults to ["A", "AAAA", "MX", "NS", "TXT", "CNAME"].
validate_mx – Validate MX record priorities when True.
validate_txt – Validate SPF and DKIM in TXT records when True.

Returns:

DetailedCheckResult dict with domain, records, errors, response_times, and validations keys.

Examples

>>> result = check_dns(
...     "example.com",
...     record_types=["MX", "TXT"],
...     validate_mx=True,
...     validate_txt=True,
... )
>>> result["validations"].get("mx", {}).get("valid")
True

nadzoring.dns_lookup.check_dns_poisoning(domain: str, control_server: str = '8.8.8.8', test_servers: list[str] | None = None, record_type: str = 'A', additional_types: list[str] | None = None) → PoisoningCheckResult[source]¶

Check for DNS poisoning, censorship, or manipulation.

Queries the trusted control_server and compares its response against multiple test servers. CDN and anycast patterns are classified separately from true poisoning.

Parameters:

domain – Domain to test (e.g. "example.com").
control_server – Trusted DNS server IP used as the baseline. Defaults to "8.8.8.8" (Google DNS).
test_servers – Test server IPs. None uses get_public_dns_servers().
record_type – Record type to query. Defaults to "A".
additional_types – Extra record types to query on the control server for additional context.

Returns:

PoisoningCheckResult with comprehensive analysis fields.

Examples

>>> result = check_dns_poisoning("example.com")
>>> if result["poisoned"]:
...     print(f"Confidence: {result['confidence']}%")

>>> result = check_dns_poisoning(
...     "example.com", test_servers=["1.1.1.1", "9.9.9.9"]
... )

nadzoring.dns_lookup.compare_dns_servers(domain: str, servers: list[str], record_types: list[str], progress_callback: Callable[[], None] | None = None) → ServerComparisonResult[source]¶

Compare DNS responses from multiple servers for the same domain.

Uses the first server in servers as the baseline. Each subsequent server’s records are compared against the baseline; discrepancies are collected in differences.

Parameters:

domain – Domain name to query (e.g. "example.com").
servers – DNS server IPs to compare. The first entry is the baseline.
record_types – Record types to query on every server.
progress_callback – Called after each successful query. Useful for progress bars.

Returns:

ServerComparisonResult with domain, servers, and differences keys.

Examples

>>> result = compare_dns_servers(
...     "example.com",
...     servers=["8.8.8.8", "1.1.1.1"],
...     record_types=["A", "MX"],
... )
>>> result["differences"]
[]

nadzoring.dns_lookup.health_check_dns(domain: str, nameserver: str | None = None) → HealthCheckResult[source]¶

Perform a comprehensive DNS health check with scoring.

Evaluates A, AAAA, MX, NS, TXT, and CNAME records, computes per-type scores, and derives an overall health score and status.

CNAME at the apex (non-subdomain) is stored as 100 but excluded from the score average, since the record type is only meaningful for subdomains.

Parameters:

domain – Domain name to check (e.g. "example.com").
nameserver – Optional nameserver IP. None uses the system default.

Returns:

HealthCheckResult dict with domain, score, status, issues, warnings, and record_scores keys.

Examples

>>> result = health_check_dns("example.com")
>>> print(result["score"], result["status"])
>>> for rtype, score in result["record_scores"].items():
...     print(f"  {rtype}: {score}")

nadzoring.dns_lookup.resolve_dns(domain: str, record_type: RecordType = 'A', nameserver: str | None = None, *, include_ttl: bool = False, timeout: float = 5.0, lifetime: float = 10.0) → DNSResult¶

Perform DNS resolution with timing and structured error handling.

Resolves domain for record_type, measuring response time and optionally capturing TTL. All DNS errors are surfaced through the error field rather than raised.

Parameters:

domain – Domain name to resolve (e.g. "example.com").
record_type – DNS record type to query. Defaults to "A".
nameserver – Optional nameserver IP; None uses the system default.
include_ttl – Include TTL value in result. Defaults to False.
timeout – Per-nameserver query timeout in seconds. Defaults to 5.0.
lifetime – Total query lifetime in seconds. Defaults to 10.0.

Returns:

DNSResult dict with domain, record_type, records, ttl, error, and response_time keys.

Examples

>>> result = resolve_with_timer("example.com", "MX", include_ttl=True)
>>> if not result["error"]:
...     print(result["records"], result["ttl"])

nadzoring.dns_lookup.reverse_dns(ip_address: str, nameserver: str | None = None) → dict[str, str | float | None][source]¶

Perform a reverse DNS lookup to resolve an IP address to a hostname.

Queries the PTR record for ip_address using dns.reversename.from_address() for automatic in-addr.arpa / ip6.arpa name construction.

Parameters:

ip_address – IPv4 or IPv6 address to look up (e.g. "8.8.8.8").
nameserver – Optional nameserver IP. None uses the system default.

Returns:

ip_address — the original address queried
hostname — resolved hostname (trailing dot stripped), or None if lookup failed
error — error message string on failure, None on success
response_time — query time in milliseconds (2 d.p.), or None when the query timed out

Return type:

Dict with the following keys

Examples

>>> result = reverse_dns("8.8.8.8")
>>> result["hostname"]
'dns.google'

>>> result = reverse_dns("192.168.1.1")
>>> result["error"]
'No PTR record'

nadzoring.dns_lookup.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"])

nadzoring.dns_lookup package¶

Submodules¶