Net Detective

Run detailed network diagnostics including DNS resolution, traceroute, MTU, and speed tests, then provide a clear plain-English report explaining any issues...

Security Scan

The code mostly matches the stated purpose (local network diagnostics) but there are several mismatches and surprising behaviors you should know about before installing.

Purpose & Capability

The name/description (network diagnostics) matches the included scripts: DNS checks, traceroute, MTU, and speed tests. However the package metadata claims "required binaries: none" and "required config paths: none" while the scripts call system binaries (ping, traceroute, ip/route, curl) and expect to read/write a history file under the user's home. That metadata mismatch is misleading and could cause surprise at runtime.

Instruction Scope

Runtime instructions only tell the agent to run the bundled scripts, which is consistent with the purpose. The scripts perform active network traffic to third-party servers (Google/Cloudflare DNS servers and Cloudflare's speed endpoint) and will write/append history to a file in the user's home directory (~/.openclaw/workspace/skills/net-detective/data/history.json). This behavior is expected for a network diagnostic tool but is worth calling out: data is sent externally and local state is persisted.

Install Mechanism

There is no install spec (instruction-only at install time). The repository includes runnable Python scripts (no third‑party packages). Lack of an install step is low risk, but because code files are included the runtime will execute local scripts that invoke system binaries — nothing is downloaded from remote URLs during install.

Credentials

The skill requests no credentials or environment variables, which is appropriate. Minor concerns: history.py hardcodes a HISTORY_FILE under the user's home (~/.openclaw/...), which the registry metadata did not declare as a required config path. The scripts also assume presence of system tools (ping, traceroute, curl, ip/route) but do not declare them in metadata.

Persistence & Privilege

The skill is not always-enabled and does not request elevated OS privileges, but it does persist diagnostic results to a file in the user's home directory. That creates a local footprint (diagnostics over time) but does not modify other skills or system-wide settings.

What to consider before installing

What to consider before installing: - Functionally the package appears to do what it claims: run ping/traceroute/MTU/DNS checks and optional speed downloads and produce a human-readable report. Expect the scripts to call system binaries: ping, traceroute, ip/route, and curl. If those are missing the scripts will report errors. - Network traffic: the tool sends DNS queries to 8.8.8.8 and 1.1.1.1 (and uses your system resolver) and downloads test payloads from Cloudflare's speed endpoint. That is expected for a speed/DNS tester, but be aware it contacts external servers. - Local persistence: results are recorded to a hardcoded history file (~/.openclaw/workspace/skills/net-detective/data/history.json). Review or back up that file if you care about privacy; the skill does not request credentials but it will store timestamps and network metrics locally. - Metadata mismatch: the registry metadata states "no required binaries / no config paths", which is misleading because the scripts assume system binaries and write to a history path. Treat that as sloppy packaging rather than an immediate red flag, but validate presence/permissions of the referenced binaries and the writable history path before running. - Code quality: there are signs of incomplete code/truncation in the provided diagnose.py (a truncated/incorrect return near run_speed) which may cause runtime errors. I recommend reviewing/ testing the scripts locally (or running them in an isolated/test environment) before relying on them for critical troubleshooting. - If you plan to share diagnostic output with others, inspect the saved JSON in the history path to ensure you are not exposing local hostnames/IPs you prefer to keep private. If you want, I can: (a) point out the exact lines where the metadata mismatches occur; (b) highlight the truncated/buggy portion in diagnose.py and suggest a fix; or (c) produce a safe, read-only dry-run checklist to run before executing these scripts on your machine.

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

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

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

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

Skip traceroute or MTU if time-constrained:

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

2. Compare against history (if available)

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:

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

With history comparison:

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

4. Record result to history

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

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

Flags Reference

Script	Flag	Effect
diagnose.py	--speed	Include bandwidth test
diagnose.py	--no-traceroute	Skip traceroute (faster)
diagnose.py	--no-mtu	Skip MTU detection
speedtest.py	--quick	Only 100kb + 1mb tests
history.py	--record <file>	Save result to history
history.py	--compare <file>	Compare vs baseline
history.py	--show	Print 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