rustnet-monitor

Crates.iorustnet-monitor
lib.rsrustnet-monitor
version0.18.0
created_at2025-09-12 07:42:08.762493+00
updated_at2026-01-07 19:09:53.144521+00
descriptionA cross-platform network monitoring terminal UI tool built with Rust
homepagehttps://github.com/domcyrus/rustnet
repositoryhttps://github.com/domcyrus/rustnet
max_upload_size
id1835287
size8,918,561
Marco Cadetg (domcyrus)

documentation

https://docs.rs/rustnet-monitor

README

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

RustNet

A cross-platform network monitoring tool built with Rust. RustNet provides real-time visibility into network connections with detailed state information, connection lifecycle management, deep packet inspection, and a terminal user interface.

RustNet Demo

Features

  • Real-time Network Monitoring: Monitor active TCP, UDP, ICMP, and ARP connections with detailed state information
  • Connection States: Track TCP states (ESTABLISHED, SYN_SENT, TIME_WAIT), QUIC states (QUIC_INITIAL, QUIC_HANDSHAKE, QUIC_CONNECTED), DNS states, SSH states, and activity-based UDP states
  • Interface Statistics: Real-time monitoring of network interface metrics including bytes/packets transferred, errors, drops, and collisions
  • Deep Packet Inspection (DPI): Detect application protocols including HTTP, HTTPS/TLS with SNI, DNS, SSH, QUIC, NTP, mDNS, LLMNR, DHCP, SNMP, SSDP, and NetBIOS
  • TCP Network Analytics: Real-time detection of TCP retransmissions, out-of-order packets, and fast retransmits with per-connection and aggregate statistics
  • Smart Connection Lifecycle: Protocol-aware timeouts with visual staleness indicators (white → yellow → red) before cleanup
  • Process Identification: Associate network connections with running processes
  • Service Name Resolution: Identify well-known services using port numbers
  • Reverse DNS Lookups: Resolve IP addresses to hostnames with background async resolution and caching
  • Cross-platform Support: Works on Linux, macOS, Windows, and FreeBSD
  • Advanced Filtering: Real-time vim/fzf-style filtering with keyword support (port:, src:, dst:, sni:, process:, state:)
  • Terminal User Interface: Beautiful TUI built with ratatui with adjustable column widths
  • Multi-threaded Processing: Concurrent packet processing for high performance
  • Optional Logging: Detailed logging with configurable log levels (disabled by default)
  • Security Sandboxing: Landlock-based filesystem/network restrictions on Linux 5.13+ (see SECURITY.md)
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:

cargo build --release --no-default-features

See 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 i): 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 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.

Quick Start

Installation

Homebrew (macOS / Linux):

brew tap domcyrus/rustnet
brew install rustnet

Ubuntu (25.10+):

sudo add-apt-repository ppa:domcyrus/rustnet
sudo apt update && sudo apt install rustnet

Fedora (42+):

sudo dnf copr enable domcyrus/rustnet
sudo dnf install rustnet

Arch Linux:

sudo pacman -S rustnet

From crates.io:

cargo install rustnet-monitor

Windows (Chocolatey):

# Run in Administrator PowerShell
choco install rustnet

Other platforms:

Running RustNet

Packet capture requires elevated privileges:

# 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:

rustnet -i eth0              # Specify network interface
rustnet --show-localhost     # Show localhost connections
rustnet --resolve-dns        # Enable reverse DNS lookups
rustnet -r 500               # Set refresh interval (ms)

See INSTALL.md for detailed permission setup and USAGE.md for complete options.

Keyboard Controls

Key Action
q Quit (press twice to confirm)
Ctrl+C Quit immediately
x Clear all connections (press twice to confirm)
Tab Switch between tabs
i Toggle interface statistics view
↑/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 (with --resolve-dns)
s S Cycle sort columns / toggle direction
a Toggle process grouping
Space Expand/collapse process group
←/→ Collapse/expand group
r Reset view (grouping, sort, filter)
/ Enter filter mode
h Toggle help

See 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 (Protocol, Address, State, Service, Bandwidth, Process)
  • Press S (Shift+s) to toggle sort direction
  • Find bandwidth hogs: Press s until "Down/Up ↓" appears (sorts by combined up+down speed)

See 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"
  • ssh: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 ssh: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 active: 10 minutes, idle: 5 minutes
  • 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 for complete timeout details.

Documentation

  • INSTALL.md - Detailed installation instructions for all platforms, permission setup, and troubleshooting
  • USAGE.md - Complete usage guide including command-line options, filtering, sorting, and logging
  • SECURITY.md - Security features including Landlock sandboxing and privilege management
  • ARCHITECTURE.md - Technical architecture, platform implementations, and performance details
  • PROFILING.md - Performance profiling guide with flamegraph setup and optimization tips
  • ROADMAP.md - Planned features and future improvements
  • RELEASE.md - Release process for maintainers

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines on how to contribute.

See 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 file for details.

Acknowledgments

  • Built with ratatui for the terminal UI
  • Packet capture powered by libpcap
  • Inspired by tools like tshark/wireshark/tcpdump, sniffnet, netstat, ss, and iftop
  • 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:

Commit count: 359

cargo fmt