Net Detective#

Run structured network diagnostics and explain findings in plain English.

Scripts#

• scripts/diagnose.py — orchestrates all tests, outputs unified JSON
• scripts/dns_check.py — tests DNS resolution across Google, Cloudflare, and system resolvers
• scripts/speedtest.py — measures download throughput via curl (no external packages)
• scripts/history.py — records results over time, detects anomalies vs baseline
• scripts/report.py — converts diagnostic JSON into a plain-English markdown report

All scripts use Python stdlib only. Cross-platform: macOS and Linux.

Reference references/diagnostic-guide.md for what each test measures and common failure patterns.

Standard Workflow#

1. Run the full diagnostic#

bash

python3 scripts/diagnose.py > /tmp/net-diag.json

Add --speed to include a bandwidth test (adds ~20s):

bash

python3 scripts/diagnose.py --speed > /tmp/net-diag.json

Skip traceroute or MTU if time-constrained:

bash

python3 scripts/diagnose.py --no-traceroute --no-mtu > /tmp/net-diag.json

2. Compare against history (if available)#

bash

python3 scripts/history.py --compare /tmp/net-diag.json > /tmp/net-history.json

If no history exists yet, skip this step.

3. Generate the report#

Without history:

bash

python3 scripts/report.py /tmp/net-diag.json

With history comparison:

bash

python3 scripts/report.py /tmp/net-diag.json --history-compare /tmp/net-history.json

4. Record result to history#

bash

python3 scripts/history.py --record /tmp/net-diag.json

Do this after every diagnostic run to build a baseline over time.

Flags Reference#

ScriptFlagEffectdiagnose.py``--speedInclude bandwidth testdiagnose.py``--no-tracerouteSkip traceroute (faster)diagnose.py``--no-mtuSkip MTU detectionspeedtest.py``--quickOnly 100kb + 1mb testshistory.py``--record <file>Save result to historyhistory.py``--compare <file>Compare vs baselinehistory.py``--showPrint current baseline

Interpreting Results#

• DNS failures/slowness — websites appear down even when servers are up; most common cause of "internet is broken" when pings still work
• Packet loss at early hops (1–3) — local network issue (router, cable, Wi-Fi)
• Packet loss at hops 3–6 — ISP problem, outside your control
• High latency, no loss — congestion, either local or upstream
• MTU < 1472 — fragmentation; common with VPNs or PPPoE connections
• Speed drop but latency fine — possible ISP throttling

Read references/diagnostic-guide.md for full pattern descriptions and remediation steps.

Presenting Findings to the User#

• Lead with the headline finding, not raw numbers
• Reference baseline comparisons when available ("This is 3x slower than your normal")
• Give actionable next steps, not just observations
• If the issue is outside the user's control (ISP), say so clearly