dnsight

dnsight

dnsight — DNS, email, and web security hygiene.

AuditResult

Bases: BaseModel

Batch audit: one :class:DomainResult per manifest target (or CLI list).

Source code in src/dnsight/sdk/audit/models.py

class AuditResult(BaseModel):
    """Batch audit: one :class:`DomainResult` per manifest target (or CLI list)."""

    model_config = ConfigDict(frozen=True)

    timestamp: datetime = Field(..., description="When the batch completed (UTC)")
    config_version: int = Field(..., description="Config schema version used")
    domains: list[DomainResult] = Field(
        default_factory=list, description="Per-target domain audits in order"
    )

    @property
    def partial(self) -> bool:
        """True if any contained domain audit is partial."""
        return any(d.partial for d in self.domains)

partial property

True if any contained domain audit is partial.

RunAuditOptions dataclass

Options shared by domain audit, stream, and manifest batch runs.

When passed, overrides the individual checks / exclude / recursive / depth keyword arguments for that call.

Source code in src/dnsight/sdk/audit/options.py

@dataclass(frozen=True)
class RunAuditOptions:
    """Options shared by domain audit, stream, and manifest batch runs.

    When passed, overrides the individual ``checks`` / ``exclude`` / ``recursive`` /
    ``depth`` keyword arguments for that call.
    """

    checks: list[str] | None = None
    exclude: list[str] | None = None
    recursive: bool = False
    depth: int = 3

run_batch(*, config_path=None, mgr=None, checks=None, exclude=None, recursive=False, depth=3, options=None) async

Deprecated alias for :func:run_targets.

Source code in src/dnsight/sdk/run.py

async def run_batch(
    *,
    config_path: Path | str | None = None,
    mgr: ConfigManager | None = None,
    checks: list[str] | None = None,
    exclude: list[str] | None = None,
    recursive: bool = False,
    depth: int = 3,
    options: RunAuditOptions | None = None,
) -> AuditResult:
    """Deprecated alias for :func:`run_targets`."""
    warnings.warn(
        "run_batch is deprecated; use run_targets instead",
        DeprecationWarning,
        stacklevel=2,
    )
    return await run_targets(
        config_path=config_path,
        mgr=mgr,
        checks=checks,
        exclude=exclude,
        recursive=recursive,
        depth=depth,
        options=options,
    )

run_batch_sync(*, config_path=None, mgr=None, checks=None, exclude=None, recursive=False, depth=3, options=None)

Deprecated alias for :func:run_targets_sync.

Source code in src/dnsight/sdk/run.py

def run_batch_sync(
    *,
    config_path: Path | str | None = None,
    mgr: ConfigManager | None = None,
    checks: list[str] | None = None,
    exclude: list[str] | None = None,
    recursive: bool = False,
    depth: int = 3,
    options: RunAuditOptions | None = None,
) -> AuditResult:
    """Deprecated alias for :func:`run_targets_sync`."""
    warnings.warn(
        "run_batch_sync is deprecated; use run_targets_sync instead",
        DeprecationWarning,
        stacklevel=2,
    )
    return run_targets_sync(
        config_path=config_path,
        mgr=mgr,
        checks=checks,
        exclude=exclude,
        recursive=recursive,
        depth=depth,
        options=options,
    )

run_check(check_name, domain, *, config_path=None, mgr=None, config=None) async

Run one registered check for domain using merged config and runtime.

Source code in src/dnsight/sdk/run.py

async def run_check(
    check_name: str,
    domain: str,
    *,
    config_path: Path | str | None = None,
    mgr: ConfigManager | None = None,
    config: Config | None = None,
) -> CheckResult[Any]:
    """Run one registered check for *domain* using merged config and runtime."""
    import dnsight.checks  # noqa: F401

    m = resolve_run_manager(
        domain=domain,
        mgr=mgr,
        config_path=config_path,
        program_config=config,
        single_check=check_name,
    )
    return await run_check_for_target(check_name, domain, mgr=m)

run_check_sync(check_name, domain, *, config_path=None, mgr=None, config=None)

Synchronously run :func:run_check.

Source code in src/dnsight/sdk/run.py

def run_check_sync(
    check_name: str,
    domain: str,
    *,
    config_path: Path | str | None = None,
    mgr: ConfigManager | None = None,
    config: Config | None = None,
) -> CheckResult[Any]:
    """Synchronously run :func:`run_check`."""
    return asyncio.run(
        run_check(check_name, domain, config_path=config_path, mgr=mgr, config=config)
    )

run_domain(domain, *, config_path=None, mgr=None, checks=None, exclude=None, recursive=False, depth=3, options=None) async

Asynchronously run checks for domain and return a :class:DomainResult.

Source code in src/dnsight/sdk/run.py

async def run_domain(
    domain: str,
    *,
    config_path: Path | str | None = None,
    mgr: ConfigManager | None = None,
    checks: list[str] | None = None,
    exclude: list[str] | None = None,
    recursive: bool = False,
    depth: int = 3,
    options: RunAuditOptions | None = None,
) -> DomainResult:
    """Asynchronously run checks for *domain* and return a :class:`DomainResult`."""
    import dnsight.checks  # noqa: F401

    m = config_manager(mgr=mgr, config_path=config_path)
    return await audit_run_domain(
        domain,
        mgr=m,
        checks=checks,
        exclude=exclude,
        recursive=recursive,
        depth=depth,
        options=options,
    )

run_domain_stream(domain, *, config_path=None, mgr=None, checks=None, exclude=None, recursive=False, depth=3, options=None) async

Yield each zone's result depth-first (root first); not a nested tree.

Source code in src/dnsight/sdk/run.py

async def run_domain_stream(
    domain: str,
    *,
    config_path: Path | str | None = None,
    mgr: ConfigManager | None = None,
    checks: list[str] | None = None,
    exclude: list[str] | None = None,
    recursive: bool = False,
    depth: int = 3,
    options: RunAuditOptions | None = None,
) -> AsyncIterator[ZoneResult]:
    """Yield each zone's result depth-first (root first); not a nested tree."""
    import dnsight.checks  # noqa: F401

    m = config_manager(mgr=mgr, config_path=config_path)
    zone_stream = audit_run_domain_stream(
        domain,
        mgr=m,
        checks=checks,
        exclude=exclude,
        recursive=recursive,
        depth=depth,
        options=options,
    )
    async for z in zone_stream:
        yield z

run_domain_stream_sync(domain, *, config_path=None, mgr=None, checks=None, exclude=None, recursive=False, depth=3, options=None)

Synchronously collect all zone results depth-first (root first); not a nested tree.

Source code in src/dnsight/sdk/run.py

def run_domain_stream_sync(
    domain: str,
    *,
    config_path: Path | str | None = None,
    mgr: ConfigManager | None = None,
    checks: list[str] | None = None,
    exclude: list[str] | None = None,
    recursive: bool = False,
    depth: int = 3,
    options: RunAuditOptions | None = None,
) -> list[ZoneResult]:
    """Synchronously collect all zone results depth-first (root first); not a nested tree."""

    async def _collect() -> list[ZoneResult]:
        zone_stream = run_domain_stream(
            domain,
            config_path=config_path,
            mgr=mgr,
            checks=checks,
            exclude=exclude,
            recursive=recursive,
            depth=depth,
            options=options,
        )
        out: list[ZoneResult] = []
        async for z in zone_stream:
            out.append(z)
        return out

    return asyncio.run(_collect())

run_domain_sync(domain, *, config_path=None, mgr=None, checks=None, exclude=None, recursive=False, depth=3, options=None)

Synchronously run checks for domain and return a :class:DomainResult.

Source code in src/dnsight/sdk/run.py

def run_domain_sync(
    domain: str,
    *,
    config_path: Path | str | None = None,
    mgr: ConfigManager | None = None,
    checks: list[str] | None = None,
    exclude: list[str] | None = None,
    recursive: bool = False,
    depth: int = 3,
    options: RunAuditOptions | None = None,
) -> DomainResult:
    """Synchronously run checks for *domain* and return a :class:`DomainResult`."""
    return asyncio.run(
        run_domain(
            domain,
            config_path=config_path,
            mgr=mgr,
            checks=checks,
            exclude=exclude,
            recursive=recursive,
            depth=depth,
            options=options,
        )
    )

run_targets(*, config_path=None, mgr=None, checks=None, exclude=None, recursive=False, depth=3, options=None) async

Run a domain audit for each manifest targets row; returns :class:AuditResult.

Source code in src/dnsight/sdk/run.py

async def run_targets(
    *,
    config_path: Path | str | None = None,
    mgr: ConfigManager | None = None,
    checks: list[str] | None = None,
    exclude: list[str] | None = None,
    recursive: bool = False,
    depth: int = 3,
    options: RunAuditOptions | None = None,
) -> AuditResult:
    """Run a domain audit for each manifest ``targets`` row; returns :class:`AuditResult`."""
    import dnsight.checks  # noqa: F401

    m = config_manager(mgr=mgr, config_path=config_path)
    return await audit_run_config_targets(
        mgr=m,
        checks=checks,
        exclude=exclude,
        recursive=recursive,
        depth=depth,
        options=options,
    )

run_targets_sync(*, config_path=None, mgr=None, checks=None, exclude=None, recursive=False, depth=3, options=None)

Synchronously run :func:run_targets.

Source code in src/dnsight/sdk/run.py

def run_targets_sync(
    *,
    config_path: Path | str | None = None,
    mgr: ConfigManager | None = None,
    checks: list[str] | None = None,
    exclude: list[str] | None = None,
    recursive: bool = False,
    depth: int = 3,
    options: RunAuditOptions | None = None,
) -> AuditResult:
    """Synchronously run :func:`run_targets`."""
    return asyncio.run(
        run_targets(
            config_path=config_path,
            mgr=mgr,
            checks=checks,
            exclude=exclude,
            recursive=recursive,
            depth=depth,
            options=options,
        )
    )