network-diagnostics

Checks reachability, DNS, active interfaces, VPN state, and listening ports on a macOS machine.

When to invoke

Trigger on phrases like: "debug my network", "internet is slow", "check connectivity", "why is my internet bad", "diagnose network".

What to check

1. Default route — route -n get default 2>/dev/null. If no route, severity critical, summary "No default route — likely offline."

2. Latency and loss — ping -c 5 -t 5 1.1.1.1 and ping -c 5 -t 5 8.8.8.8. Parse the summary line for packet loss and round-trip.

• 0% loss, avg <50 ms: ok.
• <10% loss or avg 50–200 ms: info.
• 10–25% loss or avg 200–500 ms: warn.
• ≥25% loss or avg ≥500 ms: critical.

Skip gracefully if ping is blocked (record info).

3. DNS resolution — dig +short +time=3 +tries=1 google.com @1.1.1.1 and dig +short +time=3 +tries=1 apple.com. Empty result from either = warn. Missing dig (command -v dig) → fall back to nslookup or host; if none available record info.

4. Configured resolvers — scutil --dns | awk '/nameserver/ {print $NF}' | sort -u. List in raw.

5. Active hardware ports — networksetup -listallhardwareports. Record names and MAC addresses in raw (no severity).

6. Interfaces with IPv4 — ifconfig -a | awk '/^[a-z]/ {iface=$1} /inet /{print iface, $2}'. List in raw.

7. VPN state — detect presence of utun or ppp interfaces with an inet address. Any present = info "VPN-like interface active: …".

8. Listening ports (owned by this user) — lsof -iTCP -sTCP:LISTEN -P -n 2>/dev/null | awk 'NR==1 || $3 == ENVIRON["USER"]'. Summarise top 10 (command + port) in raw; no severity unless a well-known-but-unexpected port is open (22, 23, 3389, 5900) → info.

9. Established connections — lsof -iTCP -sTCP:ESTABLISHED -P -n 2>/dev/null | awk 'NR>1 {print $1, $9}' | sort -u | head -40. Record in raw.

10. Traceroute (optional, slow) — only run if latency check passed: traceroute -n -w 2 -q 1 -m 8 1.1.1.1. Include hop list in raw. Skip on timeout; do not spend more than ~15 seconds here.

Output contract

Standard envelope. Write to ~/.mac-guardian/data/network-diagnostics-<ISOdate>.json.

Set top-level severity to the worst finding severity. Summary should name the dominant problem ("22% packet loss to 1.1.1.1; DNS OK") or confirm "Network OK — 0% loss, 18 ms avg, DNS resolving."

Handoff

• On direct invocation: bash ${CLAUDEPLUGINROOT}/scripts/render-single.sh network-diagnostics.
• When invoked by daily-health-report, return the JSON path only.

Safety

• Read-only. Do not flush DNS, restart interfaces, or toggle VPN.
• Guard every external tool with command -v and record "tool not available" as a finding when missing.