netdiag-mcp 0.2.0__tar.gz

netdiag_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AIKAWA Shigechika
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

netdiag_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: netdiag-mcp
+Version: 0.2.0
+Summary: MCP server wrapping dig, ping, mtr, whois and TLS/HTTP checks for on-demand network diagnostics
+Author: AIKAWA Shigechika
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shigechika/netdiag-mcp
+Project-URL: Repository, https://github.com/shigechika/netdiag-mcp
+Project-URL: Issues, https://github.com/shigechika/netdiag-mcp/issues
+Keywords: dns,dig,ping,mtr,whois,tls,network,mcp,model-context-protocol,diagnostics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Internet
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<2,>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+<!-- mcp-name: io.github.shigechika/netdiag-mcp -->
+
+# netdiag-mcp
+
+English | [日本語](README.ja.md)
+
+MCP server for on-demand network diagnostics — DNS lookups (with a DNSSEC AD-bit check), ping, an `mtr`-based path report, TCP port checks, HTTP status/redirect checks, TLS certificate inspection, and WHOIS, all from one server.
+
+Built for triaging "can't reach X" / "is DNS propagated yet" reports without shelling into a jump host for each one-off `dig`/`ping`/`curl`.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `dns_lookup` | Resolve a DNS record via `dig` (A/AAAA/MX/TXT/NS/CNAME/SOA/PTR/CAA), optionally against a specific resolver and over plain DNS/DoT/DoH |
+| `dnssec_check` | Query a known-validating resolver and report whether the AD bit is set (plain/DoT/DoH) — the only reliable way to confirm DNSSEC validation, since an RRSIG being present in a plain `dig` reply does not by itself prove anything validated it |
+| `ping_host` | ICMP ping (count clamped to 1-10) |
+| `traceroute_path` | Hop-by-hop path/loss report via `mtr --report` (fixed cycles, not a live/continuous run) |
+| `tcp_port_check` | Is a TCP port open — a plain socket connect, not a port scan |
+| `http_check` | HEAD/GET a URL and report status, redirect chain, and latency |
+| `tls_cert_check` | Fetch the certificate a host presents and report subject/issuer/validity/SANs |
+| `whois_lookup` | WHOIS lookup for a domain |
+| `asn_lookup` | ASN + country-code lookup for an IP, or org info for an AS number, via Team Cymru's whois service — no API key or GeoIP database needed |
+| `health_check` | Version and which wrapped binaries (`dig`/`ping`/`mtr`/`whois`) are present on PATH |
+
+All tools are read-only and single-target (no batch/sweep mode) — this is a
+convenience wrapper around checks an operator would run by hand, not a
+scanning tool. `nmap`-style multi-host/multi-port scanning is intentionally
+out of scope; deliberately probing many hosts or ports is a different,
+higher-blast-radius action that deserves its own tooling and approval flow.
+
+`tcp_port_check`, `http_check` and `tls_cert_check` use Python's own
+socket/ssl/httpx stack rather than shelling out to `nc`/`curl`/`openssl`, so
+those three tools work even on a host with only the `dig`/`ping`/`mtr`/`whois`
+binaries installed (or none of them — `health_check` reports which are
+missing without failing the whole server).
+
+`dns_lookup`/`dnssec_check` support DNS-over-TLS and DNS-over-HTTPS via
+`transport="dot"`/`"doh"` (dig's `+tls`/`+https`). This needs `dig` from
+BIND 9.18+ — an older `dig` rejects the flag outright rather than silently
+falling back to plain DNS, so a stale binary fails loudly instead of giving
+a false sense of having checked over an encrypted transport.
+
+`tls_cert_check`/`http_check` against a bare IP address can fail TLS
+handshake with a "handshake failure" or similar error on SNI-hosted /
+CDN-fronted origins (e.g. behind Cloudflare) — TLS's SNI extension only
+carries hostnames, so an IP literal can't route to the right certificate on
+a shared edge. This is normal TLS behavior, not a tool bug; check by
+hostname when the target is CDN-fronted.
+
+## Setup
+
+### 1. System dependencies
+
+`dns_lookup`, `dnssec_check`, `ping_host`, `traceroute_path` and
+`whois_lookup` shell out to `dig`, `ping`, `mtr` and `whois` respectively.
+Install whichever of these you want available:
+
+```bash
+# Debian/Ubuntu
+sudo apt install dnsutils iputils-ping mtr-tiny whois
+```
+
+`mtr` needs raw-socket access. Debian/Ubuntu's `mtr-tiny` package grants
+`cap_net_raw` to the `mtr-packet` helper at install time, so it normally
+works for an unprivileged service user without further setup — verify with
+`getcap "$(command -v mtr-packet)"` if `traceroute_path` reports a socket
+permission error. Without that capability, `traceroute_path` fails cleanly
+with a `ToolError` rather than crashing the server.
+
+### 2. Install
+
+```bash
+pip install netdiag-mcp
+# or
+uv tool install netdiag-mcp
+```
+
+### 3. Claude Code (manual)
+
+```bash
+claude mcp add netdiag -- netdiag-mcp
+```
+
+No environment variables are required.
+
+## CLI
+
+```bash
+netdiag-mcp --version   # print version
+netdiag-mcp --check     # report which wrapped binaries are present (exit 0 when all are)
+```
+
+## Security notes
+
+- Every external-binary call passes an argv list (never a shell string), so
+  no tool argument can break out into shell syntax.
+- Hostname/IP and port arguments are validated and size/range-clamped before
+  use — tool input is model-driven and treated as untrusted, the same as any
+  other tool-calling surface.
+- `tcp_port_check` connects to exactly one host:port per call; there is no
+  loop or range argument, by design.
+
+## License
+
+MIT

netdiag_mcp-0.2.0/README.md

@@ -0,0 +1,106 @@
+<!-- mcp-name: io.github.shigechika/netdiag-mcp -->
+
+# netdiag-mcp
+
+English | [日本語](README.ja.md)
+
+MCP server for on-demand network diagnostics — DNS lookups (with a DNSSEC AD-bit check), ping, an `mtr`-based path report, TCP port checks, HTTP status/redirect checks, TLS certificate inspection, and WHOIS, all from one server.
+
+Built for triaging "can't reach X" / "is DNS propagated yet" reports without shelling into a jump host for each one-off `dig`/`ping`/`curl`.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `dns_lookup` | Resolve a DNS record via `dig` (A/AAAA/MX/TXT/NS/CNAME/SOA/PTR/CAA), optionally against a specific resolver and over plain DNS/DoT/DoH |
+| `dnssec_check` | Query a known-validating resolver and report whether the AD bit is set (plain/DoT/DoH) — the only reliable way to confirm DNSSEC validation, since an RRSIG being present in a plain `dig` reply does not by itself prove anything validated it |
+| `ping_host` | ICMP ping (count clamped to 1-10) |
+| `traceroute_path` | Hop-by-hop path/loss report via `mtr --report` (fixed cycles, not a live/continuous run) |
+| `tcp_port_check` | Is a TCP port open — a plain socket connect, not a port scan |
+| `http_check` | HEAD/GET a URL and report status, redirect chain, and latency |
+| `tls_cert_check` | Fetch the certificate a host presents and report subject/issuer/validity/SANs |
+| `whois_lookup` | WHOIS lookup for a domain |
+| `asn_lookup` | ASN + country-code lookup for an IP, or org info for an AS number, via Team Cymru's whois service — no API key or GeoIP database needed |
+| `health_check` | Version and which wrapped binaries (`dig`/`ping`/`mtr`/`whois`) are present on PATH |
+
+All tools are read-only and single-target (no batch/sweep mode) — this is a
+convenience wrapper around checks an operator would run by hand, not a
+scanning tool. `nmap`-style multi-host/multi-port scanning is intentionally
+out of scope; deliberately probing many hosts or ports is a different,
+higher-blast-radius action that deserves its own tooling and approval flow.
+
+`tcp_port_check`, `http_check` and `tls_cert_check` use Python's own
+socket/ssl/httpx stack rather than shelling out to `nc`/`curl`/`openssl`, so
+those three tools work even on a host with only the `dig`/`ping`/`mtr`/`whois`
+binaries installed (or none of them — `health_check` reports which are
+missing without failing the whole server).
+
+`dns_lookup`/`dnssec_check` support DNS-over-TLS and DNS-over-HTTPS via
+`transport="dot"`/`"doh"` (dig's `+tls`/`+https`). This needs `dig` from
+BIND 9.18+ — an older `dig` rejects the flag outright rather than silently
+falling back to plain DNS, so a stale binary fails loudly instead of giving
+a false sense of having checked over an encrypted transport.
+
+`tls_cert_check`/`http_check` against a bare IP address can fail TLS
+handshake with a "handshake failure" or similar error on SNI-hosted /
+CDN-fronted origins (e.g. behind Cloudflare) — TLS's SNI extension only
+carries hostnames, so an IP literal can't route to the right certificate on
+a shared edge. This is normal TLS behavior, not a tool bug; check by
+hostname when the target is CDN-fronted.
+
+## Setup
+
+### 1. System dependencies
+
+`dns_lookup`, `dnssec_check`, `ping_host`, `traceroute_path` and
+`whois_lookup` shell out to `dig`, `ping`, `mtr` and `whois` respectively.
+Install whichever of these you want available:
+
+```bash
+# Debian/Ubuntu
+sudo apt install dnsutils iputils-ping mtr-tiny whois
+```
+
+`mtr` needs raw-socket access. Debian/Ubuntu's `mtr-tiny` package grants
+`cap_net_raw` to the `mtr-packet` helper at install time, so it normally
+works for an unprivileged service user without further setup — verify with
+`getcap "$(command -v mtr-packet)"` if `traceroute_path` reports a socket
+permission error. Without that capability, `traceroute_path` fails cleanly
+with a `ToolError` rather than crashing the server.
+
+### 2. Install
+
+```bash
+pip install netdiag-mcp
+# or
+uv tool install netdiag-mcp
+```
+
+### 3. Claude Code (manual)
+
+```bash
+claude mcp add netdiag -- netdiag-mcp
+```
+
+No environment variables are required.
+
+## CLI
+
+```bash
+netdiag-mcp --version   # print version
+netdiag-mcp --check     # report which wrapped binaries are present (exit 0 when all are)
+```
+
+## Security notes
+
+- Every external-binary call passes an argv list (never a shell string), so
+  no tool argument can break out into shell syntax.
+- Hostname/IP and port arguments are validated and size/range-clamped before
+  use — tool input is model-driven and treated as untrusted, the same as any
+  other tool-calling surface.
+- `tcp_port_check` connects to exactly one host:port per call; there is no
+  loop or range argument, by design.
+
+## License
+
+MIT

netdiag_mcp-0.2.0/netdiag_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""netdiag-mcp — on-demand network diagnostics MCP Server (dig, ping, mtr, whois, TLS/HTTP checks)."""
+
+__version__ = "0.2.0"  # x-release-please-version

netdiag_mcp-0.2.0/netdiag_mcp/__main__.py

@@ -0,0 +1,48 @@
+"""Entry point for netdiag-mcp."""
+
+import argparse
+import asyncio
+import os
+import sys
+
+from netdiag_mcp import __version__
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="On-demand network diagnostics MCP Server (dig, ping, mtr, whois, TLS/HTTP checks)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+No required environment variables. Wrapped binaries (dig, ping, mtr, whois)
+must be on PATH; missing ones degrade health_check but do not stop the
+server, since the other tools (tcp_port_check, http_check, tls_cert_check)
+use Python's own socket/ssl/httpx stack and need no external binary.
+""",
+    )
+    parser.add_argument("--version", action="store_true", help="Print version and exit")
+    parser.add_argument("--check", action="store_true", help="Verify wrapped binaries are present, then exit")
+    args = parser.parse_args()
+
+    if args.version:
+        print(f"netdiag-mcp {__version__}")
+        sys.exit(0)
+
+    if args.check:
+        from netdiag_mcp.server import health_check
+
+        result = health_check()
+        print(f"{result['status']} — {result['service']} {result['version']}")
+        if result["missing"]:
+            print(f"missing binaries: {', '.join(result['missing'])}", file=sys.stderr)
+        sys.exit(0 if result["status"] == "healthy" else 2)
+
+    from netdiag_mcp.server import mcp
+
+    try:
+        mcp.run()
+    except (KeyboardInterrupt, asyncio.CancelledError):
+        os._exit(0)
+
+
+if __name__ == "__main__":
+    main()

netdiag_mcp-0.2.0/netdiag_mcp/server.py

@@ -0,0 +1,133 @@
+"""netdiag-mcp — MCP Server tools."""
+
+import shutil
+
+from mcp.server.fastmcp import FastMCP
+
+from netdiag_mcp import tools
+from netdiag_mcp.tools import ToolError
+
+mcp = FastMCP("netdiag-mcp")
+
+# health_check probes these; missing ones degrade rather than fail outright
+# so the server stays usable for whichever tools still have their binary.
+_REQUIRED_BINARIES = ("dig", "ping", "mtr", "whois")
+
+
+@mcp.tool()
+def health_check() -> dict:
+    """Service health: version and which wrapped binaries are present on PATH.
+
+    Returns a fixed shape (status/service/version + backend fields) so a
+    monitoring caller never has to branch on missing keys. status is
+    "healthy" when every wrapped binary is found, "degraded" when at least
+    one is missing (the corresponding tools will fail at call time).
+    """
+    from netdiag_mcp import __version__
+
+    binaries = {name: shutil.which(name) is not None for name in _REQUIRED_BINARIES}
+    missing = [name for name, present in binaries.items() if not present]
+    return {
+        "status": "healthy" if not missing else "degraded",
+        "service": "netdiag-mcp",
+        "version": __version__,
+        "binaries": binaries,
+        "missing": missing,
+    }
+
+
+@mcp.tool()
+def dns_lookup(hostname: str, record_type: str = "A", resolver: str | None = None, transport: str = "plain") -> str:
+    """Resolve a DNS record via `dig`. record_type: A/AAAA/MX/TXT/NS/CNAME/SOA/PTR/CAA.
+
+    Pass resolver to query a specific nameserver instead of the host default
+    (e.g. to check whether a change has propagated to a given resolver).
+    transport: "plain" (UDP/TCP 53, default), "dot" (DNS-over-TLS, 853) or
+    "doh" (DNS-over-HTTPS, 443). Requires dig from BIND 9.18+; an older dig
+    rejects dot/doh outright instead of silently querying over plain DNS.
+    """
+    try:
+        return tools.dns_lookup(hostname, record_type, resolver, transport)
+    except (ValueError, ToolError) as e:
+        return f"error: {e}"
+
+
+@mcp.tool()
+def dnssec_check(hostname: str, resolver: str = "1.1.1.1", transport: str = "plain") -> str:
+    """Check whether a name validates DNSSEC against a known-validating resolver (AD bit).
+
+    transport: "plain" (default), "dot" or "doh" — compare validation over
+    plain DNS vs. an encrypted transport when port 53 may be intercepted.
+    """
+    try:
+        return tools.dnssec_check(hostname, resolver, transport)
+    except (ValueError, ToolError) as e:
+        return f"error: {e}"
+
+
+@mcp.tool()
+def ping_host(host: str, count: int = 4) -> str:
+    """ICMP ping a host or IP. count is clamped to 1-10."""
+    try:
+        return tools.ping_host(host, count)
+    except (ValueError, ToolError) as e:
+        return f"error: {e}"
+
+
+@mcp.tool()
+def traceroute_path(host: str, cycles: int = 3) -> str:
+    """Path/MTU-style hop report via `mtr --report` (fixed cycles, not a live run). cycles clamped 1-10."""
+    try:
+        return tools.traceroute_path(host, cycles)
+    except (ValueError, ToolError) as e:
+        return f"error: {e}"
+
+
+@mcp.tool()
+def tcp_port_check(host: str, port: int, timeout: float = 5.0) -> str:
+    """Check whether a TCP port is open (plain socket connect, no port scanning)."""
+    try:
+        return tools.tcp_port_check(host, port, timeout)
+    except (ValueError, ToolError) as e:
+        return f"error: {e}"
+
+
+@mcp.tool()
+def http_check(url: str, timeout: float = 5.0) -> str:
+    """HEAD/GET a URL and report status, redirect chain and latency."""
+    try:
+        return tools.http_check(url, timeout)
+    except (ValueError, ToolError) as e:
+        return f"error: {e}"
+
+
+@mcp.tool()
+def tls_cert_check(host: str, port: int = 443) -> str:
+    """Fetch the TLS certificate presented on host:port and report subject/issuer/validity/SANs."""
+    try:
+        return tools.tls_cert_check(host, port)
+    except (ValueError, ToolError) as e:
+        return f"error: {e}"
+
+
+@mcp.tool()
+def whois_lookup(domain: str) -> str:
+    """WHOIS lookup for a domain."""
+    try:
+        return tools.whois_lookup(domain)
+    except (ValueError, ToolError) as e:
+        return f"error: {e}"
+
+
+@mcp.tool()
+def asn_lookup(target: str) -> str:
+    """ASN + country-code lookup for an IP, or org info for an AS number (e.g. AS15169 or 15169).
+
+    Via Team Cymru's whois service — no API key or GeoIP database needed.
+    Takes an IP literal or AS number, not a hostname; resolve first with
+    dns_lookup if you only have a name.
+    """
+    try:
+        return tools.asn_lookup(target)
+    except (ValueError, ToolError) as e:
+        return f"error: {e}"

netdiag_mcp-0.2.0/netdiag_mcp/tools.py

@@ -0,0 +1,253 @@
+"""Wrappers around external diagnostic binaries and Python's own socket/ssl/httpx stack.
+
+Every external-binary call uses an argv list (never shell=True), so no
+argument can break out into shell syntax regardless of what the caller
+passes — validate.py's job is bounding *size*, not escaping.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import platform
+import re
+import shutil
+import socket
+import ssl
+import subprocess
+import time
+
+import httpx
+
+from netdiag_mcp.validate import clamp, validate_port, validate_target
+
+DEFAULT_TIMEOUT = 5.0
+SUBPROCESS_TIMEOUT = 15.0
+
+DNS_RECORD_TYPES = {"A", "AAAA", "MX", "TXT", "NS", "CNAME", "SOA", "PTR", "CAA"}
+
+# dig flag for each transport. "plain" adds nothing (classic UDP/TCP port 53).
+# +tls/+https require dig from BIND 9.18+; an older dig rejects the flag
+# outright ("Invalid option", exit 1) rather than silently falling back to
+# plain DNS, so a stale `dig` fails loudly here instead of giving a false
+# sense of having checked over an encrypted transport.
+_DNS_TRANSPORT_FLAGS = {"plain": None, "dot": "+tls", "doh": "+https"}
+
+
+class ToolError(Exception):
+    """A tool could not run at all (missing binary, timeout, bad input)."""
+
+
+def _run(binary: str, args: list[str]) -> str:
+    if shutil.which(binary) is None:
+        raise ToolError(f"{binary} is not installed on this host")
+    try:
+        proc = subprocess.run(
+            [binary, *args],
+            capture_output=True,
+            text=True,
+            timeout=SUBPROCESS_TIMEOUT,
+        )
+    except subprocess.TimeoutExpired as e:
+        raise ToolError(f"{binary} timed out after {SUBPROCESS_TIMEOUT:g}s") from e
+    out = proc.stdout.strip()
+    err = proc.stderr.strip()
+    if proc.returncode != 0 and not out:
+        raise ToolError(err or f"{binary} exited {proc.returncode} with no output")
+    return out if not err else f"{out}\n[stderr] {err}" if out else err
+
+
+def _transport_flag(transport: str) -> str | None:
+    key = transport.strip().lower()
+    if key not in _DNS_TRANSPORT_FLAGS:
+        raise ToolError(f"unsupported transport {transport!r}; use one of {sorted(_DNS_TRANSPORT_FLAGS)}")
+    return _DNS_TRANSPORT_FLAGS[key]
+
+
+def dns_lookup(hostname: str, record_type: str = "A", resolver: str | None = None, transport: str = "plain") -> str:
+    """transport: "plain" (UDP/TCP 53, default), "dot" (DNS-over-TLS, 853) or "doh" (DNS-over-HTTPS, 443)."""
+    target = validate_target(hostname)
+    rtype = record_type.strip().upper()
+    if rtype not in DNS_RECORD_TYPES:
+        raise ToolError(f"unsupported record type {record_type!r}; use one of {sorted(DNS_RECORD_TYPES)}")
+    flag = _transport_flag(transport)
+    args = []
+    if resolver:
+        args.append(f"@{validate_target(resolver)}")
+    if flag:
+        args.append(flag)
+    args += [target, rtype, "+noall", "+answer", "+stats"]
+    return _run("dig", args)
+
+
+def dnssec_check(hostname: str, resolver: str = "1.1.1.1", transport: str = "plain") -> str:
+    """Query a validating resolver and report whether the AD (Authenticated Data) bit is set.
+
+    A bare `dig` reply with an RRSIG present does NOT mean DNSSEC validated
+    — only a resolver that itself validates and sets the AD flag proves
+    that. This deliberately targets a known-validating public resolver
+    rather than trusting whatever the host's default resolver is.
+
+    transport lets you compare validation over plain DNS vs. DoT/DoH — useful
+    when a network intercepts/spoofs port 53 but leaves 443/853 alone.
+    """
+    target = validate_target(hostname)
+    res = validate_target(resolver)
+    flag = _transport_flag(transport)
+    args = [f"@{res}"]
+    if flag:
+        args.append(flag)
+    args += [target, "+dnssec", "+noall", "+comment", "+answer"]
+    out = _run("dig", args)
+    ad_set = "flags:" in out and " ad" in out.split("flags:", 1)[1].split(";", 1)[0]
+    verdict = "DNSSEC validated (AD bit set)" if ad_set else "DNSSEC NOT validated (AD bit absent)"
+    return f"{verdict}\n\n{out}"
+
+
+def _is_ipv6_literal(target: str) -> bool:
+    try:
+        return ipaddress.ip_address(target).version == 6
+    except ValueError:
+        return False  # hostname — let ping's own resolver pick a family
+
+
+def ping_host(host: str, count: int = 4) -> str:
+    """ping with an explicit overall deadline where the binary supports one.
+
+    Without a deadline, an unreachable target makes `ping` wait its own
+    per-packet default for every probe (observed ~12s for count=2 against a
+    black-holed address), which can exceed SUBPROCESS_TIMEOUT and get
+    hard-killed into a generic "timed out" ToolError instead of ping's own
+    clean 100%-loss report. iputils (Linux, the deploy target) takes an
+    overall deadline via `-w`; BSD/macOS `ping` takes one via `-t`.
+
+    On Linux a single `ping` binary handles both families. BSD/macOS's
+    `ping` is IPv4-only and rejects an IPv6 literal outright ("cannot
+    resolve ...: Unknown host") — this dispatches to `ping6` there instead,
+    which has no overall-deadline flag at all (its `-t` means something
+    unrelated: an ICMPv6 Node Information query type), so an unreachable
+    IPv6 target on macOS falls back to the SUBPROCESS_TIMEOUT backstop and
+    a generic timeout error rather than a clean loss report — a narrow gap
+    limited to local macOS testing, since Linux never takes this branch.
+    An IPv6-only *hostname* on macOS still isn't handled (that would need a
+    pre-resolve this tool deliberately doesn't do), but a bare IPv6 literal
+    now works on both platforms.
+    """
+    target = validate_target(host)
+    n = clamp(count, 1, 10)
+    deadline = clamp(n * 2, 4, 10)
+    is_linux = platform.system() == "Linux"
+    binary = "ping" if is_linux or not _is_ipv6_literal(target) else "ping6"
+    args = ["-c", str(n)]
+    if binary != "ping6":
+        args += ["-w" if is_linux else "-t", str(deadline)]
+    args.append(target)
+    return _run(binary, args)
+
+
+def traceroute_path(host: str, cycles: int = 3) -> str:
+    """mtr in report mode — a fixed number of cycles, not a live/continuous run."""
+    target = validate_target(host)
+    n = clamp(cycles, 1, 10)
+    return _run("mtr", ["--report", "--report-cycles", str(n), "--no-dns", target])
+
+
+def whois_lookup(domain: str) -> str:
+    target = validate_target(domain)
+    return _run("whois", [target])
+
+
+_ASN_RE = re.compile(r"^(?:AS)?(\d{1,10})$", re.IGNORECASE)
+
+
+def asn_lookup(target: str) -> str:
+    """ASN + country-code lookup for an IP, or org info for an AS number, via
+    Team Cymru's whois service (whois.cymru.com) — no API key or GeoIP
+    database needed, reuses the `whois` binary already required by
+    whois_lookup. Accepts an IP literal or an AS number (`AS15169` or
+    `15169`), not a hostname — Cymru's service does prefix/ASN lookups, not
+    DNS resolution, so resolve a hostname with dns_lookup first.
+    """
+    stripped = target.strip()
+    m = _ASN_RE.match(stripped)
+    if m:
+        query = f"AS{m.group(1)}"
+    else:
+        try:
+            ipaddress.ip_address(stripped)
+        except ValueError as e:
+            raise ToolError(
+                f"asn_lookup takes an IP address or AS number (e.g. AS15169 or 15169), "
+                f"not a hostname: {target!r}. Resolve it first with dns_lookup."
+            ) from e
+        query = validate_target(stripped)
+    # The leading space before "-v" is a documented whois.cymru.com quirk:
+    # their server parses flags out of the raw query string itself (the
+    # standard whois protocol has no argv-style options), and drops the
+    # -v verbose header line without it.
+    return _run("whois", ["-h", "whois.cymru.com", f" -v {query}"])
+
+
+def tcp_port_check(host: str, port: int, timeout: float = DEFAULT_TIMEOUT) -> str:
+    """Native TCP connect probe — no `nc` dependency, no shell involved at all."""
+    target = validate_target(host)
+    p = validate_port(port)
+    t = clamp(timeout, 1, 15)
+    start = time.monotonic()
+    try:
+        with socket.create_connection((target, p), timeout=t):
+            elapsed_ms = (time.monotonic() - start) * 1000
+            return f"{target}:{p} open ({elapsed_ms:.1f}ms)"
+    except TimeoutError:
+        return f"{target}:{p} timed out after {t:g}s"
+    except (ConnectionRefusedError, OSError) as e:
+        return f"{target}:{p} closed/unreachable: {e}"
+
+
+def http_check(url: str, timeout: float = DEFAULT_TIMEOUT) -> str:
+    """HEAD (falling back to GET) via httpx — reports status, redirect chain and latency."""
+    t = clamp(timeout, 1, 15)
+    try:
+        with httpx.Client(follow_redirects=True, timeout=t) as client:
+            start = time.monotonic()
+            resp = client.head(url)
+            if resp.status_code == 405:
+                resp = client.get(url)
+            elapsed_ms = (time.monotonic() - start) * 1000
+    except httpx.HTTPError as e:
+        raise ToolError(f"HTTP request failed: {e}") from e
+    lines = [f"{resp.status_code} {resp.reason_phrase}  {elapsed_ms:.0f}ms  final_url={resp.url}"]
+    if resp.history:
+        chain = " -> ".join(str(r.url) for r in [*resp.history, resp])
+        lines.append(f"redirects: {chain}")
+    for header in ("server", "content-type", "content-length"):
+        if header in resp.headers:
+            lines.append(f"{header}: {resp.headers[header]}")
+    return "\n".join(lines)
+
+
+def tls_cert_check(host: str, port: int = 443) -> str:
+    """Native ssl/socket TLS handshake — reports the peer certificate, not raw openssl s_client text."""
+    target = validate_target(host)
+    p = validate_port(port)
+    ctx = ssl.create_default_context()
+    try:
+        with socket.create_connection((target, p), timeout=DEFAULT_TIMEOUT) as sock:
+            with ctx.wrap_socket(sock, server_hostname=target) as tls:
+                cert = tls.getpeercert()
+                cipher = tls.cipher()
+    except ssl.SSLCertVerificationError as e:
+        return f"TLS handshake failed certificate verification: {e}"
+    except (TimeoutError, OSError) as e:
+        raise ToolError(f"could not connect to {target}:{p}: {e}") from e
+    subject = dict(x[0] for x in cert.get("subject", []))
+    issuer = dict(x[0] for x in cert.get("issuer", []))
+    sans = [v for k, v in cert.get("subjectAltName", []) if k == "DNS"]
+    lines = [
+        f"subject: {subject.get('commonName', '?')}",
+        f"issuer: {issuer.get('commonName', '?')}",
+        f"validity: {cert.get('notBefore')} -> {cert.get('notAfter')}",
+        f"cipher: {cipher[0]} {cipher[1]}" if cipher else "cipher: ?",
+    ]
+    if sans:
+        lines.append(f"subjectAltName: {', '.join(sans)}")
+    return "\n".join(lines)

netdiag_mcp-0.2.0/netdiag_mcp/validate.py

@@ -0,0 +1,47 @@
+"""Input validation shared by every tool.
+
+Tool arguments are LLM-driven and must be treated as adversarial: nothing
+here ever builds a shell string (subprocess calls always pass argv lists),
+but sizes/counts/hostnames are still bounds-checked so a single tool call
+cannot become an amplification vector (e.g. an unbounded ping count) or a
+malformed argv0 for the wrapped binary.
+"""
+
+import ipaddress
+import re
+
+_HOSTNAME_RE = re.compile(r"^(?=.{1,253}$)(?!-)[A-Za-z0-9-]{1,63}(?<!-)(\.(?!-)[A-Za-z0-9-]{1,63}(?<!-))*\.?$")
+
+
+def validate_target(value: str) -> str:
+    """Return value unchanged if it is a plausible hostname or IP literal.
+
+    Raises ValueError otherwise. Deliberately permissive about *what* the
+    name resolves to (that is the point of the tool) — this only rejects
+    input that could not be a real target at all (empty, whitespace,
+    shell metacharacters, embedded newlines).
+    """
+    target = value.strip()
+    if not target or len(target) > 253:
+        raise ValueError("target must be a non-empty hostname or IP address")
+    if any(c.isspace() for c in target):
+        raise ValueError("target must not contain whitespace")
+    try:
+        ipaddress.ip_address(target)
+        return target
+    except ValueError:
+        pass
+    if not _HOSTNAME_RE.match(target):
+        raise ValueError(f"not a valid hostname or IP address: {value!r}")
+    return target
+
+
+def validate_port(value: int) -> int:
+    port = int(value)
+    if not 1 <= port <= 65535:
+        raise ValueError("port must be between 1 and 65535")
+    return port
+
+
+def clamp(value: int, low: int, high: int) -> int:
+    return max(low, min(high, int(value)))

netdiag_mcp-0.2.0/netdiag_mcp.egg-info/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: netdiag-mcp
+Version: 0.2.0
+Summary: MCP server wrapping dig, ping, mtr, whois and TLS/HTTP checks for on-demand network diagnostics
+Author: AIKAWA Shigechika
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shigechika/netdiag-mcp
+Project-URL: Repository, https://github.com/shigechika/netdiag-mcp
+Project-URL: Issues, https://github.com/shigechika/netdiag-mcp/issues
+Keywords: dns,dig,ping,mtr,whois,tls,network,mcp,model-context-protocol,diagnostics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Internet
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<2,>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+<!-- mcp-name: io.github.shigechika/netdiag-mcp -->
+
+# netdiag-mcp
+
+English | [日本語](README.ja.md)
+
+MCP server for on-demand network diagnostics — DNS lookups (with a DNSSEC AD-bit check), ping, an `mtr`-based path report, TCP port checks, HTTP status/redirect checks, TLS certificate inspection, and WHOIS, all from one server.
+
+Built for triaging "can't reach X" / "is DNS propagated yet" reports without shelling into a jump host for each one-off `dig`/`ping`/`curl`.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `dns_lookup` | Resolve a DNS record via `dig` (A/AAAA/MX/TXT/NS/CNAME/SOA/PTR/CAA), optionally against a specific resolver and over plain DNS/DoT/DoH |
+| `dnssec_check` | Query a known-validating resolver and report whether the AD bit is set (plain/DoT/DoH) — the only reliable way to confirm DNSSEC validation, since an RRSIG being present in a plain `dig` reply does not by itself prove anything validated it |
+| `ping_host` | ICMP ping (count clamped to 1-10) |
+| `traceroute_path` | Hop-by-hop path/loss report via `mtr --report` (fixed cycles, not a live/continuous run) |
+| `tcp_port_check` | Is a TCP port open — a plain socket connect, not a port scan |
+| `http_check` | HEAD/GET a URL and report status, redirect chain, and latency |
+| `tls_cert_check` | Fetch the certificate a host presents and report subject/issuer/validity/SANs |
+| `whois_lookup` | WHOIS lookup for a domain |
+| `asn_lookup` | ASN + country-code lookup for an IP, or org info for an AS number, via Team Cymru's whois service — no API key or GeoIP database needed |
+| `health_check` | Version and which wrapped binaries (`dig`/`ping`/`mtr`/`whois`) are present on PATH |
+
+All tools are read-only and single-target (no batch/sweep mode) — this is a
+convenience wrapper around checks an operator would run by hand, not a
+scanning tool. `nmap`-style multi-host/multi-port scanning is intentionally
+out of scope; deliberately probing many hosts or ports is a different,
+higher-blast-radius action that deserves its own tooling and approval flow.
+
+`tcp_port_check`, `http_check` and `tls_cert_check` use Python's own
+socket/ssl/httpx stack rather than shelling out to `nc`/`curl`/`openssl`, so
+those three tools work even on a host with only the `dig`/`ping`/`mtr`/`whois`
+binaries installed (or none of them — `health_check` reports which are
+missing without failing the whole server).
+
+`dns_lookup`/`dnssec_check` support DNS-over-TLS and DNS-over-HTTPS via
+`transport="dot"`/`"doh"` (dig's `+tls`/`+https`). This needs `dig` from
+BIND 9.18+ — an older `dig` rejects the flag outright rather than silently
+falling back to plain DNS, so a stale binary fails loudly instead of giving
+a false sense of having checked over an encrypted transport.
+
+`tls_cert_check`/`http_check` against a bare IP address can fail TLS
+handshake with a "handshake failure" or similar error on SNI-hosted /
+CDN-fronted origins (e.g. behind Cloudflare) — TLS's SNI extension only
+carries hostnames, so an IP literal can't route to the right certificate on
+a shared edge. This is normal TLS behavior, not a tool bug; check by
+hostname when the target is CDN-fronted.
+
+## Setup
+
+### 1. System dependencies
+
+`dns_lookup`, `dnssec_check`, `ping_host`, `traceroute_path` and
+`whois_lookup` shell out to `dig`, `ping`, `mtr` and `whois` respectively.
+Install whichever of these you want available:
+
+```bash
+# Debian/Ubuntu
+sudo apt install dnsutils iputils-ping mtr-tiny whois
+```
+
+`mtr` needs raw-socket access. Debian/Ubuntu's `mtr-tiny` package grants
+`cap_net_raw` to the `mtr-packet` helper at install time, so it normally
+works for an unprivileged service user without further setup — verify with
+`getcap "$(command -v mtr-packet)"` if `traceroute_path` reports a socket
+permission error. Without that capability, `traceroute_path` fails cleanly
+with a `ToolError` rather than crashing the server.
+
+### 2. Install
+
+```bash
+pip install netdiag-mcp
+# or
+uv tool install netdiag-mcp
+```
+
+### 3. Claude Code (manual)
+
+```bash
+claude mcp add netdiag -- netdiag-mcp
+```
+
+No environment variables are required.
+
+## CLI
+
+```bash
+netdiag-mcp --version   # print version
+netdiag-mcp --check     # report which wrapped binaries are present (exit 0 when all are)
+```
+
+## Security notes
+
+- Every external-binary call passes an argv list (never a shell string), so
+  no tool argument can break out into shell syntax.
+- Hostname/IP and port arguments are validated and size/range-clamped before
+  use — tool input is model-driven and treated as untrusted, the same as any
+  other tool-calling surface.
+- `tcp_port_check` connects to exactly one host:port per call; there is no
+  loop or range argument, by design.
+
+## License
+
+MIT

netdiag_mcp-0.2.0/netdiag_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+netdiag_mcp/__init__.py
+netdiag_mcp/__main__.py
+netdiag_mcp/server.py
+netdiag_mcp/tools.py
+netdiag_mcp/validate.py
+netdiag_mcp.egg-info/PKG-INFO
+netdiag_mcp.egg-info/SOURCES.txt
+netdiag_mcp.egg-info/dependency_links.txt
+netdiag_mcp.egg-info/entry_points.txt
+netdiag_mcp.egg-info/requires.txt
+netdiag_mcp.egg-info/top_level.txt
+tests/test_server.py
+tests/test_tools.py
+tests/test_validate.py

netdiag_mcp-0.2.0/netdiag_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

netdiag_mcp-0.2.0/netdiag_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+netdiag-mcp = netdiag_mcp.__main__:main

netdiag_mcp-0.2.0/netdiag_mcp.egg-info/requires.txt

@@ -0,0 +1,7 @@
+httpx>=0.27
+mcp<2,>=1.2
+
+[dev]
+pytest
+pytest-cov
+ruff

netdiag_mcp-0.2.0/netdiag_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+netdiag_mcp

netdiag_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "netdiag-mcp"
+dynamic = ["version"]
+description = "MCP server wrapping dig, ping, mtr, whois and TLS/HTTP checks for on-demand network diagnostics"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    {name = "AIKAWA Shigechika"},
+]
+keywords = ["dns", "dig", "ping", "mtr", "whois", "tls", "network", "mcp", "model-context-protocol", "diagnostics"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Networking",
+    "Topic :: Internet",
+]
+dependencies = [
+    "httpx>=0.27",
+    "mcp>=1.2,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "ruff",
+]
+
+[project.scripts]
+netdiag-mcp = "netdiag_mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/shigechika/netdiag-mcp"
+Repository = "https://github.com/shigechika/netdiag-mcp"
+Issues = "https://github.com/shigechika/netdiag-mcp/issues"
+
+[tool.setuptools]
+packages = ["netdiag_mcp"]
+
+[tool.setuptools.dynamic]
+version = {attr = "netdiag_mcp.__version__"}
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

netdiag_mcp-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

netdiag_mcp-0.2.0/tests/test_server.py

@@ -0,0 +1,57 @@
+import netdiag_mcp.server as server
+
+
+def test_health_check_shape_all_present(monkeypatch):
+    monkeypatch.setattr(server.shutil, "which", lambda _: "/usr/bin/x")
+    result = server.health_check()
+    assert result["status"] == "healthy"
+    assert result["service"] == "netdiag-mcp"
+    assert result["missing"] == []
+    assert set(result["binaries"]) == set(server._REQUIRED_BINARIES)
+
+
+def test_health_check_shape_degraded_when_missing(monkeypatch):
+    def fake_which(name):
+        return None if name == "mtr" else "/usr/bin/x"
+
+    monkeypatch.setattr(server.shutil, "which", fake_which)
+    result = server.health_check()
+    assert result["status"] == "degraded"
+    assert result["missing"] == ["mtr"]
+
+
+def test_dns_lookup_wraps_validation_error_as_string():
+    out = server.dns_lookup("bad host name", "A")
+    assert out.startswith("error:")
+
+
+def test_dns_lookup_delegates_to_tools(monkeypatch):
+    monkeypatch.setattr(server.tools, "dns_lookup", lambda h, r, s, t: f"{h}/{r}/{s}/{t}")
+    assert server.dns_lookup("example.com", "MX", None, "doh") == "example.com/MX/None/doh"
+
+
+def test_ping_host_wraps_tool_error(monkeypatch):
+    def raise_tool_error(*a, **k):
+        raise server.ToolError("ping not installed")
+
+    monkeypatch.setattr(server.tools, "ping_host", raise_tool_error)
+    out = server.ping_host("example.com")
+    assert out == "error: ping not installed"
+
+
+def test_tcp_port_check_rejects_bad_port():
+    out = server.tcp_port_check("example.com", 99999)
+    assert out.startswith("error:")
+
+
+def test_asn_lookup_wraps_tool_error(monkeypatch):
+    def raise_tool_error(*a, **k):
+        raise server.ToolError("not a hostname")
+
+    monkeypatch.setattr(server.tools, "asn_lookup", raise_tool_error)
+    assert server.asn_lookup("example.com") == "error: not a hostname"
+
+
+def test_asn_lookup_delegates_to_tools(monkeypatch):
+    monkeypatch.setattr(server.tools, "asn_lookup", lambda t: f"asn-result for {t}")
+    assert server.asn_lookup("8.8.8.8") == "asn-result for 8.8.8.8"

netdiag_mcp-0.2.0/tests/test_tools.py

@@ -0,0 +1,231 @@
+import socket
+import subprocess
+import threading
+
+import httpx
+import pytest
+
+from netdiag_mcp import tools
+from netdiag_mcp.tools import ToolError
+
+
+def test_run_raises_when_binary_missing(monkeypatch):
+    monkeypatch.setattr(tools.shutil, "which", lambda _: None)
+    with pytest.raises(ToolError, match="not installed"):
+        tools._run("dig", ["example.com"])
+
+
+def test_run_raises_on_timeout(monkeypatch):
+    monkeypatch.setattr(tools.shutil, "which", lambda _: "/usr/bin/dig")
+
+    def fake_run(*a, **k):
+        raise subprocess.TimeoutExpired(cmd="dig", timeout=15)
+
+    monkeypatch.setattr(subprocess, "run", fake_run)
+    with pytest.raises(ToolError, match="timed out"):
+        tools._run("dig", ["example.com"])
+
+
+def test_run_returns_stdout(monkeypatch):
+    monkeypatch.setattr(tools.shutil, "which", lambda _: "/usr/bin/dig")
+    proc = subprocess.CompletedProcess(args=[], returncode=0, stdout="192.0.2.1\n", stderr="")
+    monkeypatch.setattr(subprocess, "run", lambda *a, **k: proc)
+    assert tools._run("dig", ["example.com"]) == "192.0.2.1"
+
+
+def test_dns_lookup_rejects_unknown_record_type():
+    with pytest.raises(ToolError, match="unsupported record type"):
+        tools.dns_lookup("example.com", "BOGUS")
+
+
+def test_dns_lookup_rejects_bad_hostname():
+    with pytest.raises(ValueError):
+        tools.dns_lookup("not a host", "A")
+
+
+def test_dns_lookup_rejects_unknown_transport():
+    with pytest.raises(ToolError, match="unsupported transport"):
+        tools.dns_lookup("example.com", "A", transport="quic")
+
+
+def test_dns_lookup_plain_transport_adds_no_flag(monkeypatch):
+    captured = {}
+    monkeypatch.setattr(tools, "_run", lambda binary, args: captured.setdefault("args", args) or "ok")
+    tools.dns_lookup("example.com", "A", transport="plain")
+    assert "+tls" not in captured["args"]
+    assert "+https" not in captured["args"]
+
+
+@pytest.mark.parametrize("transport,flag", [("dot", "+tls"), ("doh", "+https")])
+def test_dns_lookup_encrypted_transport_adds_flag(monkeypatch, transport, flag):
+    captured = {}
+    monkeypatch.setattr(tools, "_run", lambda binary, args: captured.setdefault("args", args) or "ok")
+    tools.dns_lookup("example.com", "A", resolver="1.1.1.1", transport=transport)
+    assert flag in captured["args"]
+    assert "@1.1.1.1" in captured["args"]
+
+
+def test_dnssec_check_rejects_unknown_transport():
+    with pytest.raises(ToolError, match="unsupported transport"):
+        tools.dnssec_check("example.com", transport="quic")
+
+
+@pytest.mark.parametrize("transport,flag", [("dot", "+tls"), ("doh", "+https")])
+def test_dnssec_check_encrypted_transport_adds_flag(monkeypatch, transport, flag):
+    captured = {}
+
+    def fake_run(binary, args):
+        captured["args"] = args
+        return ";; flags: qr rd ra ad; QUERY: 1, ANSWER: 1"
+
+    monkeypatch.setattr(tools, "_run", fake_run)
+    tools.dnssec_check("example.com", transport=transport)
+    assert flag in captured["args"]
+
+
+def test_dnssec_check_detects_ad_flag(monkeypatch):
+    fake_output = ";; flags: qr rd ra ad; QUERY: 1, ANSWER: 1\nexample.com. 300 IN A 192.0.2.1"
+    monkeypatch.setattr(tools, "_run", lambda binary, args: fake_output)
+    result = tools.dnssec_check("example.com")
+    assert "DNSSEC validated" in result
+
+
+def test_dnssec_check_reports_missing_ad_flag(monkeypatch):
+    fake_output = ";; flags: qr rd ra; QUERY: 1, ANSWER: 1\nexample.com. 300 IN A 192.0.2.1"
+    monkeypatch.setattr(tools, "_run", lambda binary, args: fake_output)
+    result = tools.dnssec_check("example.com")
+    assert "NOT validated" in result
+
+
+def test_ping_host_clamps_count(monkeypatch):
+    captured = {}
+
+    def fake_run(binary, args):
+        captured["args"] = args
+        return "ok"
+
+    monkeypatch.setattr(tools, "_run", fake_run)
+    tools.ping_host("example.com", count=999)
+    assert captured["args"][1] == "10"  # clamped to the max
+
+
+def test_ping_host_sets_an_overall_deadline(monkeypatch):
+    """Regression guard: without a deadline flag an unreachable target makes
+    ping wait its own per-packet default for every probe (observed ~12s for
+    count=2 against a black-holed address), which can exceed
+    SUBPROCESS_TIMEOUT and turn a clean 100%-loss report into a hard-killed
+    generic timeout error instead."""
+    captured = {}
+    monkeypatch.setattr(tools, "_run", lambda binary, args: captured.setdefault("args", args) or "ok")
+    tools.ping_host("example.com", count=4)
+    assert "-w" in captured["args"] or "-t" in captured["args"]
+
+
+def test_ping_host_uses_ping6_for_ipv6_literal_on_macos(monkeypatch):
+    """Regression guard: BSD/macOS `ping` is IPv4-only and rejects an IPv6
+    literal outright ("cannot resolve ...: Unknown host") — a bare IPv6
+    literal must dispatch to `ping6` there. Linux's iputils `ping` handles
+    both, so this only applies off-Linux."""
+    captured = {}
+    monkeypatch.setattr(tools.platform, "system", lambda: "Darwin")
+    monkeypatch.setattr(tools, "_run", lambda binary, args: captured.setdefault("binary", binary) or "ok")
+    tools.ping_host("2001:db8::1")
+    assert captured["binary"] == "ping6"
+
+
+def test_ping_host_uses_ping_for_ipv4_on_macos(monkeypatch):
+    captured = {}
+    monkeypatch.setattr(tools.platform, "system", lambda: "Darwin")
+    monkeypatch.setattr(tools, "_run", lambda binary, args: captured.setdefault("binary", binary) or "ok")
+    tools.ping_host("192.0.2.1")
+    assert captured["binary"] == "ping"
+
+
+def test_ping_host_uses_ping_for_ipv6_on_linux(monkeypatch):
+    """Linux's iputils ping is dual-stack — no ping6 dispatch needed there."""
+    captured = {}
+    monkeypatch.setattr(tools.platform, "system", lambda: "Linux")
+    monkeypatch.setattr(tools, "_run", lambda binary, args: captured.setdefault("binary", binary) or "ok")
+    tools.ping_host("2001:db8::1")
+    assert captured["binary"] == "ping"
+
+
+def test_tcp_port_check_open_port():
+    server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    server.bind(("127.0.0.1", 0))
+    server.listen(1)
+    port = server.getsockname()[1]
+    t = threading.Thread(target=lambda: server.accept(), daemon=True)
+    t.start()
+    try:
+        result = tools.tcp_port_check("127.0.0.1", port, timeout=2)
+        assert "open" in result
+    finally:
+        server.close()
+
+
+def test_tcp_port_check_closed_port():
+    # Bind and immediately close to get a port nothing is listening on.
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    s.bind(("127.0.0.1", 0))
+    port = s.getsockname()[1]
+    s.close()
+    result = tools.tcp_port_check("127.0.0.1", port, timeout=2)
+    assert "closed" in result or "unreachable" in result
+
+
+def test_http_check_reports_status_and_headers(monkeypatch):
+    real_client = httpx.Client
+
+    def handler(request):
+        return httpx.Response(200, headers={"server": "test-server"}, request=request)
+
+    def fake_client(*args, **kwargs):
+        kwargs["transport"] = httpx.MockTransport(handler)
+        return real_client(*args, **kwargs)
+
+    monkeypatch.setattr(tools.httpx, "Client", fake_client)
+    result = tools.http_check("https://example.com")
+    assert "200" in result
+    assert "server: test-server" in result
+
+
+def test_http_check_wraps_transport_errors(monkeypatch):
+    real_client = httpx.Client
+
+    def handler(request):
+        raise httpx.ConnectError("boom", request=request)
+
+    def fake_client(*args, **kwargs):
+        kwargs["transport"] = httpx.MockTransport(handler)
+        return real_client(*args, **kwargs)
+
+    monkeypatch.setattr(tools.httpx, "Client", fake_client)
+    with pytest.raises(ToolError, match="HTTP request failed"):
+        tools.http_check("https://example.com")
+
+
+def test_tls_cert_check_raises_on_connection_failure():
+    # Port 1 is a reserved system port with nothing listening in CI/dev.
+    with pytest.raises(ToolError):
+        tools.tls_cert_check("127.0.0.1", 1)
+
+
+@pytest.mark.parametrize("value", ["AS15169", "as15169", "15169"])
+def test_asn_lookup_normalizes_as_number(monkeypatch, value):
+    captured = {}
+    monkeypatch.setattr(tools, "_run", lambda binary, args: captured.setdefault("args", args) or "ok")
+    tools.asn_lookup(value)
+    assert captured["args"] == ["-h", "whois.cymru.com", " -v AS15169"]
+
+
+def test_asn_lookup_passes_through_ip(monkeypatch):
+    captured = {}
+    monkeypatch.setattr(tools, "_run", lambda binary, args: captured.setdefault("args", args) or "ok")
+    tools.asn_lookup("8.8.8.8")
+    assert captured["args"] == ["-h", "whois.cymru.com", " -v 8.8.8.8"]
+
+
+def test_asn_lookup_rejects_hostname():
+    with pytest.raises(ToolError, match="not a hostname"):
+        tools.asn_lookup("example.com")

netdiag_mcp-0.2.0/tests/test_validate.py

@@ -0,0 +1,41 @@
+import pytest
+
+from netdiag_mcp.validate import clamp, validate_port, validate_target
+
+
+@pytest.mark.parametrize(
+    "value",
+    ["example.com", "sub.example.co.jp", "192.0.2.1", "2001:db8::1", "a.b", "localhost"],
+)
+def test_validate_target_accepts_valid_input(value):
+    assert validate_target(value) == value
+
+
+@pytest.mark.parametrize(
+    "value",
+    ["", "   ", "has space.com", "evil.com; rm -rf /", "a" * 254, "bad\nname.com"],
+)
+def test_validate_target_rejects_invalid_input(value):
+    with pytest.raises(ValueError):
+        validate_target(value)
+
+
+def test_validate_target_strips_surrounding_whitespace():
+    assert validate_target("  example.com  ") == "example.com"
+
+
+@pytest.mark.parametrize("value", [1, 80, 443, 65535])
+def test_validate_port_accepts_valid_range(value):
+    assert validate_port(value) == value
+
+
+@pytest.mark.parametrize("value", [0, -1, 65536, 100000])
+def test_validate_port_rejects_out_of_range(value):
+    with pytest.raises(ValueError):
+        validate_port(value)
+
+
+def test_clamp_bounds_both_directions():
+    assert clamp(-5, 1, 10) == 1
+    assert clamp(50, 1, 10) == 10
+    assert clamp(5, 1, 10) == 5