4497e2a871
readme's sample console output showed a multi-line summary table (connection/egress/vpn/latency) the tool has never printed; the real stdout is three lines (banner, verdict, file paths). also documented: the tcptrace/ndt7 extras install command, bare-asn --target syntax, ndt7's interactive consent prompt, tcp-trace's cascade fallback, and that --watch writes one artifact per session rather than per tick. architecture's storage section had the peeringdb cache path wrong (.cache/peeringdb/*.json vs the real .cache/pdb-net-*.json) and never mentioned the watch_*.json artifact from task 39. the file-size exceptions note only covered exporter.py; interpret.py, cli.py, models.py, bgp.py, ip_geo.py, netinfo.py, speed.py, reputation.py and probes/traceroute.py all cleared ~200 lines too and are now listed with the reason each stayed one file. test count updated from ~120 (written before a single module existed) to the real ~385.
5.4 KiB
netcheck
Cross-platform CLI for deep network diagnostics: who your ISP actually is, whether a VPN is really carrying your traffic, where the path degrades, and what your line actually delivers.
$ netcheck --quick
netcheck 0.1.0 · auto mode · Windows
Verdict: ok (100/100) — No problems found on this connection.
Report written to logs/report_AS64500_20260808T191200Z.md
logs/report_AS64500_20260808T191200Z.json
Everything else — egress ASN, VPN verdict, latency, path, speed — lives in the two files it just wrote, not on the console; the terminal only tells you the headline and where to look.
Install
Requirements:
- Python 3.10 or newer
- Windows, Linux or macOS
- Internet access (netcheck is a network tool; it degrades gracefully but cannot do much offline)
- Optional: the native Ookla
speedtestbinary onPATHfor the best bandwidth tier - Optional:
mtronPATHfor the best path data
git clone https://github.com/<owner>/netcheck
cd netcheck
uv sync
uv run netcheck
Want --tcp-trace and --ndt7 too? They're optional extras, not installed by default:
uv sync --extra tcptrace --extra ndt7
Without uv:
python -m pip install -r requirements.txt
python -m pip install -e .
netcheck
No configuration is required. Copy .env.example to .env only if you have optional API keys.
What it does
- Identity — egress IPv4 and IPv6, reverse DNS, ASN, organisation, geo, and whether the address looks residential, mobile, hosting or business. Cross-checked across six independent providers so one rate limit does not blank the answer.
- VPN / proxy assessment — a weighted verdict (
none/likely/confirmed) built from tunnel interfaces, MTU anomalies, gateway-vs-egress mismatch, Cloudflare WARP flags, provider proxy/hosting flags, PeeringDB network type, timezone-vs-geo mismatch, and DNS resolver ASN mismatch. - DNS leak test — enumerates resolvers per network adapter, so it catches the classic case where the tunnel adapter is clean but the Wi-Fi adapter still holds the ISP resolver. Also detects EDNS Client Subnet leakage.
- BGP intelligence — upstreams, peers, downstreams, announced prefixes, route stability, IXP presence, and CAIDA ASRank customer-cone size.
- Reputation — locally cached FireHOL blocklists (no query leaves your machine), Shodan InternetDB exposure, and optional classic DNSBL zones.
- Latency & path — per-host ping statistics with real jitter/loss/mdev, and a traceroute that never needs administrator rights.
- Bandwidth — a cascading speedtest (Ookla binary → Cloudflare → fast.com → optional M-Lab NDT7) with separate download and upload bufferbloat grades.
Handy things
| Flag | What it does |
|---|---|
--quick |
~10 s express run: reference-host pings only, no speedtest |
--full |
~60–120 s: full speedtest and full MTR cycles |
--target AS64500 / --target 64500 / --target 1.2.3.4 / --target example.com |
Investigate a specific network instead of your own connection — the AS prefix on a bare ASN is optional |
--target-host <ip|domain> |
Add an extra host to the ping and traceroute fan-out |
--speedtest-server <id|url> |
Pin the speedtest to a specific server |
--watch |
Continuous monitoring with a live dashboard — for catching intermittent drops. Writes one logs/watch_*.json time series per session, not one report per tick |
--compare a.json b.json |
Diff two earlier reports: before/after a VPN switch, before/after an ISP call. Read-only — no probing, no network calls |
--dnsbl |
Opt in to classic DNSBL reputation zones |
--ndt7 |
Opt in to M-Lab NDT7 (publishes your measurement, including your IP, as CC0 open data). On an interactive terminal it prints the consent notice and asks first; on a non-interactive one it proceeds without asking |
--tcp-trace |
Opt in to a scapy TCP-SYN traceroute through ICMP-filtering middleboxes (needs the tcptrace extra plus Npcap on Windows or root on Unix). Falls through to the normal cascade when it cannot run |
Every run writes two files into ./logs/: a Markdown report to read and a JSON dump containing every raw provider response, untruncated. ./logs/ is gitignored — reports contain your external IP, city, coordinates and ISP name.
netcheck never requires administrator or root. Where privileges would give better data, it degrades to an unprivileged method and says so in the report.
For developers
Stack: Python 3.10+, Typer, Rich, httpx, pydantic-settings, dnspython, psutil, icmplib, ctypes.
uv sync --all-extras --group dev
uv run pytest -q
uv run netcheck --quick
uv export --no-hashes --format requirements-txt -o requirements.txt # after dependency changes
Architecture, data flow and the reasoning behind each provider choice: ARCHITECTURE.md.
Credits
netcheck reads from RIPEstat, CAIDA ASRank, Team Cymru, PeeringDB, Cloudflare, ip-api.com, freeipapi.com, ipinfo.io, ipwho.is, Shodan InternetDB, the FireHOL blocklist project, Netflix fast.com and M-Lab. All of them are used within their free/keyless tiers.
License
Not yet finalized — see LICENSE. The choice is between MIT and Polyform Noncommercial; the default reputation sources (Shodan InternetDB, Spamhaus free mirrors) are non-commercial-use-only, which is the crux of the decision.