boy-hack · boy-hack · Mar 27, 2026 · Mar 26, 2026
diff --git a/README_EN.md b/README_EN.md
diff --git a/docs/OUTPUT_FORMATS.md b/docs/OUTPUT_FORMATS.md
@@ -101,6 +101,8 @@ One JSON object per line, perfect for streaming.
 
 ### Usage
 ```bash
+./ksubdomain enum -d example.com --format jsonl -o results.jsonl
+# or using legacy alias
 ./ksubdomain enum -d example.com --oy jsonl -o results.jsonl
 ```
 

diff --git a/docs/api.md b/docs/api.md
@@ -13,7 +13,8 @@ type Config struct {
     Bandwidth      string             // bandwidth cap, e.g. "5m" (default "5m")
     Retry          int                // per-domain retry count, -1 = infinite (default 3)
     Resolvers      []string           // DNS resolver IPs; nil = built-in defaults
-    Device         string             // network interface; "" = auto-detect
+    Device         string             // single network interface; "" = auto-detect (backward-compat)
+    Devices        []string           // multi-NIC: takes precedence over Device when non-empty
     Dictionary     string             // wordlist file for Enum; "" = built-in list
     Predict        bool               // enable AI subdomain prediction
     WildcardFilter string             // "none" | "basic" | "advanced" (default "none")

diff --git a/docs/best-practices.md b/docs/best-practices.md
@@ -131,7 +131,35 @@ For scans with millions of domains (e.g., combined wordlists):
 
 ---
 
-## SDK usage tips
+## Multi-NIC for higher throughput
+
+Repeat `--interface` to send from multiple adapters simultaneously.
+Each interface spawns an independent goroutine; they share the same domain
+channel, naturally load-balancing queries:
+
+```bash
+sudo ksubdomain enum -d example.com --interface eth0 --interface eth1 -b 20m
+```
+
+Equivalently in the SDK:
+
+```go
+scanner := sdk.NewScanner(&sdk.Config{
+    Bandwidth: "20m",
+    Devices:   []string{"eth0", "eth1"},
+})
+```
+
+---
+
+## Dynamic timeout
+
+The engine automatically adjusts the per-query timeout using an RTT
+sliding window (EWMA α=0.125, β=0.25, RFC 6298), bounded between 1 s
+and 10 s.  You rarely need to override `--timeout`; only do so if your
+network has unusually high or low latency.
+
+---
 
 ### Cancellation
 

diff --git a/docs/faq.md b/docs/faq.md
@@ -172,9 +172,30 @@ brew install libpcap
 Use the `build.sh` script which sets the correct `CGO_ENABLED` and
 `CC` for each target platform.
 
+### How do I use multiple network interfaces?
+
+Repeat `--interface` (or `--eth`) to send from multiple NICs simultaneously:
+
+```bash
+sudo ksubdomain enum -d example.com --interface eth0 --interface eth1 -b 20m
+```
+
 ---
 
-## Exit codes
+## Flags renamed in v2.4+
+
+Several flag names changed for clarity. Old aliases still work for backward-compat.
+
+| Old flag | New recommended flag |
+|----------|---------------------|
+| `--band` / `-b` | `--bandwidth` |
+| `--eth` | `--interface` |
+| `--wild-filter-mode` | `--wildcard-filter` |
+| `--not-print` / `--np` | `--quiet` / `-q` |
+| `--output-type` | `--format` |
+| `-s` | `--silent` (also `-s`) |
+
+---
 
 | Code | Meaning |
 |---|---|

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -4,16 +4,19 @@
 
 | Requirement | Notes |
 |---|---|
-| OS | Linux, macOS, Windows (WSL2 recommended) |
+| OS | Linux, macOS, Windows |
 | Privileges | **root** or `CAP_NET_RAW` — raw packet capture requires elevated access |
 | libpcap / npcap | Linux: `libpcap-dev`; macOS: built-in; Windows: [Npcap](https://npcap.com) |
+| Go (build only) | 1.23+ |
 
 ---
 
 ## Installation
 
 ### Download pre-built binary (recommended)
 
+Visit [Releases](https://github.com/boy-hack/ksubdomain/releases) and download the binary for your platform.
+
 ```bash
 # Linux x86_64
 curl -L https://github.com/boy-hack/ksubdomain/releases/latest/download/ksubdomain_linux_amd64 \
@@ -26,19 +29,31 @@ chmod +x /usr/local/bin/ksubdomain
 ```bash
 git clone https://github.com/boy-hack/ksubdomain.git
 cd ksubdomain
-go build -o ksubdomain ./cmd/ksubdomain
-# or use the build script (cross-compile all platforms):
-./build.sh
+# Inject version via ldflags (recommended)
+go build -ldflags "-X github.com/boy-hack/ksubdomain/v2/pkg/core/conf.Version=v2.x.y" \
+    -o ksubdomain ./cmd/ksubdomain
 ```
 
 ---
 
 ## Your first scan
 
-### 1 — Enumerate subdomains (built-in wordlist)
+### 1 — Check available network interfaces
+
+```bash
+sudo ./ksubdomain device
+```
+
+### 2 — Test maximum packet rate
+
+```bash
+sudo ./ksubdomain test
+```
+
+### 3 — Enumerate subdomains (built-in wordlist)
 
 ```bash
-sudo ksubdomain enum -d example.com
+sudo ./ksubdomain enum -d example.com
 ```
 
 Sample output:
@@ -49,93 +64,87 @@ mail.example.com => 93.184.216.50
 api.example.com => 93.184.216.51
 ```
 
-### 2 — Enumerate with a custom wordlist
+### 4 — Verify a domain list
 
 ```bash
-sudo ksubdomain enum -d example.com -f /path/to/wordlist.txt
+sudo ./ksubdomain verify -f domains.txt -o output.txt
 ```
 
-### 3 — Verify a list of known subdomains
+---
+
+## Common workflows
+
+### Pipe to httpx for HTTP probing
 
 ```bash
-cat domains.txt | sudo ksubdomain verify
-# or
-sudo ksubdomain verify -f domains.txt
+sudo ./ksubdomain enum -d example.com --only-domain --silent | httpx -silent
 ```
 
-### 4 — Pipe into httpx
+### Save as JSONL for streaming processing
 
 ```bash
-sudo ksubdomain enum -d example.com --silent --only-domain | httpx -silent
+sudo ./ksubdomain enum -d example.com --format jsonl -o result.jsonl
 ```
 
-`--only-domain` prints one clean domain per line with no extra characters,
-making the output safe to pipe into any line-oriented tool.
+### Batch enumeration of multiple root domains
 
----
+```bash
+sudo ./ksubdomain enum --domain-list roots.txt -b 10m --format jsonl -o all.jsonl
+```
 
-## Common flags
-
-| Flag | Short | Description |
-|---|---|---|
-| `--domain` | `-d` | Target domain (enum mode) |
-| `--file` | `-f` | Input file (wordlist for enum, domain list for verify) |
-| `--band` | `-b` | Bandwidth limit, e.g. `5m`, `100m` (default: `5m`) |
-| `--retry` | `-r` | Max retries per domain (default: `3`) |
-| `--resolvers` | | Custom DNS resolver IPs, comma-separated |
-| `--output` | `-o` | Output file path |
-| `--output-type` | `--ot` | Output format: `txt`, `json`, `csv`, `jsonl` |
-| `--only-domain` | `--od` | Print only the domain name, no record values |
-| `--silent` | | Suppress progress bar and informational logs |
-| `--wild-filter-mode` | | Wildcard filter: `none` (default), `basic`, `advanced` |
-| `--predict` | | Enable AI subdomain prediction |
+### Predict + advanced wildcard filter
 
----
+```bash
+sudo ./ksubdomain enum -d example.com --predict --wildcard-filter advanced -o result.txt
+```
 
-## Output formats
+### Multi-NIC parallel sending
 
 ```bash
-# Plain text (default)
-sudo ksubdomain enum -d example.com -o results.txt
+sudo ./ksubdomain enum -d example.com --interface eth0 --interface eth1 -b 20m
+```
+
+---
 
-# JSON Lines (jq-compatible, one object per line)
-sudo ksubdomain enum -d example.com -o results.jsonl --ot jsonl
+## Platform notes
 
-# Parse with jq
-jq '.domain' results.jsonl
-jq 'select(.type=="A") | .records[]' results.jsonl
-```
+### Linux
 
-See [docs/OUTPUT_FORMATS.md](./OUTPUT_FORMATS.md) for full format details.
+```bash
+# Grant CAP_NET_RAW instead of running as root (optional)
+sudo setcap cap_net_raw+ep ./ksubdomain
 
----
+./ksubdomain enum -d example.com
+```
 
-## Bandwidth tuning
+### macOS
 
-ksubdomain operates at the raw packet level and sends DNS queries at the
-rate you specify. Start conservatively and increase:
+macOS uses BPF with smaller default buffers. Keep bandwidth conservative:
 
 ```bash
-# ~60 Mbit bandwidth cap (safe for most home connections)
-sudo ksubdomain enum -d example.com -b 60m
+sudo ./ksubdomain enum -d example.com -b 5m
+```
 
-# Max out a Gigabit interface
-sudo ksubdomain enum -d example.com -b 1000m
+### WSL / WSL2
+
+```bash
+./ksubdomain enum -d example.com --interface eth0
 ```
 
-See [docs/best-practices.md](./best-practices.md) for bandwidth and resolver advice.
+### Windows
+
+1. Install [Npcap](https://npcap.com/) (WinPcap is not supported)
+2. Run as Administrator
+
+```bat
+.\ksubdomain.exe enum -d example.com
+```
 
 ---
 
-## Troubleshooting quick reference
+## Next steps
 
-| Symptom | Fix |
-|---|---|
-| `permission denied` | Run with `sudo` or grant `CAP_NET_RAW` |
-| `network device not found` | Specify interface with `--eth <name>`; list with `ip link show` |
-| `network device not active` | Bring interface up: `sudo ip link set <name> up` |
-| No results, no errors | Try `--wild-filter-mode none`; target domain may have wildcard DNS |
-| macOS `ENOBUFS` | Lower bandwidth: `-b 5m` |
-| WSL2 wrong interface | Add `--eth eth0` |
-
-For more, see [docs/faq.md](./faq.md).
+- [API Reference](./api.md)
+- [Best Practices](./best-practices.md)
+- [FAQ](./faq.md)
+- [SDK README](../sdk/README.md)