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
from nadzoring.dns_lookup.errors import DNSResolveError

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]

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. The error field uses a Literal type for type-safe error handling.

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. Error strings are defined in DNSResolveError.

Type:: Literal[‘Domain does not exist’, ‘No records of requested type’, ‘Query timeout’, ‘Operation exceeded lifetime timeout’, ‘Resolver error’] | None

response_time¶

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

Type:: float | None

domain: str¶

error: Literal['Domain does not exist', 'No records of requested type', 'Query timeout', 'Operation exceeded lifetime timeout', 'Resolver error'] | 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

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.

This list excludes "ALL" (a CLI convenience token) and includes only concrete record types that can be queried directly.

type nadzoring.dns_lookup.types.RecordType = Literal['A', 'AAAA', 'CNAME', 'MX', 'NS', 'TXT', 'PTR', 'SOA', 'DNSKEY']¶

Supported DNS record types for queries and validation.

Values:

A: IPv4 address record
AAAA: IPv6 address record
CNAME: Canonical name (alias)
MX: Mail exchange record
NS: Nameserver record
TXT: Text record (including SPF, DKIM, DMARC)
PTR: Pointer record (reverse DNS)
SOA: Start of authority record
DNSKEY: DNSSEC key record

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

Bases: TypedDict

Reverse DNS lookup result for an IP address.

ip_address¶

The original IP address that was queried.

Type:: str

hostname¶

Resolved hostname with trailing dot stripped, or None when the lookup failed.

Type:: str | None

error¶

Error message if resolution failed; None on success. Error strings are defined in DNSReverseError.

Type:: Literal[‘No PTR record’, ‘No reverse DNS’, ‘Query timeout’, ‘Invalid IP address’, ‘Resolver error’] | None

response_time¶

Query round-trip time in milliseconds (2 d.p.), or None when the query timed out.

Type:: float | None

error: Literal['No PTR record', 'No reverse DNS', 'Query timeout', 'Invalid IP address', 'Resolver error'] | None¶

hostname: str | None¶

ip_address: str¶

response_time: float | None¶