175 lines
5.1 KiB
Markdown
175 lines
5.1 KiB
Markdown
# WTFnet
|
|
|
|
WTFnet is a pure CLI toolbox for diagnosing network problems on Linux and Windows.
|
|
|
|
## Highlights
|
|
- System snapshot: interfaces, IPs, routes, DNS config.
|
|
- Ports, neighbors, and trusted root certificates.
|
|
- Probing: ping, tcping, traceroute (best-effort).
|
|
- DNS: query/detect/watch with GeoIP, DoT/DoH, and SOCKS5 support.
|
|
- DNS leak detection with policy profiles and privacy modes (best-effort).
|
|
- GeoIP offline lookup via GeoLite2 Country/ASN.
|
|
- Subnet calculator: subnet/contains/overlap/summarize.
|
|
- Discover: mDNS/SSDP plus LLMNR/NBNS.
|
|
|
|
## Quickstart
|
|
```bash
|
|
cargo run -p wtfnet-cli -- sys ifaces
|
|
cargo run -p wtfnet-cli -- dns query example.com A
|
|
cargo run -p wtfnet-cli -- calc subnet 192.168.1.10 255.255.255.0
|
|
```
|
|
|
|
## Usage examples
|
|
```bash
|
|
# System snapshot
|
|
wtfn sys ifaces
|
|
wtfn sys ip --all
|
|
wtfn sys route --ipv4
|
|
wtfn sys dns
|
|
|
|
# Ports and neighbors
|
|
wtfn ports listen --tcp
|
|
wtfn ports who 443
|
|
wtfn neigh list --ipv6
|
|
|
|
# GeoIP and probing
|
|
wtfn geoip lookup 8.8.8.8
|
|
wtfn probe ping example.com --count 4
|
|
wtfn probe tcping example.com:443 --count 4
|
|
wtfn probe tcping example.com:443 --socks5 socks5://127.0.0.1:10808
|
|
wtfn probe trace example.com:443 --max-hops 20
|
|
|
|
# DNS
|
|
wtfn dns query example.com A
|
|
wtfn dns query example.com AAAA --server 1.1.1.1
|
|
wtfn dns query example.com A --transport doh --server 1.1.1.1 --tls-name cloudflare-dns.com
|
|
wtfn dns query example.com A --transport dot --server 1.1.1.1 --tls-name cloudflare-dns.com --socks5 socks5://127.0.0.1:10808
|
|
wtfn dns detect example.com --transport doh --servers 1.1.1.1 --tls-name cloudflare-dns.com
|
|
wtfn dns watch --duration 10s --filter example.com
|
|
wtfn dns watch --follow
|
|
wtfn dns leak status
|
|
wtfn dns leak watch --duration 10s --profile proxy-stub
|
|
wtfn dns leak watch --follow
|
|
wtfn dns leak report report.json
|
|
|
|
# TLS
|
|
wtfn tls handshake example.com:443
|
|
wtfn tls handshake example.com:443 --socks5 socks5://127.0.0.1:10808
|
|
wtfn tls cert example.com:443
|
|
wtfn tls verify example.com:443
|
|
wtfn tls alpn example.com:443 --alpn h2,http/1.1
|
|
|
|
# Discover
|
|
wtfn discover mdns --duration 3s
|
|
wtfn discover ssdp --duration 3s
|
|
wtfn discover llmnr --duration 3s
|
|
wtfn discover nbns --duration 3s
|
|
|
|
# Diag
|
|
wtfn diag --out report.json --json
|
|
wtfn diag --bundle report.zip
|
|
|
|
# Calc
|
|
wtfn calc contains 192.168.0.0/16 192.168.1.0/24
|
|
wtfn calc overlap 10.0.0.0/24 10.0.1.0/24
|
|
wtfn calc summarize 10.0.0.0/24 10.0.1.0/24
|
|
```
|
|
|
|
## Command reference
|
|
See `docs/COMMANDS.md` for the full list of commands and flags (with descriptions).
|
|
|
|
## GeoIP data files
|
|
GeoLite2 mmdb files should live in `data/`.
|
|
Lookup order:
|
|
1) `NETTOOL_GEOIP_COUNTRY_DB` / `NETTOOL_GEOIP_ASN_DB`
|
|
2) `data/` next to the CLI binary
|
|
3) `data/` in the current working directory
|
|
|
|
## Build
|
|
|
|
### Only build binary
|
|
```bash
|
|
cargo build --release
|
|
```
|
|
|
|
### Build and package
|
|
1. Prepare GeoLite2 databases (required `GeoLite2-ASN.mmdb` and `GeoLite2-Country.mmdb` ):
|
|
|
|
```bash
|
|
# Place your mmdb files under data/
|
|
mkdir data
|
|
```
|
|
|
|
> **Note**: This step requires `python3` and `just`.
|
|
|
|
2. Use `just` to run build and package command (Note: you don't need bash environment on windows):
|
|
|
|
```bash
|
|
# You will find package under dist/, zip file on windows, tar.gz file on linux
|
|
just release
|
|
```
|
|
|
|
## HTTP/3 (experimental)
|
|
HTTP/3 support is feature-gated and best-effort. Enable it only when you want to test QUIC
|
|
connectivity.
|
|
|
|
To enable locally for testing:
|
|
```bash
|
|
cargo run -p wtfnet-cli --features wtfnet-http/http3 -- http head https://cloudflare-quic.com --http3
|
|
```
|
|
|
|
## Roadmap
|
|
### v0.1 (MVP)
|
|
- sys: ifaces/ip/route/dns
|
|
- ports: listen/who
|
|
- probe: ping + tcping
|
|
- calc: subnet/contains/overlap
|
|
- basic logging + --json everywhere
|
|
|
|
### v0.2 (current requirements)
|
|
- dns: query + detect + watch (best-effort)
|
|
- geoip: local Country+ASN mmdb integration
|
|
- http: head/get (HTTP/2 required; HTTP/3 best-effort optional)
|
|
- tls: handshake/verify/cert/alpn
|
|
- neigh: ARP/NDP snapshot
|
|
- discover: mdns + ssdp (bounded)
|
|
- diag: bundle export (zip)
|
|
|
|
### v0.3 (future upgrades)
|
|
- richer trace output (reverse lookup, per-hop loss, per-hop stats)
|
|
- HTTP timing accuracy (connect/tls)
|
|
- TLS extras: OCSP stapling indicator, richer cert parsing
|
|
- ports conns improvements (top talkers / summary)
|
|
- better baseline/diff for system roots
|
|
- optional LLMNR/NBNS discovery
|
|
- optional HTTP/3 (feature-gated; experimental, incomplete)
|
|
|
|
### v0.4 (current requirements)
|
|
- dns leak detection (passive watch + report)
|
|
- process attribution (best-effort)
|
|
- policy profiles + privacy modes
|
|
|
|
## Current stage
|
|
Implemented:
|
|
- Core CLI with JSON output and logging.
|
|
- sys, ports, neigh, cert roots.
|
|
- geoip, probe, dns query/detect/watch.
|
|
- http head/get with timing and GeoIP.
|
|
- tls handshake/verify/cert/alpn.
|
|
- DoT/DoH + SOCKS5 proxy support.
|
|
- discover mdns/ssdp/llmnr/nbns.
|
|
- dns leak detection (status/watch/report).
|
|
- diag report + bundle.
|
|
- calc subcrate with subnet/contains/overlap/summarize.
|
|
- CMake/Makefile build + package + install targets.
|
|
- Basic unit tests for calc and TLS parsing.
|
|
|
|
In progress:
|
|
- dns leak: DoH heuristic classification (optional).
|
|
- dns leak: Leak-D mismatch correlation (optional).
|
|
|
|
See `docs/implementation_status.md` for a design-vs-implementation view.
|
|
|
|
## License
|
|
MIT (see `LICENSE`).
|