Net Detective

Run comprehensive network tests including DNS, traceroute, MTU, and speed, then deliver clear, plain-English diagnoses with actionable insights and trend com...

Security Scan

The skill mostly does what it says (network diagnostics) but the manifest and SKILL.md claim 'no external binaries / stdlib only' while the scripts call system tools (curl, ping, traceroute, ip/route) and write history into a hard-coded path in the user's home — these inconsistencies suggest sloppy packaging and warrant caution before running.

Purpose & Capability

Name/description match the included scripts: DNS, traceroute, MTU, speed and reporting. However the SKILL.md and registry metadata claim 'All scripts use Python stdlib only' and 'Required binaries: none', yet the code invokes external system binaries (curl, ping, traceroute, route/ip). The skill also writes history under a hard-coded user path (~/.openclaw/workspace/skills/net-detective/data/history.json) which isn't declared in the metadata. These are incoherences between claimed requirements and actual behavior.

Instruction Scope

Runtime instructions direct the agent to run the included Python scripts and to record results to history. The scripts perform network probes to public endpoints (Google, Cloudflare, 8.8.8.8/1.1.1.1 and Cloudflare speed endpoints) and call local system commands. They also read/write a history file in the user's home directory. The SKILL.md does not call out that files will be written under ~/.openclaw, nor does it list required system tools — this scope creep should be noted.

Install Mechanism

There is no install spec (instruction-only at registry level), which is lower risk. The repository bundle does include runnable scripts (so code will be executed when invoked). No third-party downloads or remote installers are used by the skill itself; network activity is limited to diagnostics (DNS queries, HTTP downloads to Cloudflare speed endpoint).

Credentials

The skill requests no environment variables or credentials, which is appropriate. It does, however, write a history file under a hard-coded path in the user's home directory (~/.openclaw/workspace/skills/net-detective/data/history.json). That write access is reasonable for a diagnostics tool, but users should be aware the skill will create and modify files in their home directory and will perform network requests to public services (8.8.8.8, 1.1.1.1, Cloudflare endpoints).

Persistence & Privilege

always is false and the skill does not request permanent platform-wide privileges. It writes only its own history file and does not modify other skills or global agent configuration. Autonomous invocation is allowed (platform default) but does not combine with other high privileges here.

What to consider before installing

This skill appears to implement the advertised network tests, but the package is sloppy about what it declares: SKILL.md/registry say 'no external binaries / stdlib only' yet the scripts call system tools (ping, traceroute, curl, ip/route) and will write a history file at ~/.openclaw/workspace/skills/net-detective/data/history.json. Recommended precautions before running: 1) Inspect the included scripts (already bundled) and confirm you are comfortable with them performing network probes to public servers (8.8.8.8, 1.1.1.1, Cloudflare speed endpoints) and writing to your home directory. 2) Run in an isolated environment (VM or container) if you want to limit blast radius. 3) Ensure the called binaries (curl, ping, traceroute) are present and consider using flags like --no-speed to avoid downloads. 4) If you need higher assurance, ask the publisher for a declared list of required binaries and for SKILL.md to be corrected; absence of a homepage or source provenance lowers trust. 5) Note: there are minor code issues (truncated return in diagnose.py as packaged) which may cause runtime errors — this is sloppy but not necessarily malicious. If you are not comfortable, do not run it and request a cleaned/declared release.

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