nadzoring.dns_lookup.health module

DNS health check functionality for comprehensive domain DNS evaluation.

This module provides functions to perform health checks on DNS configurations, including scoring, validation, and detailed analysis of various record types.

class nadzoring.dns_lookup.health.DetailedCheckResult[source]

Bases: dict[str, Any]

Detailed DNS check result with per-record type information.

Provides granular information about each queried record type including actual records, response times, errors, and validations.

domain

The domain name that was checked.

Type:

str

records

Dictionary mapping record types to their resolved records.

Type:

dict[str, list[str]]

errors

Dictionary mapping record types to any errors encountered.

Type:

dict[str, str]

response_times

Dictionary mapping record types to response times in ms.

Type:

dict[str, float | None]

validations

Dictionary containing validation results for MX and TXT records.

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.

Contains overall health score, status, and detailed breakdown by record type.

domain

The domain name that was checked.

Type:

str

score

Overall health score (0-100).

Type:

int

status

Health status (‘healthy’, ‘degraded’, ‘unhealthy’).

Type:

str

issues

List of critical issues found.

Type:

list[str]

warnings

List of warnings found.

Type:

list[str]

record_scores

Dictionary mapping record types to their individual scores.

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 specified DNS record types for a domain and returns detailed information including actual records, response times, errors, and optional validation results for MX and TXT records.

Parameters:

  • domain – Domain name to check (e.g., “example.com”).

  • nameserver – Optional specific nameserver IP to use for queries. If None, uses system default resolvers.

  • record_types – List of DNS record types to query. If None, defaults to [“A”, “AAAA”, “MX”, “NS”, “TXT”, “CNAME”].

  • validate_mx – If True, perform additional validation on MX records (checks for duplicate priorities).

  • validate_txt – If True, perform additional validation on TXT records (checks SPF and DKIM compliance).

Returns:

Dictionary containing detailed check results:

  • domain: The domain that was checked

  • records: Dict mapping record types to lists of resolved records

  • errors: Dict mapping record types to error messages (if any)

  • response_times: Dict mapping record types to response times in ms

  • validations: Dict containing validation results:

    • mx: MX validation result (if validate_mx=True and MX records exist)

    • txt: TXT validation result (if validate_txt=True, TXT records exist)

Return type:

DetailedCheckResult

Examples

>>> # Basic check with default record types
>>> result = check_dns("example.com")
>>> if "A" in result["records"]:
...     print(f"A records: {result['records']['A']}")

>>> # Check specific record types with validation
>>> result = check_dns(
...     "example.com",
...     record_types=["MX", "TXT"],
...     validate_mx=True,
...     validate_txt=True,
... )
>>> if "validations" in result:
...     mx_valid = result["validations"].get("mx", {})
...     if not mx_valid.get("valid", True):
...         print("MX issues:", mx_valid.get("issues", []))

>>> # Check with custom nameserver
>>> result = check_dns(
...     "example.com", nameserver="1.1.1.1", record_types=["A", "AAAA"]
... )
>>> for rtype, time in result["response_times"].items():
...     print(f"{rtype} resolved in {time}ms")

Notes

  • Response times are in milliseconds, rounded to 2 decimal places

  • Records without trailing dots for consistency

  • MX validation checks for duplicate priorities

  • TXT validation checks SPF for missing all and DKIM for missing public key

  • Errors are recorded per record type if resolution fails

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

Perform a comprehensive DNS health check with scoring.

Evaluates the health of a domain’s DNS configuration by checking multiple record types, calculating individual scores, and producing an overall health score and status.

Parameters:

  • domain – Domain name to check (e.g., “example.com”).

  • nameserver – Optional specific nameserver IP to use for queries. If None, uses system default resolvers.

Returns:

Dictionary containing health check results:

  • domain: The domain that was checked

  • score: Overall health score (0-100)

  • status: Health status (‘healthy’, ‘degraded’, ‘unhealthy’)

  • issues: List of critical issues found during checks

  • warnings: List of non-critical warnings found

  • record_scores: Dict with scores for each record type:

    • A: IPv4 address records score

    • AAAA: IPv6 address records score

    • MX: Mail exchange records score

    • NS: Nameserver records score

    • TXT: Text records score

    • CNAME: Canonical name records score (if applicable)

Return type:

HealthCheckResult

Examples

>>> # Basic health check
>>> result = health_check_dns("example.com")
>>> print(f"Health score: {result['score']} - {result['status']}")
>>> for rtype, score in result["record_scores"].items():
...     print(f"  {rtype}: {score}")

>>> # Using specific nameserver
>>> result = health_check_dns("example.com", nameserver="8.8.8.8")
>>> if result["issues"]:
...     print("Issues found:", result["issues"])

Notes

  • Checks all major record types: A, AAAA, MX, NS, TXT, CNAME

  • CNAME records are only scored for subdomains (as per DNS standards)

  • Scores are calculated using validation rules from validation module

  • The final score is the average of all non-CNAME record scores

  • Status is determined by the overall score:

    • >= 80: healthy

    • 50-79: degraded

    • < 50: unhealthy