netcheck-ir 2.0.0__py3-none-any.whl

netcheck/__init__.py

@@ -0,0 +1,10 @@
+"""
+NetCheck — enterprise network triage, security posture, and IR/forensics
+with optional AI analysis (Claude / OpenAI / Azure / Ollama).
+
+Standard-library only at runtime (AI calls use urllib, no SDKs) so it runs in
+locked-down and air-gapped environments.
+"""
+
+__version__ = "2.0.0"
+__all__ = ["__version__"]

netcheck/__main__.py

@@ -0,0 +1,5 @@
+import sys
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

netcheck/ai.py

@@ -0,0 +1,255 @@
+"""
+netcheck.ai
+===========
+Pluggable AI analysis layer. Sends the *structured* diagnostic / security /
+forensic results to an LLM and gets back an expert narrative: root-cause
+ranking, remediation steps, and (for security/IR) triage guidance.
+
+Providers (all via raw HTTP - no third-party SDKs, so it works in locked-down
+and air-gapped environments):
+  - anthropic : Claude API           (cloud)
+  - openai    : OpenAI / compatible  (cloud or self-hosted via base_url)
+  - azure     : Azure OpenAI         (cloud, enterprise)
+  - ollama    : Ollama               (fully local / on-prem - no data leaves)
+
+API keys are read from environment variables only (see config.get_api_key).
+For cloud providers, internal IPs / hostnames / MACs are redacted by default
+before any data leaves the machine (config.ai.redact). Use Ollama for zero
+data egress.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.request
+import urllib.error
+
+from .config import AIConfig, get_api_key
+
+# --------------------------------------------------------------------------- #
+# Redaction (privacy guard for cloud providers)
+# --------------------------------------------------------------------------- #
+
+_PRIVATE_IP_RE = re.compile(
+    r"\b(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}"
+    r"|172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}"
+    r"|192\.168\.\d{1,3}\.\d{1,3}"
+    r"|169\.254\.\d{1,3}\.\d{1,3}"
+    r"|127\.\d{1,3}\.\d{1,3}\.\d{1,3})\b")
+_MAC_RE = re.compile(r"\b(?:[0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}\b")
+
+
+def redact(text: str, hostname: str = "") -> str:
+    """Mask internal IPs, MACs, and the local hostname. Public IPs are kept."""
+    text = _PRIVATE_IP_RE.sub("[REDACTED-INTERNAL-IP]", text)
+    text = _MAC_RE.sub("[REDACTED-MAC]", text)
+    if hostname:
+        text = re.sub(re.escape(hostname), "[REDACTED-HOST]", text, flags=re.I)
+    return text
+
+
+# --------------------------------------------------------------------------- #
+# Prompt construction
+# --------------------------------------------------------------------------- #
+
+SYSTEM_PROMPTS = {
+    "triage": (
+        "You are a senior network engineer doing incident triage. You are given "
+        "structured results from an automated network health check. Identify the "
+        "single most likely root cause, explain the reasoning concisely, and give "
+        "concrete, ordered remediation steps an on-call engineer can execute now. "
+        "Be precise and avoid generic advice. If the data is insufficient, say so."),
+    "security": (
+        "You are a senior security engineer performing a defensive posture review "
+        "of infrastructure the operator is authorised to assess. Given the security "
+        "findings, prioritise them by real-world risk, explain the impact of each, "
+        "and give specific hardening steps. Map issues to common frameworks (e.g. "
+        "CIS, OWASP) where relevant. Do not provide exploitation instructions."),
+    "incident": (
+        "You are an incident response lead. Given diagnostic, security, and host "
+        "forensic data captured during an incident, produce a concise IR analysis: "
+        "(1) likely nature and scope, (2) severity, (3) immediate containment steps, "
+        "(4) eradication & recovery actions, (5) what additional evidence to collect. "
+        "Follow standard IR phases. Be specific and actionable."),
+}
+
+
+def build_user_prompt(env: dict, results, findings, mode: str) -> str:
+    payload = {
+        "mode": mode,
+        "environment": {k: env.get(k) for k in
+                        ("os", "target", "timestamp")},  # minimal env, no host/IP
+        "checks": [
+            {"name": r.name, "status": r.status, "detail": r.detail,
+             "category": r.category, "data": r.data}
+            for r in results
+        ],
+        "rule_based_findings": findings,
+    }
+    return ("Here is the structured output of an automated network assessment. "
+            "Analyse it and respond as instructed.\n\n```json\n"
+            + json.dumps(payload, indent=2, default=str)
+            + "\n```")
+
+
+# --------------------------------------------------------------------------- #
+# HTTP helper
+# --------------------------------------------------------------------------- #
+
+def _post_json(url: str, headers: dict, body: dict, timeout: float) -> dict:
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(url, data=data, method="POST")
+    for k, v in headers.items():
+        req.add_header(k, v)
+    req.add_header("content-type", "application/json")
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return json.loads(resp.read().decode("utf-8", "replace"))
+
+
+# --------------------------------------------------------------------------- #
+# Providers
+# --------------------------------------------------------------------------- #
+
+class AIError(Exception):
+    pass
+
+
+def _provider_anthropic(cfg: AIConfig, system: str, user: str) -> str:
+    key = get_api_key("anthropic")
+    if not key:
+        raise AIError("ANTHROPIC_API_KEY is not set")
+    base = cfg.base_url or "https://api.anthropic.com"
+    url = base.rstrip("/") + "/v1/messages"
+    headers = {"x-api-key": key, "anthropic-version": "2023-06-01"}
+    body = {
+        "model": cfg.resolved_model(),
+        "max_tokens": cfg.max_tokens,
+        "system": system,
+        "messages": [{"role": "user", "content": user}],
+    }
+    resp = _post_json(url, headers, body, cfg.timeout)
+    parts = [b.get("text", "") for b in resp.get("content", [])
+             if b.get("type") == "text"]
+    return "\n".join(p for p in parts if p).strip()
+
+
+def _provider_openai(cfg: AIConfig, system: str, user: str) -> str:
+    key = get_api_key("openai")
+    base = cfg.base_url or "https://api.openai.com/v1"
+    is_official = "api.openai.com" in base
+    if is_official and not key:
+        raise AIError("OPENAI_API_KEY is not set")
+    url = base.rstrip("/") + "/chat/completions"
+    headers = {}
+    if key:
+        headers["Authorization"] = f"Bearer {key}"
+    body = {
+        "model": cfg.resolved_model(),
+        "messages": [{"role": "system", "content": system},
+                     {"role": "user", "content": user}],
+    }
+    if cfg.max_tokens:
+        # Official OpenAI uses max_completion_tokens; compat servers use max_tokens.
+        body["max_completion_tokens" if is_official else "max_tokens"] = cfg.max_tokens
+    resp = _post_json(url, headers, body, cfg.timeout)
+    return resp["choices"][0]["message"]["content"].strip()
+
+
+def _provider_azure(cfg: AIConfig, system: str, user: str) -> str:
+    key = get_api_key("azure")
+    if not key:
+        raise AIError("AZURE_OPENAI_API_KEY is not set")
+    endpoint = cfg.base_url or os.environ.get("AZURE_OPENAI_ENDPOINT", "")
+    if not endpoint:
+        raise AIError("Azure endpoint not set (config ai.base_url or AZURE_OPENAI_ENDPOINT)")
+    deployment = cfg.deployment or cfg.model
+    if not deployment:
+        raise AIError("Azure deployment name not set (config ai.deployment)")
+    url = (endpoint.rstrip("/") +
+           f"/openai/deployments/{deployment}/chat/completions"
+           f"?api-version={cfg.api_version}")
+    headers = {"api-key": key}
+    body = {
+        "messages": [{"role": "system", "content": system},
+                     {"role": "user", "content": user}],
+        "max_tokens": cfg.max_tokens,
+    }
+    resp = _post_json(url, headers, body, cfg.timeout)
+    return resp["choices"][0]["message"]["content"].strip()
+
+
+def _provider_ollama(cfg: AIConfig, system: str, user: str) -> str:
+    base = (cfg.base_url or os.environ.get("OLLAMA_HOST")
+            or "http://localhost:11434")
+    if not base.startswith("http"):
+        base = "http://" + base
+    url = base.rstrip("/") + "/api/chat"
+    headers = {}
+    key = get_api_key("ollama")
+    if key:  # for Ollama behind an authenticating proxy
+        headers["Authorization"] = f"Bearer {key}"
+    body = {
+        "model": cfg.resolved_model(),
+        "messages": [{"role": "system", "content": system},
+                     {"role": "user", "content": user}],
+        "stream": False,
+        "options": {"num_predict": cfg.max_tokens},
+    }
+    resp = _post_json(url, headers, body, cfg.timeout)
+    return (resp.get("message", {}) or {}).get("content", "").strip()
+
+
+_PROVIDERS = {
+    "anthropic": _provider_anthropic,
+    "openai": _provider_openai,
+    "azure": _provider_azure,
+    "ollama": _provider_ollama,
+}
+
+CLOUD_PROVIDERS = {"anthropic", "openai", "azure"}
+
+
+def list_providers():
+    return sorted(_PROVIDERS)
+
+
+def analyze(cfg: AIConfig, env: dict, results, findings, mode: str = "triage") -> dict:
+    """Run AI analysis. Returns {ok, provider, model, text, error}."""
+    out = {"ok": False, "provider": cfg.provider,
+           "model": cfg.resolved_model(), "text": "", "error": ""}
+    fn = _PROVIDERS.get(cfg.provider)
+    if fn is None:
+        out["error"] = f"unknown provider '{cfg.provider}'"
+        return out
+
+    system = SYSTEM_PROMPTS.get(mode, SYSTEM_PROMPTS["triage"])
+    user = build_user_prompt(env, results, findings, mode)
+
+    # Privacy guard: redact internal identifiers before any cloud call.
+    if cfg.redact and cfg.provider in CLOUD_PROVIDERS:
+        host = env.get("hostname", "")
+        user = redact(user, host)
+
+    try:
+        text = fn(cfg, system, user)
+        if not text:
+            out["error"] = "empty response from model"
+            return out
+        out["ok"] = True
+        out["text"] = text
+    except urllib.error.HTTPError as e:
+        detail = ""
+        try:
+            detail = e.read().decode("utf-8", "replace")[:300]
+        except Exception:
+            pass
+        out["error"] = f"HTTP {e.code}: {detail or e.reason}"
+    except urllib.error.URLError as e:
+        out["error"] = f"connection error: {e.reason}"
+    except AIError as e:
+        out["error"] = str(e)
+    except Exception as e:
+        out["error"] = f"{type(e).__name__}: {e}"
+    return out

netcheck/checks.py

@@ -0,0 +1,322 @@
+"""
+netcheck.checks
+===============
+The layered diagnostic checks. Each returns a CheckResult; run_diagnostics()
+orchestrates them in OSI order.
+"""
+
+from __future__ import annotations
+
+import concurrent.futures
+import socket
+import time
+from datetime import datetime, timezone
+
+from . import core
+from .core import (CheckResult, OK, WARN, FAIL, INFO, SKIP,
+                   ping, tcp_connect, dns_query_a, http_probe, tls_check,
+                   is_private_or_bogus, OSNAME, run_cmd)
+from .config import (AppConfig, INTERNET_ANCHORS, PUBLIC_RESOLVERS,
+                     DNS_PROBE_NAME, CAPTIVE_PROBES, PORT_NAMES)
+
+
+def gather_env(cfg: AppConfig) -> dict:
+    return {
+        "hostname": socket.gethostname(),
+        "os": f"{core.platform.system()} {core.platform.release()}",
+        "python": core.platform.python_version(),
+        "local_ip": core.get_local_ip(),
+        "local_ipv6": core.get_local_ipv6(),
+        "gateway": core.get_default_gateway(),
+        "dns_servers": core.get_configured_dns(),
+        "target": cfg.target,
+        "operator": cfg.operator,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def check_interface(env: dict) -> CheckResult:
+    ip = env.get("local_ip")
+    if not ip:
+        return CheckResult("Local interface", FAIL,
+                           "No outbound IPv4 address - interface down or no DHCP lease",
+                           {"has_ip": False})
+    if ip.startswith("169.254."):
+        return CheckResult("Local interface", FAIL,
+                           f"APIPA address {ip} - DHCP failed", {"has_ip": True, "apipa": True})
+    return CheckResult("Local interface", OK, f"IPv4 {ip}", {"has_ip": True, "ip": ip})
+
+
+def check_gateway(env: dict) -> CheckResult:
+    gw = env.get("gateway")
+    if not gw:
+        return CheckResult("Gateway reachability", WARN, "Could not determine default gateway",
+                           {"gateway": None})
+    st = ping(gw, count=3)
+    data = {"gateway": gw, "loss_pct": st.loss_pct, "rtt_avg_ms": st.rtt_avg_ms,
+            "reachable": st.reachable}
+    if not st.reachable:
+        return CheckResult("Gateway reachability", FAIL,
+                           f"Cannot reach gateway {gw} - local link/Wi-Fi/router problem", data)
+    if st.loss_pct and st.loss_pct > 0:
+        return CheckResult("Gateway reachability", WARN, f"{gw} reachable but {st.loss_pct:.0f}% loss", data)
+    return CheckResult("Gateway reachability", OK,
+                       f"{gw}  {st.rtt_avg_ms:.1f}ms" if st.rtt_avg_ms else f"{gw} reachable", data)
+
+
+def check_internet(cfg: AppConfig) -> CheckResult:
+    results, any_ok = [], False
+    for ip, name in INTERNET_ANCHORS:
+        ok, lat, err = tcp_connect(ip, 443, timeout=cfg.timeout)
+        results.append({"ip": ip, "name": name, "ok": ok, "latency_ms": lat, "err": err})
+        any_ok = any_ok or ok
+    st = ping(INTERNET_ANCHORS[0][0], count=4)
+    data = {"anchors": results, "icmp_loss_pct": st.loss_pct, "icmp_rtt_avg_ms": st.rtt_avg_ms,
+            "icmp_jitter_ms": st.jitter_ms, "reachable": any_ok}
+    if not any_ok:
+        return CheckResult("Internet (by IP)", FAIL,
+                           "No route to the internet - cannot reach 1.1.1.1 or 8.8.8.8 on :443", data)
+    good = next(r for r in results if r["ok"])
+    return CheckResult("Internet (by IP)", OK,
+                       f"reachable via {good['name']} {good['ip']}  {good['latency_ms']:.0f}ms", data)
+
+
+def check_dns(cfg: AppConfig) -> CheckResult:
+    per = []
+    try:
+        sys_ips = sorted({ai[4][0] for ai in socket.getaddrinfo(DNS_PROBE_NAME, None,
+                                                                family=socket.AF_INET)})
+        sys_err = ""
+    except Exception as e:
+        sys_ips, sys_err = [], type(e).__name__
+    per.append({"server": "system", "name": "system resolver", "ips": sys_ips,
+                "error": sys_err, "latency_ms": None})
+
+    def q(item):
+        ip, name = item
+        ips, lat, err = dns_query_a(DNS_PROBE_NAME, ip, timeout=cfg.timeout)
+        return {"server": ip, "name": name, "ips": ips, "error": err, "latency_ms": lat}
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=len(PUBLIC_RESOLVERS)) as ex:
+        per.extend(ex.map(q, PUBLIC_RESOLVERS))
+
+    sys_ok = bool(sys_ips)
+    public_ok = [r for r in per if r["server"] != "system" and r["ips"]]
+    hijacked = [r["name"] for r in per for ip in r["ips"] if is_private_or_bogus(ip)]
+    data = {"resolvers": per, "system_ok": sys_ok, "public_ok_count": len(public_ok),
+            "hijack_suspects": hijacked}
+
+    if hijacked:
+        return CheckResult("DNS resolution", WARN,
+                           f"Suspicious private-IP answers from: {', '.join(set(hijacked))} - possible hijack/captive portal",
+                           data)
+    if not sys_ok and not public_ok:
+        return CheckResult("DNS resolution", FAIL, "DNS fully broken - no resolver answered", data)
+    if not sys_ok and public_ok:
+        return CheckResult("DNS resolution", FAIL,
+                           "System DNS broken, but public resolvers (1.1.1.1) work - your configured DNS is the problem",
+                           data)
+    if sys_ok and len(public_ok) < len(PUBLIC_RESOLVERS):
+        slow = ", ".join(r["name"] for r in per if r["server"] != "system" and not r["ips"])
+        return CheckResult("DNS resolution", WARN,
+                           f"System DNS OK; unreachable public resolvers: {slow}", data)
+    avg = [r["latency_ms"] for r in public_ok if r["latency_ms"]]
+    lat_txt = f"  avg {sum(avg)/len(avg):.0f}ms" if avg else ""
+    return CheckResult("DNS resolution", OK,
+                       f"resolves on system + {len(public_ok)} public resolvers{lat_txt}", data)
+
+
+def check_ports(cfg: AppConfig) -> CheckResult:
+    target, ports = cfg.target, cfg.ports
+
+    def probe(port):
+        ok, lat, err = tcp_connect(target, port, timeout=cfg.timeout)
+        return {"port": port, "name": PORT_NAMES.get(port, "?"), "open": ok,
+                "latency_ms": lat, "error": err}
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=min(8, len(ports))) as ex:
+        port_results = list(ex.map(probe, ports))
+    port_results.sort(key=lambda p: ports.index(p["port"]))
+
+    opened = [p for p in port_results if p["open"]]
+    dns_failed = any("dns" in (p["error"] or "") for p in port_results)
+    data = {"target": target, "ports": port_results}
+    summary = "  ".join(f"{p['port']}/{p['name']}{'✓' if p['open'] else '✗'}" for p in port_results)
+    name = f"TCP ports → {target}"
+    if dns_failed:
+        return CheckResult(name, FAIL, f"cannot resolve {target} (DNS) - port test inconclusive", data)
+    if not opened:
+        return CheckResult(name, FAIL, f"no ports reachable on {target}  [{summary}]", data)
+    if len(opened) < len(port_results):
+        return CheckResult(name, WARN, summary, data)
+    return CheckResult(name, OK, summary, data)
+
+
+def check_http_captive(cfg: AppConfig) -> CheckResult:
+    def probe(item):
+        url, exp_status, exp_body = item
+        status, body, err = http_probe(url, timeout=cfg.timeout)
+        matched = (status == exp_status and (exp_body is None or exp_body.lower() in body.lower()))
+        return {"url": url, "status": status, "expected": exp_status, "matched": matched,
+                "intercepted": (status is not None and not matched), "err": err}
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=len(CAPTIVE_PROBES)) as ex:
+        probes = list(ex.map(probe, CAPTIVE_PROBES))
+    any_ok = any(p["matched"] for p in probes)
+    captive = any(p["intercepted"] for p in probes)
+    data = {"probes": probes, "captive_portal": captive and not any_ok, "internet_open": any_ok}
+    if any_ok and not captive:
+        return CheckResult("HTTP / captive portal", OK, "open internet confirmed (probes passed)", data)
+    if captive:
+        return CheckResult("HTTP / captive portal", WARN,
+                           "Captive portal detected - a login/splash page is intercepting traffic.", data)
+    return CheckResult("HTTP / captive portal", FAIL,
+                       "Connectivity probes failed - HTTP egress blocked or no internet", data)
+
+
+def check_tls(cfg: AppConfig) -> CheckResult:
+    host = cfg.target
+    name = f"TLS → {host}"
+    if 443 not in cfg.ports:
+        return CheckResult(name, SKIP, "443 not in port list")
+    res = tls_check(host, 443, timeout=cfg.timeout)
+    if res["verified"]:
+        exp = res.get("not_after", "")
+        return CheckResult(name, OK, "certificate valid" + (f" (expires {exp})" if exp else ""), res)
+    if res["clock_skew"]:
+        return CheckResult(name, WARN, "TLS validation failed - system clock looks wrong", res)
+    if res["expired"]:
+        return CheckResult(name, WARN, "server certificate is expired", res)
+    if res["not_yet_valid"]:
+        return CheckResult(name, WARN, "server certificate not yet valid", res)
+    return CheckResult(name, WARN, f"TLS handshake/validation failed: {res['error']}", res)
+
+
+def check_quality(internet_result: CheckResult) -> CheckResult:
+    if not internet_result or not internet_result.data.get("reachable"):
+        return CheckResult("Connection quality", SKIP, "internet unreachable")
+    d = internet_result.data
+    loss, rtt, jit = d.get("icmp_loss_pct"), d.get("icmp_rtt_avg_ms"), d.get("icmp_jitter_ms")
+    data = {"loss_pct": loss, "rtt_avg_ms": rtt, "jitter_ms": jit}
+    parts = []
+    if rtt is not None:
+        parts.append(f"{rtt:.0f}ms RTT")
+    if jit is not None:
+        parts.append(f"{jit:.0f}ms jitter")
+    if loss is not None:
+        parts.append(f"{loss:.0f}% loss")
+    detail = "  ".join(parts) or "no ICMP stats (ICMP may be filtered)"
+    status, notes = OK, []
+    if loss is not None and loss >= 5:
+        status, _ = WARN, notes.append("packet loss")
+    if rtt is not None and rtt >= 200:
+        status, _ = WARN, notes.append("high latency")
+    if jit is not None and jit >= 50:
+        status, _ = WARN, notes.append("high jitter")
+    if notes:
+        detail += "  (" + ", ".join(notes) + ")"
+    return CheckResult("Connection quality", status, detail, data)
+
+
+def _df_ping(host: str, payload: int) -> bool:
+    if OSNAME == "Windows":
+        cmd = ["ping", "-n", "1", "-w", "2000", "-f", "-l", str(payload), host]
+    elif OSNAME == "Darwin":
+        cmd = ["ping", "-c", "1", "-D", "-s", str(payload), host]
+    else:
+        cmd = ["ping", "-c", "1", "-W", "2", "-M", "do", "-s", str(payload), host]
+    rc, out = run_cmd(cmd, timeout=5)
+    low = out.lower()
+    if "too long" in low or "frag" in low or "needs to be fragmented" in low:
+        return False
+    return rc == 0 and ("1 received" in low or "1 packets received" in low
+                        or "received = 1" in low or "ttl=" in low)
+
+
+def check_mtu(cfg: AppConfig) -> CheckResult:
+    target = INTERNET_ANCHORS[0][0]
+    small_ok = _df_ping(target, 1200)
+    big_ok = _df_ping(target, 1472)
+    data = {"target": target, "df_1200": small_ok, "df_1500": big_ok}
+    if small_ok and not big_ok:
+        lo, hi = 1200, 1472
+        while hi - lo > 8:
+            mid = (lo + hi) // 2
+            if _df_ping(target, mid):
+                lo = mid
+            else:
+                hi = mid
+        data["estimated_mtu"] = lo + 28
+        return CheckResult("Path MTU", WARN,
+                           f"MTU black hole - 1500B blocked, ~{lo+28}B works (VPN/PPPoE). Clamp MSS / lower MTU.", data)
+    if not small_ok and not big_ok:
+        return CheckResult("Path MTU", SKIP, "ICMP DF probes filtered - cannot test", data)
+    return CheckResult("Path MTU", OK, "1500-byte packets pass (no black hole)", data)
+
+
+def check_traceroute(cfg: AppConfig) -> CheckResult:
+    target = cfg.target
+    name = f"Traceroute → {target}"
+    if OSNAME == "Windows":
+        cmd = ["tracert", "-d", "-h", "20", "-w", "1500", target]
+    else:
+        cmd = ["traceroute", "-n", "-m", "20", "-w", "2", target]
+    rc, out = run_cmd(cmd, timeout=60)
+    if rc == 127:
+        return CheckResult(name, SKIP, "traceroute not installed", {"raw": out})
+    import re
+    lines = [l for l in out.splitlines() if l.strip()]
+    hops = len([l for l in lines if re.match(r"\s*\d+", l)])
+    dead = 0
+    for l in reversed(lines):
+        if re.match(r"\s*\d+", l) and l.count("*") >= 3:
+            dead += 1
+        elif re.match(r"\s*\d+", l):
+            break
+    data = {"target": target, "hops": hops, "dead_tail_hops": dead, "raw": out}
+    if dead >= 2:
+        return CheckResult(name, WARN, f"path stops responding after hop {hops-dead} ({hops} total)", data)
+    return CheckResult(name, OK, f"reached target in {hops} hops", data)
+
+
+def check_ipv6(cfg: AppConfig, env: dict) -> CheckResult:
+    if not env.get("local_ipv6"):
+        return CheckResult("IPv6", INFO, "no global IPv6 address (IPv4-only network)", {"available": False})
+    ok, lat, err = tcp_connect("2606:4700:4700::1111", 443, timeout=cfg.timeout)
+    data = {"available": True, "reachable": ok, "latency_ms": lat}
+    if ok:
+        return CheckResult("IPv6", OK, f"reachable  {lat:.0f}ms", data)
+    return CheckResult("IPv6", WARN,
+                       "IPv6 present but no IPv6 internet - may cause slow 'Happy Eyeballs' fallbacks", data)
+
+
+def run_diagnostics(cfg: AppConfig, env: dict, emit=None):
+    """Run all diagnostic checks. `emit(result)` is called as each completes."""
+    results = []
+
+    def step(fn, *a):
+        t0 = time.perf_counter()
+        try:
+            r = fn(*a)
+        except Exception as e:
+            r = CheckResult(getattr(fn, "__name__", "check"), FAIL, f"internal error: {e}")
+        r.duration_ms = (time.perf_counter() - t0) * 1000
+        results.append(r)
+        if emit:
+            emit(r)
+        return r
+
+    step(check_interface, env)
+    step(check_gateway, env)
+    inet = step(check_internet, cfg)
+    step(check_dns, cfg)
+    step(check_ports, cfg)
+    step(check_http_captive, cfg)
+    step(check_tls, cfg)
+    step(lambda c: check_quality(inet), cfg)
+
+    if cfg.full:
+        step(check_ipv6, cfg, env)
+        step(check_mtu, cfg)
+        step(check_traceroute, cfg)
+    return results