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 (recordinfo).
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 ${CLAUDE_PLUGIN_ROOT}/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 -vand record "tool not available" as a finding when missing.