From 707aa22b07a29cadcb3fb17f69851b4f55a2d3b4 Mon Sep 17 00:00:00 2001
From: DaZuo0122 <1085701449@qq.com>
Date: Fri, 16 Jan 2026 13:38:41 +0800
Subject: [PATCH] Update README.md

---
 README.md | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..645e600
--- /dev/null
+++ b/README.md
@@ -0,0 +1,129 @@
+# 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 for DoH.
+- GeoIP offline lookup via GeoLite2 Country/ASN.
+- Subnet calculator: subnet/contains/overlap/summarize.
+
+## 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 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 detect example.com --transport doh --servers 1.1.1.1 --tls-name cloudflare-dns.com
+wtfn dns watch --duration 10s --filter example.com
+
+# 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`
+- `--log-level <error|warn|info|debug|trace>`
+- `--log-format <text|json>`
+- `--log-file <path>`
+
+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>`
+- `probe ping`: `--count <n>`, `--timeout-ms <n>`, `--interval-ms <n>`, `--no-geoip`
+- `probe tcping`: `--count <n>`, `--timeout-ms <n>`, `--no-geoip`
+- `probe trace`: `--max-hops <n>`, `--timeout-ms <n>`, `--udp`, `--port <n>`, `--no-geoip`
+- `dns query`: `--server <ip[:port]>`, `--transport <udp|tcp|dot|doh>`, `--tls-name <name>`, `--socks5 <url>`, `--timeout-ms <n>`
+- `dns detect`: `--servers <csv>`, `--transport <udp|tcp|dot|doh>`, `--tls-name <name>`, `--socks5 <url>`, `--repeat <n>`, `--timeout-ms <n>`
+- `dns watch`: `--duration <Ns|Nms>`, `--iface <name>`, `--filter <pattern>`
+
+## 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
+```
+
+## 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)
+- TLS extras: OCSP stapling indicator, more chain parsing
+- ports conns improvements (top talkers / summary)
+- better baseline/diff for system roots
+- smarter "diagnose <domain>" workflow mode
+
+## Current stage
+Implemented:
+- Core CLI with JSON output and logging.
+- sys, ports, neigh, cert roots.
+- geoip, probe, dns query/detect/watch.
+- DoT/DoH + SOCKS5 proxy for DoH.
+- calc subcrate with subnet/contains/overlap/summarize.
+- CMake/Makefile build + package + install targets.
+
+In progress:
+- http, tls, discover, diag.
+
+## License
+MIT (see `LICENSE`).