nadzoring.dns_lookup.types module

Type definitions for DNS lookup module.

class nadzoring.dns_lookup.types.BenchmarkResult

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

>>> result: BenchmarkResult = {
...     "server": "8.8.8.8",
...     "avg_response_time": 42.5,
...     "min_response_time": 15.2,
...     "max_response_time": 156.8,
...     "success_rate": 98.5,
...     "total_queries": 100,
...     "failed_queries": 2,
...     "responses": [15.2, 23.4, 31.7],
... }

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

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 record type: A/AAAA — IP addresses; MX — "priority mailserver" strings; TXT — concatenated text; others — string repr without trailing dots.

Type:

list[str]

ttl

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

Type:

int | None

error

Error message if resolution failed; None on success.

Type:

str | None

response_time

Query response time in milliseconds (2 d.p.), or None on timeout.

Type:

float | None

Examples

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

domain: str

error: str | None

record_type: str

records: list[str]

response_time: float | None

ttl: int | None

class nadzoring.dns_lookup.types.PoisoningCheckResult

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 server.

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 — NONE/LOW/MEDIUM/HIGH/CRITICAL/SUSPICIOUS.

Type:

str

confidence

Confidence score (0-100).

Type:

float

mismatches

Count of record mismatches.

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 levels to inconsistency counts.

Type:

dict[str, int]

unique_ips_seen

Distinct IPs 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, and owner.

Type:

list[dict[str, Any]]

consensus_rate

Percentage of servers returning the most common IP.

Type:

float

geo_diversity

Unique countries 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 is probable.

Type:

bool

Examples

>>> result: PoisoningCheckResult = {
...     "domain": "example.com",
...     "poisoned": False,
...     "confidence": 0.0,
...     "poisoning_level": "NONE",
... }

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.