268 lines
8.0 KiB
Markdown
268 lines
8.0 KiB
Markdown
Below are **repo-ready v0.3.0 docs**.
|
||
They’re written to match your **current implemented feature set** (v0.2 mostly done: sys/ports/neigh/certs/geoip/probe/dns/http/tls/discover/diag/calc).
|
||
They also respect your decision to **NOT include** in v0.3.0:
|
||
|
||
* shell completions / man pages
|
||
* the “smart one-shot doctor” command
|
||
* extra output ergonomics for automation
|
||
|
||
And they target the **real gaps / next upgrades** you still have: **HTTP/3**, deeper **HTTP timing**, **TLS extras**, richer **trace**, **ports conns**, better **cert baseline/diff**, and optionally **LLMNR/NBNS discovery** (currently missing).
|
||
|
||
---
|
||
|
||
## 1) `docs/RELEASE_v0.3.0.md`
|
||
|
||
```markdown
|
||
# WTFnet v0.3.0 — Release Plan
|
||
|
||
Binary name in examples: `wtfn` (current CLI examples use this form).
|
||
Project scope: Linux (Debian/Ubuntu) + Windows first-class.
|
||
|
||
## 0. Summary
|
||
|
||
v0.3.0 focuses on improving **diagnostic depth and fidelity** of existing commands rather than adding a "smart doctor" workflow.
|
||
|
||
Major upgrades in this release:
|
||
- richer traceroute output and per-hop statistics
|
||
- HTTP timing breakdown accuracy (connect/tls stages)
|
||
- optional HTTP/3 support (best-effort)
|
||
- TLS diagnostics upgrades (OCSP stapling indicator, richer certificate parsing)
|
||
- ports connections view and summaries
|
||
- improved cert baseline/diff for system roots
|
||
- optional discovery expansion (LLMNR/NBNS)
|
||
|
||
---
|
||
|
||
## 1. Goals
|
||
|
||
### G1. Make existing outputs more trustworthy
|
||
- Replace placeholder timing fields with real measured values where feasible.
|
||
- Improve trace reliability and readability.
|
||
|
||
### G2. Expand diagnostics depth, not workflow complexity
|
||
- Keep subcommands explicit (no `doctor`, no guided flow).
|
||
- Focus on "give me evidence" tools.
|
||
|
||
### G3. Keep v0.2 compatibility
|
||
- Add flags and fields in an additive way.
|
||
- Keep default behavior safe and bounded.
|
||
|
||
---
|
||
|
||
## 2. Non-goals (explicitly out of scope)
|
||
|
||
- No `wtfn doctor ...` / one-shot diagnosis command (move to v0.4+).
|
||
- No shell completion scripts or man page generation.
|
||
- No new output modes like JSONL streaming / schema negotiation changes (stay stable).
|
||
- No OS-native TLS verifier in v0.3.0 (optional future enhancement).
|
||
|
||
---
|
||
|
||
## 3. Feature scope
|
||
|
||
### 3.1 probe trace: richer output (MUST)
|
||
Current: trace exists best-effort.
|
||
Target improvements:
|
||
- `--rdns`: reverse DNS lookup per hop (best-effort; cached; time-bounded)
|
||
- `--per-hop <n>`: send N probes per hop (default 3) to compute:
|
||
- avg/min/max RTT per hop
|
||
- loss % per hop
|
||
- `--icmp` and `--udp` modes remain best-effort; document privilege requirements
|
||
- Keep `--geoip` integration: hop IP → Country/ASN
|
||
|
||
Acceptance:
|
||
- output includes per-hop loss and stable hop formatting
|
||
- JSON output contains hop arrays with RTT series
|
||
|
||
---
|
||
|
||
### 3.2 HTTP timing breakdown accuracy (MUST)
|
||
Current: `dns_ms` + `ttfb_ms` exist, but connect/tls are placeholders.
|
||
Target:
|
||
- implement `connect_ms` and `tls_ms` (best-effort) for HTTP/1.1 and HTTP/2
|
||
- keep total duration correct and stable
|
||
- when measurement unavailable (library limitation), report:
|
||
- `null` + add warning, never fake numbers
|
||
|
||
Acceptance:
|
||
- `wtfn http head|get` JSON contains:
|
||
- `dns_ms`, `connect_ms`, `tls_ms`, `ttfb_ms`, `total_ms`
|
||
- on timeout / failure, partial timing must still be meaningful.
|
||
|
||
---
|
||
|
||
### 3.3 HTTP/3 (optional feature flag) (SHOULD)
|
||
Current: HTTP/3 not implemented.
|
||
Target:
|
||
- add `--http3` support behind Cargo feature `http3`
|
||
- behavior:
|
||
- `--http3-only`: fail if HTTP/3 cannot be used
|
||
- `--http3`: try HTTP/3, fallback to HTTP/2 unless `--http3-only`
|
||
- provide clear error classes:
|
||
- UDP blocked, QUIC handshake timeout, TLS/ALPN mismatch, etc.
|
||
|
||
Acceptance:
|
||
- builds without `http3` feature still work
|
||
- with feature enabled, HTTP/3 works on at least one known compatible endpoint
|
||
|
||
---
|
||
|
||
### 3.4 TLS extras: OCSP + richer cert parsing (MUST)
|
||
Current: `tls handshake/verify/cert/alpn` exists.
|
||
Target:
|
||
- show OCSP stapling presence (if exposed by library)
|
||
- richer certificate parsing for leaf and intermediates:
|
||
- SANs (DNS/IP)
|
||
- key usage / extended key usage (best-effort)
|
||
- signature algorithm (best-effort)
|
||
- new flags:
|
||
- `--show-extensions` (prints richer X.509 info)
|
||
- `--ocsp` (show stapling info if present)
|
||
|
||
Acceptance:
|
||
- TLS output includes richer leaf cert details when requested
|
||
- `--show-chain` remains fast and bounded
|
||
|
||
---
|
||
|
||
### 3.5 ports conns: active connection view + summaries (SHOULD)
|
||
Current: `ports listen/who`.
|
||
Target:
|
||
- add `wtfn ports conns`
|
||
- show active TCP connections with:
|
||
- local addr:port
|
||
- remote addr:port
|
||
- state (ESTABLISHED/TIME_WAIT/etc)
|
||
- PID/process name (best-effort)
|
||
- add summary mode:
|
||
- `--top <n>` show top remote IPs by count
|
||
- `--by-process` group by process
|
||
|
||
Acceptance:
|
||
- works on Linux + Windows best-effort
|
||
- never requires admin by default; if needed, return partial with warnings
|
||
|
||
---
|
||
|
||
### 3.6 cert roots: stronger baseline/diff (MUST)
|
||
Current: cert roots listing exists; baseline/diff exists.
|
||
Target improvements:
|
||
- normalize matching key: SHA256 fingerprint
|
||
- diff categories:
|
||
- added / removed
|
||
- changed validity (newly expired)
|
||
- subject/issuer changes
|
||
- add stable JSON schema for baseline files (include schema version)
|
||
|
||
Acceptance:
|
||
- baseline diff is stable across platforms (best-effort fields allowed)
|
||
- diff output is human-friendly and JSON-friendly
|
||
|
||
---
|
||
|
||
### 3.7 discover: LLMNR/NBNS (optional) (NICE)
|
||
Current: mDNS + SSDP exist; LLMNR/NBNS missing.
|
||
Target:
|
||
- add `wtfn discover llmnr --duration 3s`
|
||
- add `wtfn discover nbns --duration 3s`
|
||
- bounded, low-noise, rate-limited
|
||
|
||
Acceptance:
|
||
- best-effort implementation on Windows-first networks
|
||
- if unsupported on OS, show "not supported" error with exit code 5 (partial)
|
||
|
||
---
|
||
|
||
## 4. Compatibility & behavior rules
|
||
|
||
- Command names must remain stable.
|
||
- Existing flags must retain meaning.
|
||
- JSON output fields are additive only.
|
||
- Logging remains stderr-only; JSON output remains clean stdout.
|
||
|
||
---
|
||
|
||
## 5. Deliverables checklist
|
||
|
||
MUST:
|
||
- trace richer output + per-hop loss stats
|
||
- HTTP connect/tls timing best-effort with warnings when unknown
|
||
- TLS extras: OCSP indicator + richer x509 parsing
|
||
- ports conns basic implementation
|
||
- cert baseline/diff improvements
|
||
|
||
SHOULD:
|
||
- HTTP/3 behind feature flag
|
||
|
||
NICE:
|
||
- LLMNR/NBNS discovery
|
||
|
||
---
|
||
|
||
## 6. Definition of Done (v0.3.0)
|
||
|
||
- v0.3.0 builds on Linux (Debian/Ubuntu) + Windows.
|
||
- `wtfn probe trace` provides per-hop loss and optional rdns.
|
||
- `wtfn http head|get` reports accurate timing breakdown where possible.
|
||
- `wtfn tls ...` provides OCSP + SAN/extensions when requested.
|
||
- `wtfn ports conns` works best-effort and produces useful output.
|
||
- cert baseline/diff is stable and readable.
|
||
- No doctor command, no completions, no new output modes.
|
||
|
||
```
|
||
|
||
---
|
||
|
||
## 3) `docs/WORK_ITEMS_v0.3.0.md` (engineering task list)
|
||
|
||
```markdown
|
||
# WTFnet v0.3.0 — Work Items
|
||
|
||
This is a practical checklist to execute v0.3.0.
|
||
|
||
## 1) probe/trace upgrades
|
||
- [ ] add `--per-hop <n>` and store RTT samples per hop
|
||
- [ ] compute loss% per hop
|
||
- [ ] add `--rdns` best-effort reverse lookup (cached + time-bounded)
|
||
- [ ] improve hop formatting + JSON schema
|
||
|
||
## 2) http timing improvements
|
||
- [ ] implement `connect_ms` and `tls_ms` timing
|
||
- [ ] report `null` + warning when measurement unavailable
|
||
- [ ] keep current `dns_ms` and `ttfb_ms`
|
||
|
||
## 3) optional HTTP/3
|
||
- [ ] add `http3` cargo feature + deps
|
||
- [ ] implement `--http3` / `--http3-only`
|
||
- [ ] define error classification for QUIC failures
|
||
|
||
## 4) tls extras
|
||
- [ ] add OCSP stapling presence indicator (if available)
|
||
- [ ] parse SANs and key usage / EKU best-effort
|
||
- [ ] add `--show-extensions` and `--ocsp` flags
|
||
|
||
## 5) ports conns
|
||
- [ ] implement `wtfn ports conns`
|
||
- [ ] add `--top <n>` and `--by-process`
|
||
- [ ] best-effort PID mapping with warnings
|
||
|
||
## 6) cert baseline/diff improvements
|
||
- [ ] baseline schema version
|
||
- [ ] match by SHA256 fingerprint
|
||
- [ ] diff categories: add/remove/expired/changed
|
||
|
||
## 7) optional LLMNR/NBNS
|
||
- [ ] implement `discover llmnr`
|
||
- [ ] implement `discover nbns`
|
||
- [ ] bounded collection, low-noise
|
||
|
||
## 8) docs updates
|
||
- [ ] update README roadmap
|
||
- [ ] update COMMANDS.md with new flags/commands
|
||
- [ ] add RELEASE_v0.3.0.md
|
||
|
||
```
|
||
|
||
---
|
||
|