nadzoring.dns_lookup.types module¶

Type definitions for the DNS lookup module.

All public TypedDict classes and type aliases used across nadzoring.dns_lookup are defined here so that consumers can import types from a single stable location.

Usage example:

from nadzoring.dns_lookup.types import DNSResult, RecordType

result: DNSResult = {
    "domain": "example.com",
    "record_type": "A",
    "records": ["93.184.216.34"],
    "ttl": 3600,
    "error": None,
    "response_time": 45.67,
}

class nadzoring.dns_lookup.types.BenchmarkResult[source]¶

Bases: TypedDict

DNS benchmark statistics for a single nameserver.

server¶

IP address of the tested DNS server.

Type:: str

avg_response_time¶

Average response time in milliseconds.

Type:: float

min_response_time¶

Fastest observed response time in milliseconds.

Type:: float

max_response_time¶

Slowest observed response time in milliseconds.

Type:: float

success_rate¶

Percentage of successful queries (0.0-100.0).

Type:: float

total_queries¶

Total number of queries attempted.

Type:: int

failed_queries¶

Number of queries that failed or timed out.

Type:: int

responses¶

Individual response times for successful queries.

Type:: list[float]

Examples

Iterate over benchmark results sorted fastest-first:

from nadzoring.dns_lookup.benchmark import benchmark_dns_servers

results = benchmark_dns_servers(
    servers=["8.8.8.8", "1.1.1.1"],
    queries=5,
)
for r in results:
    print(
        f"{r['server']}: "
        f"avg={r['avg_response_time']:.1f}ms  "
        f"ok={r['success_rate']}%"
    )

avg_response_time: float¶

failed_queries: int¶

max_response_time: float¶

min_response_time: float¶

responses: list[float]¶

server: str¶

success_rate: float¶

total_queries: int¶

class nadzoring.dns_lookup.types.DNSResult[source]¶

Bases: TypedDict

DNS resolution result for a single query.

All fields are optional to accommodate partial results from failed queries.

domain¶

The domain name that was queried.

Type:: str

record_type¶

The type of DNS record that was requested.

Type:: str

records¶

List of resolved record strings. Format varies by type:

A / AAAA — IP address strings
MX — "priority mailserver" strings
TXT — concatenated text chunks
SOA — space-joined SOA fields
others — str() with trailing dot stripped

Type:: list[str]

ttl¶

Time To Live in seconds, or None when not requested or unavailable.

Type:: int | None

error¶

Human-readable error message if resolution failed; None on success. Possible values:

"Domain does not exist" — NXDOMAIN
"No <type> records" — no records of this type
"Query timeout" — per-query timeout exceeded
arbitrary string — unexpected resolver error

Type:: str | None

response_time¶

Query round-trip time in milliseconds (2 d.p.), or None on timeout.

Type:: float | None

Examples

Check for errors before using records:

from nadzoring.dns_lookup.utils import resolve_with_timer

result = resolve_with_timer("example.com", "A")
if result["error"]:
    print("DNS error:", result["error"])
else:
    for record in result["records"]:
        print(record)
    print(f"RTT: {result['response_time']} ms")

domain: str¶

error: str | None¶

record_type: str¶

records: list[str]¶

response_time: float | None¶

ttl: int | None¶

class nadzoring.dns_lookup.types.PoisoningCheckResult[source]¶

Bases: TypedDict

DNS cache poisoning detection result.

Comprehensive analysis comparing responses from multiple resolvers against a trusted control server to detect poisoning, censorship, or manipulation.

domain¶

The domain name tested for poisoning.

Type:: str

record_type¶

DNS record type queried.

Type:: str

control_server¶

IP address of the trusted control resolver.

Type:: str

control_name¶

Provider name of the control server.

Type:: str

control_country¶

Country code of the control server.

Type:: str

control_result¶

DNS resolution result from the control resolver.

Type:: nadzoring.dns_lookup.types.DNSResult

control_analysis¶

IP pattern analysis of control server records.

Type:: dict[str, Any]

control_owner¶

Inferred owner of control server IPs.

Type:: str

additional_records¶

Optional extra record types from the control.

Type:: dict[str, nadzoring.dns_lookup.types.DNSResult] | None

test_results¶

Dict mapping test resolver IPs to their DNS results.

Type:: dict[str, nadzoring.dns_lookup.types.DNSResult]

test_servers_count¶

Number of test servers queried.

Type:: int

inconsistencies¶

Detected discrepancies between resolvers.

Type:: list[dict[str, Any]]

poisoned¶

True when poisoning indicators exceed the threshold.

Type:: bool

poisoning_level¶

Severity string — NONE / LOW / MEDIUM / HIGH / CRITICAL / SUSPICIOUS.

Type:: str

confidence¶

Confidence score from 0.0 to 100.0.

Type:: float

mismatches¶

Count of record mismatches across test servers.

Type:: int

cdn_variations¶

Count of CDN-related IP variations.

Type:: int

cdn_detected¶

Whether CDN usage was identified.

Type:: bool

cdn_owner¶

Name of the detected CDN provider.

Type:: str

cdn_percentage¶

Percentage of IPs belonging to the CDN.

Type:: float

severity¶

Dict mapping severity labels to inconsistency counts.

Type:: dict[str, int]

unique_ips_seen¶

Distinct IP count across all test results.

Type:: int

ip_diversity¶

IPs not present in the control result.

Type:: int

control_ip_count¶

IPs returned by the control server.

Type:: int

consensus_top¶

Top-3 most common IPs with count, percentage, owner.

Type:: list[dict[str, Any]]

consensus_rate¶

Percentage of servers returning the most common IP.

Type:: float

geo_diversity¶

Unique country count among test servers.

Type:: int

anycast_likely¶

True when anycast routing is probable.

Type:: bool

cdn_likely¶

True when CDN usage is probable.

Type:: bool

poisoning_likely¶

True when deliberate poisoning pattern found.

Type:: bool

Examples

Interpreting severity levels:

from nadzoring.dns_lookup.poisoning import check_dns_poisoning

result = check_dns_poisoning("example.com")

level = result.get("poisoning_level", "NONE")
# NONE     — everything looks consistent
# LOW      — minor variations, likely CDN/anycast
# MEDIUM   — notable inconsistencies, worth investigating
# HIGH     — strong signs of manipulation
# CRITICAL — near-certain poisoning or censorship
# SUSPICIOUS — unusual patterns that don't fit CDN

if result.get("poisoned"):
    for inc in result.get("inconsistencies", []):
        print(inc)

additional_records: dict[str, DNSResult] | None¶

anycast_likely: bool¶

cdn_detected: bool¶

cdn_likely: bool¶

cdn_owner: str¶

cdn_percentage: float¶

cdn_variations: int¶

confidence: float¶

consensus_rate: float¶

consensus_top: list[dict[str, Any]]¶

control_analysis: dict[str, Any]¶

control_country: str¶

control_ip_count: int¶

control_name: str¶

control_owner: str¶

control_result: DNSResult¶

control_server: str¶

domain: str¶

geo_diversity: int¶

inconsistencies: list[dict[str, Any]]¶

ip_diversity: int¶

mismatches: int¶

poisoned: bool¶

poisoning_level: str¶

poisoning_likely: bool¶

record_type: str¶

severity: dict[str, int]¶

test_results: dict[str, DNSResult]¶

test_servers_count: int¶

unique_ips_seen: int¶

nadzoring.dns_lookup.types.RECORD_TYPES: list[str] = ['A', 'AAAA', 'CNAME', 'MX', 'NS', 'TXT', 'PTR', 'SOA', 'DNSKEY']¶: List of all supported DNS record type strings.

type nadzoring.dns_lookup.types.RecordType = Literal['A', 'AAAA', 'CNAME', 'MX', 'NS', 'TXT', 'PTR', 'SOA', 'DNSKEY']¶: Supported DNS record types for queries and validation.