nadzoring.dns_lookup.health module¶

DNS health check functionality for comprehensive domain DNS evaluation.

class nadzoring.dns_lookup.health.DetailedCheckResult[source]¶

Bases: dict[str, Any]

Detailed DNS check result with per-record-type information.

A dict subclass providing granular information about each queried record type including resolved records, response times, errors, and optional validation results.

domain¶

Domain name that was checked.

Type:: str

records¶

Map of record type to list of resolved record strings.

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

errors¶

Map of record type to error message when resolution failed.

Type:: dict[str, str]

response_times¶

Map of record type to response time in milliseconds.

Type:: dict[str, float | None]

validations¶

Validation results for MX and TXT records when requested.

Type:: dict[str, dict[str, bool | list[str]]]

domain: str¶

errors: dict[str, str]¶

records: dict[str, list[str]]¶

response_times: dict[str, float | None]¶

validations: dict[str, dict[str, bool | list[str]]]¶

class nadzoring.dns_lookup.health.HealthCheckResult[source]¶

Bases: dict[str, Any]

Comprehensive DNS health check result.

A dict subclass carrying overall health score, status, and a per-record-type score breakdown.

domain¶

Domain name that was checked.

Type:: str

score¶

Overall health score (0-100).

Type:: int

status¶

Health status — "healthy", "degraded", or "unhealthy".

Type:: str

issues¶

Critical issues found during validation.

Type:: list[str]

warnings¶

Non-critical warnings found during validation.

Type:: list[str]

record_scores¶

Map of record type to its individual score.

Type:: dict[str, int]

domain: str¶

issues: list[str]¶

record_scores: dict[str, int]¶

score: int¶

status: str¶

warnings: list[str]¶

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