Ping a host with ICMP echo requests and report packet loss and latency.

Answers: "Is this machine reachable at the network level, and how lossy or slow is the path?" Uses the system ping binary (unprivileged), so it works out of the box on macOS and Linux.

Args: host: Hostname, IPv4, or IPv6 address (e.g. "store-042.example.com", "10.1.42.1"). Validated strictly; shell metacharacters rejected. count: Number of echo requests to send, clamped to 1..10 (default 4).

Returns: On success: {"ok": true, "host", "count", "reachable", "packets_sent", "packets_received", "packet_loss_percent", "rtt_ms": {"min", "avg", "max"} | null}. On failure (unknown host, timeout, ping missing): {"ok": false, "error": "..."}.

Resolve DNS records for a name and report how long resolution took.

Answers: "Does this name resolve, to what, and is DNS itself slow or broken?" A/AAAA lookups go through the system resolver (socket.getaddrinfo) so they reflect what applications on this machine actually see; CNAME/MX/TXT/NS use dnspython.

Args: name: The DNS name to resolve (e.g. "vpn.example.com"). record_type: One of A, AAAA, CNAME, MX, TXT, NS (default "A").

Returns: On success: {"ok": true, "name", "record_type", "records": [...], "record_count", "resolution_time_ms"}. MX records are {"priority", "exchange"} dicts; other types are strings. On failure (NXDOMAIN, no answer, timeout): {"ok": false, "error": "..."}.

GET an http(s) URL, following redirects, and report response health.

Answers: "Is this web endpoint up, how fast does it answer, and where do its redirects land?" Only http:// and https:// URLs are accepted.

Args: url: Full URL to check (e.g. "https://portal.example.com/health"). timeout: Total request timeout in seconds, clamped to 1..30 (default 10).

Returns: On success: {"ok": true, "url", "status_code", "healthy" (true when status is 2xx/3xx), "latency_ms", "final_url", "redirect_count", "redirect_chain": [{"status_code", "url", "location"}], "server", "content_type", "response_bytes"}. On failure (timeout, connection error, bad scheme): {"ok": false, "error": "..."}.

Check whether ONE TCP port on a host accepts connections.

Answers: "Is the service listening?" — e.g. 443 on a payment gateway, 22 on a store server, 5432 on a database. This is deliberately a single-port diagnostic, not a scanner: exactly one integer port per call; ranges and lists are rejected.

Args: host: Hostname, IPv4, or IPv6 address. port: A single TCP port, integer 1..65535. timeout: Connect timeout in seconds, clamped to 1..30 (default 5).

Returns: On success: {"ok": true, "host", "port", "state": "open" | "closed" | "timeout", "latency_ms" (connect time for open/closed, null on timeout)}. On failure (unresolvable host, invalid port): {"ok": false, "error": "..."}.

Inspect the TLS certificate a host serves and flag looming expiry.

Answers: "Is this cert about to expire, who issued it, and which names does it cover?" Performs a verified TLS handshake using the system trust store; a cert that fails verification (expired, self-signed, wrong chain) is reported as an error with the verification reason.

Args: host: Hostname or IP to connect to (SNI uses this hostname). port: TCP port, integer 1..65535 (default 443).

Returns: On success: {"ok": true, "host", "port", "subject" (CN), "issuer_org", "issuer_cn", "not_before", "not_after", "days_until_expiry", "expiring_soon" (true when fewer than 30 days remain), "sans": [...], "tls_version"}. On failure: {"ok": false, "error": "..."}.

Trace the network path to a host, hop by hop, with per-hop latency.

Answers: "Where along the path does traffic slow down or die?" Uses the system traceroute binary (one probe per hop, 2s wait). If neither traceroute nor tracert exists on this system, that is returned as an error in the result, not raised.

Args: host: Hostname, IPv4, or IPv6 address. max_hops: Maximum hops to probe, clamped to 1..30 (default 15).

Returns: On success: {"ok": true, "host", "max_hops", "hop_count", "hops": [{"hop", "host" (name/IP or null when the hop timed out), "address", "rtt_ms"}]}. On failure: {"ok": false, "error": "..."}.

Run one diagnostic check across a whole fleet of hosts, concurrently.

The signature tool. Answers: "Which of my stores/gateways/servers are down right now, and which is the slowest?" Runs the chosen check on every host (up to 10 at a time) and returns a per-host results table plus an up/down summary.

Args: hosts: List of hostnames/IPs — capped at 50 per call; longer lists are rejected. For check="http", entries may be full URLs or bare hostnames (bare names are checked as https://). check: One of "ping" (2 ICMP probes per host), "port" (single TCP connect), or "http" (GET following redirects). Default "ping". port: Required when check="port": a single TCP port, integer 1..65535, used for every host. Ignored otherwise.

Returns: On success: {"ok": true, "check", "results": [{"host", "up", "latency_ms", "detail": }], "summary": {"up", "down", "total", "worst_latency_host"}}. A host that fails validation or its check counts as down, with the reason in its "detail". On bad input (too many hosts, missing port, unknown check): {"ok": false, "error": "..."}.