Plugins

The nadzoring.plugins package provides a small connector framework for probing hosts, services, and CI/CD systems from Python. It is separate from the Click CLI: connectors call the same domain functions the CLI uses and return a uniform ProbeResult.

This is intended for integrators who want to embed Nadzoring checks in monitoring pipelines, test harnesses, or orchestration without shelling out to nadzoring commands.

---

Concepts

Connector — A class inheriting ConnectorBase with a class-level meta and an implemented probe() method that returns ProbeResult.

Registry — PluginRegistry maps ConnectorMeta.name strings to connector classes, builds instances, and lists connectors by category or tag.

Categories — ConnectorCategory groups connectors as web, network, or cicd.

Built-in implementations live under nadzoring.plugins.connectors (DNS, network, security, ARP, HTTP, CI/CD). Optional Flask/Django/FastAPI examples live in nadzoring.plugins.examples.

---

Minimal example

from nadzoring.plugins import PluginRegistry
from nadzoring.plugins.connectors import DnsResolveConnector, PingConnector

registry = PluginRegistry()
registry.register(DnsResolveConnector)
registry.register(PingConnector)

dns_result = registry.build(
    "dns-resolve",
    domains=["example.com"],
    record_types=["A"],
).probe()

ping_result = registry.build("ping", addresses=["127.0.0.1"]).probe()

print(dns_result.status, dns_result.details)
print(ping_result.status, ping_result.error)

Several network and security connectors mark boolean and timeout fields as keyword-only in their dataclass constructors. This avoids passing a bare True/False positionally where it could be mistaken for a numeric parameter. Always pass those arguments by name (and the same applies to PluginRegistry.build, which forwards keyword arguments to the connector).

from nadzoring.plugins import PluginRegistry
from nadzoring.plugins.connectors import (
    ConnectionsConnector,
    HttpPingConnector,
    SslCertConnector,
    TracerouteConnector,
)

registry = PluginRegistry()
for cls in (
    HttpPingConnector,
    SslCertConnector,
    ConnectionsConnector,
    TracerouteConnector,
):
    registry.register(cls)

http = registry.build(
    "http-ping",
    urls=["https://example.com"],
    verify_ssl=True,
    follow_redirects=True,
    include_headers=False,
).probe()

tls = registry.build(
    "ssl-cert",
    domains=["example.com"],
    days_before=14,
    verify=True,
    full=False,
).probe()

connections = registry.build(
    "connections",
    protocol="tcp",
    state_filter="LISTEN",
    include_process=False,
).probe()

trace = registry.build(
    "traceroute",
    targets=["198.51.100.1"],
    max_hops=30,
    use_sudo=False,
).probe()

---

Result contract

ProbeResult fields:

• status — "ok", "degraded", "unreachable", or "error".

• error — Human-readable message when the probe did not fully succeed.

• latency_ms — Optional round-trip timing where applicable.

• details — Structured payload (often includes a "data" key with raw domain-layer results).

Connectors should follow the same rule as domain code: do not raise for expected failures (timeouts, HTTP 4xx/5xx, DNS errors). Surface them via status and error.

---

Timeouts

Network-oriented connectors accept TimeoutConfig (see Error Handling and domain documentation). Pass None only where the connector constructs defaults internally.

---

Linting note for contributors

ruff applies a few per-file ignores under src/nadzoring/plugins/ for lazy imports inside probe() and connector meta layout. See ruff.toml [lint.per-file-ignores] for the exact codes.