From 57b9c37ba1802dced8581392dcd74a2b4fd1e07c Mon Sep 17 00:00:00 2001 From: wehub-resource-sync Date: Mon, 13 Jul 2026 10:19:02 +0000 Subject: [PATCH] docs: preserve upstream English README --- README.en.md | 340 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 340 insertions(+) create mode 100644 README.en.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..ddeb371 --- /dev/null +++ b/README.en.md @@ -0,0 +1,340 @@ +

+

RustNet

+

+ Per-process network monitoring for your terminal: live TCP, UDP, and QUIC connections with deep packet inspection, sandboxed by default. +

+

+ Built With Ratatui + Build Status + Crates.io + GitHub Stars + License + GitHub release + Docker Image +

+

+ +

+ English | 简体中文 +

+ +

+ RustNet demo +

+ +

+ Real-time visibility into every connection your machine makes, who owns it, and what protocol it's speaking. No tcpdump, X11 forwarding, or root piping. +

+ +## Features + +- **Per-process attribution**: Every TCP, UDP, and QUIC connection mapped to its owning process, via eBPF on Linux, PKTAP on macOS, native APIs on Windows and FreeBSD. Wireshark and tcpdump can't do this; `netstat` / `ss` can't show live state. +- **Deep packet inspection**: Identify HTTP, HTTPS/TLS with SNI, DNS, SSH, FTP, QUIC, MQTT, BitTorrent, STUN, NTP, mDNS, LLMNR, DHCP, SNMP, SSDP, and NetBIOS, without external dissectors. +- **Annotated PCAPNG export**: `--pcapng-export` writes a Wireshark-ready capture with process, PID, direction, DPI/SNI, and GeoIP embedded as per-packet comments. Open it in Wireshark and every packet already names its owning process, with no post-processing. Classic `--pcap-export` with a JSONL sidecar for offline correlation is also available. +- **Security sandboxing**: Landlock (Linux 5.13+), Seatbelt (macOS), token privilege drop + job-object child-process block (Windows). Drops privileges immediately after libpcap initializes. See [SECURITY.md](SECURITY.md). +- **TCP network analytics**: Real-time retransmissions, out-of-order packets, and fast-retransmit detection, per-connection and aggregate. +- **Smart connection lifecycle**: Protocol-aware timeouts with white → yellow → red staleness indicators. Toggle `t` to keep historic (closed) connections visible for forensics. +- **Vim/fzf-style filtering**: `port:`, `src:`, `dst:`, `sni:`, `process:`, `state:`, `proto:`, plus regex via `/(?i)pattern/`. +- **GeoIP enrichment**: Country lookups via local MaxMind GeoLite2. No network calls. +- **Kubernetes attribution** (optional `kubernetes` feature): connections mapped to their pod, namespace, and container, shown in the details pane, JSON/PCAPNG exports, and the `pod:`, `ns:`, `container:` filters. Enabled in the official Docker image; on a cluster, use the [kubectl-rustnet](https://github.com/domcyrus/kubectl-rustnet) plugin to run it as an ephemeral debug pod. See [USAGE.md](USAGE.md#--kubernetes-mode-optional-feature). +- **Cross-platform**: Linux, macOS, Windows, FreeBSD. + +## Why RustNet? + +RustNet fills the gap between simple connection tools (`netstat`, `ss`) and packet analyzers (`Wireshark`, `tcpdump`): + +- **Process attribution**: See which application owns each connection. Wireshark cannot provide this because it only sees packets, not sockets. +- **Connection-centric view**: Track states, bandwidth, and protocols per connection in real-time +- **SSH-friendly**: TUI works over SSH so you can quickly see what's happening on a remote server without forwarding X11 or capturing traffic + +RustNet complements packet capture tools. Use RustNet to see *what's making connections*. For direct Wireshark inspection, `--pcapng-export` writes live best-effort packet comments with PID/process context. For cleanup-time correlation, use `--pcap-export` plus the JSONL sidecar and optional `scripts/pcap_enrich.py`. See [PCAP Export](USAGE.md#pcap-export) and [Comparison with Similar Tools](ARCHITECTURE.md#comparison-with-similar-tools) for details. + +Built on ratatui, libpcap, eBPF (libbpf-rs), DashMap, crossbeam, ring, MaxMind GeoLite2, and Landlock. See [ARCHITECTURE.md](ARCHITECTURE.md#dependencies) for the full dependency breakdown. + +
+eBPF Enhanced Process Identification (Linux Default) + +RustNet uses kernel eBPF programs by default on Linux for enhanced performance and lower overhead process identification. However, this comes with important limitations: + +**Process Name Limitations:** +- eBPF uses the kernel's `comm` field, which is limited to 16 characters +- Shows the task/thread command name, not the full executable path +- Multi-threaded applications often show thread names instead of the main process name + +**Real-world Examples:** +- **Firefox**: May appear as "Socket Thread", "Web Content", "Isolated Web Co", or "MainThread" +- **Chrome**: May appear as "ThreadPoolForeg", "Chrome_IOThread", "BrokerProcess", or "SandboxHelper" +- **Electron apps**: Often show as "electron", "node", or internal thread names +- **System processes**: Show truncated names like "systemd-resolve" → "systemd-resolve" + +**Fallback Behavior:** +- When eBPF fails to load or lacks sufficient permissions, RustNet automatically falls back to standard procfs-based process identification +- Standard mode provides full process names but with higher CPU overhead +- eBPF is enabled by default; no special build flags needed + +To disable eBPF and use procfs-only mode, build with: +```bash +cargo build --release --no-default-features +``` + +See [ARCHITECTURE.md](ARCHITECTURE.md) for technical information. + +
+ +
+Interface Statistics Monitoring + +RustNet provides real-time network interface statistics across all supported platforms: + +- **Overview Tab**: Shows active interfaces with current rates, errors, and drops +- **Interfaces Tab** (press `3`): Detailed table with comprehensive metrics for all interfaces +- **Cross-Platform**: Linux (sysfs), macOS/FreeBSD (getifaddrs), Windows (GetIfTable2 API) +- **Smart Filtering**: Windows automatically excludes virtual/filter adapters + +See [USAGE.md](USAGE.md#interface-statistics) for detailed documentation on interpreting interface statistics and platform-specific behavior. + +**Metrics Available:** +- Total bytes and packets (RX/TX) +- Error counters (receive and transmit) +- Packet drops (queue overflows) +- Collisions (legacy, rarely used on modern networks) + +Stats are collected every 2 seconds in a background thread with minimal performance impact. + +
+ +## Screenshots + + + + + + + + + + +
Overview
Connections table with live stats and sparklines
Details
Per-connection SNI, cipher, GeoIP, DPI
Graph
Traffic chart, app distribution, top processes
Interfaces
Per-interface RX/TX history with errors and drops
+ +## Quick Start + +### Installation + +**Homebrew (macOS / Linux):** +```bash +brew install rustnet +``` + +**Ubuntu (25.10+):** +```bash +sudo add-apt-repository ppa:domcyrus/rustnet +sudo apt update && sudo apt install rustnet +``` + +**Fedora (42+):** +```bash +sudo dnf copr enable domcyrus/rustnet +sudo dnf install rustnet +``` + +**openSUSE Tumbleweed:** +```bash +sudo zypper addrepo https://download.opensuse.org/repositories/home:/domcyrus:/rustnet/openSUSE_Tumbleweed/home:domcyrus:rustnet.repo +sudo zypper refresh +sudo zypper install rustnet +``` + +**Arch Linux:** +```bash +sudo pacman -S rustnet +``` + +**Nix / NixOS:** +```bash +nix-shell -p rustnet +# Then inside the shell: sudo rustnet +``` + +**From crates.io:** +```bash +cargo install rustnet-monitor +``` + +**Windows (Chocolatey):** +```powershell +# Run in Administrator PowerShell +# Requires Npcap (https://npcap.com) installed with "WinPcap API-compatible Mode" enabled +choco install rustnet +``` + +**Other platforms:** +- **FreeBSD**: Download from [rustnet-bsd releases](https://github.com/domcyrus/rustnet-bsd/releases) +- **Docker, source builds, other Linux distros**: See [INSTALL.md](INSTALL.md) for detailed instructions + +### Running RustNet + +Packet capture requires elevated privileges: + +```bash +# Quick start (all platforms) +sudo rustnet + +# Linux: Grant capabilities to run without sudo (recommended) +sudo setcap 'cap_net_raw,cap_bpf,cap_perfmon+eip' $(which rustnet) +rustnet +``` + +**Common options:** +```bash +rustnet -i eth0 # Specify network interface +rustnet --show-localhost # Show localhost connections +rustnet --no-resolve-dns # Disable reverse DNS lookups (enabled by default) +rustnet -r 500 # Set refresh interval (ms) +rustnet --theme classic # Original full-color palette (default: muted) +rustnet --pcapng-export capture.pcapng # Annotated PCAPNG for Wireshark +``` + +See [INSTALL.md](INSTALL.md) for detailed permission setup and [USAGE.md](USAGE.md) for complete options. + +> If you set capabilities but the TUI still shows `eBPF unavailable`, see +> [eBPF Unavailable Despite Capabilities Being Set](INSTALL.md#ebpf-unavailable-despite-capabilities-being-set) +> in the troubleshooting section. + +## Keyboard Controls + +| Key | Action | +|-----|--------| +| `q` | Quit (press twice to confirm) | +| `Ctrl+C` | Quit immediately | +| `x` | Clear all connections (press twice to confirm) | +| `Tab` or `]` | Next tab | +| `Shift+Tab` or `[` | Previous tab | +| `1`–`5` | Jump to Overview / Details / Interfaces / Graph / Help | +| `↑/k` `↓/j` | Navigate up/down | +| `g` `G` | Jump to first/last connection | +| `Enter` | View connection details | +| `Esc` | Go back or clear filter | +| `c` | Copy remote address | +| `p` | Toggle service names/ports | +| `d` | Toggle hostnames/IPs | +| `s` `S` | Cycle sort columns / toggle direction | +| `a` | Toggle process grouping | +| `Space` | Expand/collapse process group | +| `←/→` or `h/l` | Collapse/expand group | +| `PageUp/PageDown` or `Ctrl+B/F` | Page navigation | +| `t` | Toggle historic (closed) connections | +| `i` | Toggle the System info sidebar | +| `r` | Reset view (grouping, sort, filter) | +| `/` | Enter filter mode | +| `h` | Toggle help | + +See [USAGE.md](USAGE.md) for detailed keyboard controls and navigation tips. + +## Filtering & Sorting + +**Quick filtering examples:** +``` +/google # Search for "google" anywhere +/port:443 # Filter by port +/process:firefox # Filter by process +/state:established # Filter by connection state +/dport:443 sni:github.com # Combine filters +``` + +**Sorting:** +- Press `s` to cycle through sortable columns (Process, Addresses, Service, Application, State, Bandwidth) +- Press `S` (Shift+s) to toggle sort direction +- Find bandwidth hogs: Press `s` until "Bandwidth Total ↓" appears (sorts by combined up+down speed) + +See [USAGE.md](USAGE.md) for complete filtering syntax and sorting guide. + +
+Advanced Filtering Examples + +**Keyword filters:** +- `port:44` - Ports containing "44" (443, 8080, 4433) +- `sport:80` - Source ports containing "80" +- `dport:443` - Destination ports containing "443" +- `src:192.168` - Source IPs containing "192.168" +- `dst:github.com` - Destinations containing "github.com" +- `process:ssh` - Process names containing "ssh" +- `sni:api` - SNI hostnames containing "api" +- `app:openssh` - SSH connections using OpenSSH +- `state:established` - Filter by protocol state +- `proto:tcp` - Filter by protocol type + +**State filtering:** +- `state:syn_recv` - Half-open connections (SYN flood detection) +- `state:established` - Established connections only +- `state:quic_connected` - Active QUIC connections +- `state:dns_query` - DNS query connections + +**Combined examples:** +- `sport:80 process:nginx` - Nginx connections from port 80 +- `dport:443 sni:google.com` - HTTPS to Google +- `process:firefox state:quic_connected` - Firefox QUIC connections +- `dport:22 app:openssh state:established` - Established OpenSSH connections + +
+ +
+Connection Lifecycle & Visual Indicators + +RustNet uses smart timeouts and visual warnings before removing connections: + +**Visual staleness indicators:** +- **White**: Active (< 75% of timeout) +- **Yellow**: Stale (75-90% of timeout) +- **Red**: Critical (> 90% of timeout) + +**Protocol-aware timeouts:** +- **HTTP/HTTPS**: 10 minutes (supports keep-alive) +- **SSH**: 30 minutes (long sessions) +- **TCP active**: 10 minutes, idle: 5 minutes +- **QUIC connected**: 3 minutes (or peer's transport-param idle timeout, when present); `Initial`/`Handshaking`: 60 seconds +- **DNS**: 30 seconds +- **TCP CLOSED**: 5 seconds + +Example: An HTTP connection turns yellow at 7.5 min, red at 9 min, and is removed at 10 min. + +See [USAGE.md](USAGE.md) for complete timeout details. + +
+ +## Documentation + +- **[INSTALL.md](INSTALL.md)** - Detailed installation instructions for all platforms, permission setup, and troubleshooting +- **[USAGE.md](USAGE.md)** - Complete usage guide including command-line options, filtering, sorting, and logging +- **[SECURITY.md](SECURITY.md)** - Security features including Landlock sandboxing and privilege management +- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Technical architecture, platform implementations, and performance details +- **[PROFILING.md](PROFILING.md)** - Performance profiling guide with flamegraph setup and optimization tips +- **[ROADMAP.md](ROADMAP.md)** - Planned features and future improvements +- **[RELEASE.md](RELEASE.md)** - Release process for maintainers + +## Contributing + +Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute. + +See [CONTRIBUTORS.md](CONTRIBUTORS.md) for a list of people who have contributed to this project. + +## License + +This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE) file for details. + +## Acknowledgments + +- Built with [ratatui](https://github.com/ratatui-org/ratatui) for the terminal UI +- Packet capture powered by [libpcap](https://www.tcpdump.org/) +- Inspired by tools like `tshark/wireshark/tcpdump`, `sniffnet`, `netstat`, `ss`, `iftop`, and [bandwhich](https://github.com/imsnif/bandwhich) +- Some code is vibe coded (OMG) / may the LLM gods be with you + +--- + +## Documentation Moved + +Some sections have been moved to dedicated files for better organization: + +- **Permissions Setup**: Now in [INSTALL.md - Permissions Setup](INSTALL.md#permissions-setup) +- **Installation Instructions**: Now in [INSTALL.md](INSTALL.md) +- **Detailed Usage**: Now in [USAGE.md](USAGE.md) +- **Architecture Details**: Now in [ARCHITECTURE.md](ARCHITECTURE.md)