WTFnet/README.md

# 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:9909
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:9909
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 leak status
wtfn dns leak watch --duration 10s --profile proxy-stub
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:9909
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
```

## Supported flags
Global flags:
- `--json` / `--pretty`
- `--no-color` / `--quiet`
- `-v` / `-vv` / `--verbose`
- `--log-level <error|warn|info|debug|trace>`
- `--log-format <text|json>`
- `--log-file <path>`
- `NETTOOL_LOG_FILTER` or `RUST_LOG` can override log filters (ex: `maxminddb::decoder=debug`)

Command flags (implemented):
- `sys ip`: `--all`, `--iface <name>`
- `sys route`: `--ipv4`, `--ipv6`, `--to <ip>`
- `ports listen`: `--tcp`, `--udp`, `--port <n>`
- `neigh list`: `--ipv4`, `--ipv6`, `--iface <name>`
- `ports conns`: `--top <n>`, `--by-process`
- `cert baseline`: `<path>`
- `cert diff`: `<path>`
- `probe ping`: `--count <n>`, `--timeout-ms <n>`, `--interval-ms <n>`, `--no-geoip`
- `probe tcping`: `--count <n>`, `--timeout-ms <n>`, `--socks5 <url>`, `--prefer-ipv4`, `--no-geoip`
- `probe trace`: `--max-hops <n>`, `--per-hop <n>`, `--timeout-ms <n>`, `--udp`, `--port <n>`, `--rdns`, `--no-geoip`
- `dns query`: `--server <ip[:port]>`, `--transport <udp|tcp|dot|doh>`, `--tls-name <name>`, `--socks5 <url>`, `--prefer-ipv4`, `--timeout-ms <n>`
- `dns detect`: `--servers <csv>`, `--transport <udp|tcp|dot|doh>`, `--tls-name <name>`, `--socks5 <url>`, `--prefer-ipv4`, `--repeat <n>`, `--timeout-ms <n>`
- `dns watch`: `--duration <Ns|Nms>`, `--iface <name>`, `--filter <pattern>`
- `dns leak status`: `--profile <full-tunnel|proxy-stub|split>`, `--policy <path>`
- `dns leak watch`: `--duration <Ns|Nms>`, `--iface <name>`, `--profile <full-tunnel|proxy-stub|split>`, `--policy <path>`, `--privacy <full|redacted|minimal>`, `--out <path>`, `--summary-only`
- `dns leak watch`: `--iface-diag` (prints capture-capable interfaces)
- `dns leak report`: `<path>`, `--privacy <full|redacted|minimal>`
- `http head|get`: `--timeout-ms <n>`, `--follow-redirects <n>`, `--show-headers`, `--show-body`, `--max-body-bytes <n>`, `--http1-only`, `--http2-only`, `--http3` (feature `http3`), `--http3-only` (feature `http3`), `--geoip`, `--socks5 <url>`
- `tls handshake|cert|verify|alpn`: `--sni <name>`, `--alpn <csv>`, `--timeout-ms <n>`, `--insecure`, `--socks5 <url>`, `--prefer-ipv4`, `--show-extensions`, `--ocsp`
- `discover mdns`: `--duration <Ns|Nms>`, `--service <type>`
- `discover ssdp`: `--duration <Ns|Nms>`
- `discover llmnr`: `--duration <Ns|Nms>`, `--name <host>`
- `discover nbns`: `--duration <Ns|Nms>`
- `diag`: `--out <path>`, `--bundle <path>`, `--dns-detect <domain>`, `--dns-timeout-ms <n>`, `--dns-repeat <n>`

## 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 and package
```bash
cmake -S . -B build
cmake --build build
cmake --build build --target package
```

Install:
```bash
cmake --build build --target install
```

## HTTP/3 (experimental)
HTTP/3 support is feature-gated and incomplete. Do not enable it in production builds yet.

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`).