# Network Diagnostics

> This skill should be used when the user asks to "debug my network", "internet is slow", "check connectivity", "why is my internet bad", "diagnose network", or mentions DNS, packet loss, or VPN issues. Performs read-only network diagnostics on macOS and writes a JSON result to ~/.mac-guardian/data/.

- Skill: `dennisonbertram/network-diagnostics` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dennisonbertram/network-diagnostics`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dennisonbertram/network-diagnostics/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dennisonbertram (https://skillmd.com/u/dennisonbertram)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dennisonbertram/network-diagnostics

---


# 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 ${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 -v` and record "tool not available" as a finding when missing.