// IFTOPRS — REAL-TIME PACKET INTERCEPT

Quickstart

Install from crates.io or build from source. Raw packet capture needs root or cap_net_raw:

# install from crates.io
cargo install iftoprs

# from source
git clone https://github.com/MenkeTechnologies/iftoprs
cd iftoprs && cargo build --release

# launch (needs root for raw capture)
sudo iftoprs                        # auto-detect default interface
sudo iftoprs -i en0                 # specific interface
sudo iftoprs -f "tcp port 443"      # BPF filter — HTTPS only
sudo iftoprs -F 10.0.0.0/8 -B       # filter private net, show bytes
sudo iftoprs -Z                     # show process names per flow

# headless / pipelines
sudo iftoprs --json                 # NDJSON stream to stdout
sudo iftoprs --json | jq '.flows[0]'

# shell completions
iftoprs --completions zsh > _iftoprs
iftoprs --completions bash > iftoprs.bash
iftoprs --completions fish > iftoprs.fish

Full install + dependency matrix lives in the README. On Linux apt install libpcap-dev before cargo build. On macOS libpcap ships with the system — no install needed.

Why iftoprs — against the classic tool

Capture engine

The capture pipeline is built around three concerns — read packets, parse to flow tuples, survive transient errors:

• libpcap — pcap::Capture opens the device with the configured BPF filter, snaplen, and promiscuous flag. The capture thread lives in src/capture/sniffer.rs.
• async hand-off — raw packets flow over a tokio::sync::mpsc channel to the parser task; the UI thread reads parsed flow updates from a second channel. Lossy capture (kernel drop) is logged but never panics.
• parser — src/capture/parser.rs walks Ethernet/IPv4/IPv6/TCP/UDP/ICMP headers, tracks 5-tuples, classifies protocol, and folds bytes into the per-flow counters.
• auto-restart — transient pcap errors trigger an exponential-backoff reopen instead of crash. v2.22.2 release notes (76f42105bd) wired this in.
• sliding windows — bandwidth is tracked over 2 s / 10 s / 40 s averages with a per-flow ring buffer in src/data/history.rs. Cumulative + peak counters live alongside.

Flow tracker

The flow model lives in src/data/flow.rs and the tracker in src/data/tracker.rs. Every flow is keyed by (src, dst, src_port, dst_port, protocol); counters split into tx and rx directions based on the configured interface IP / network filter.

• 5-tuple keys — protocols cover TCP / UDP / ICMP / Other (ARP, raw IP, etc.).
• three windows — 2 s yellow, 10 s green, 40 s cyan; sort cycles through them with 1/2/3.
• peak + cumulative — toggle the cumulative row with U.
• process attribution — an opt-out background poller in src/util/procinfo.rs shells out to lsof and maps socket → PID + process name. Joined into the flow on render.
• DNS resolution — async reverse-DNS cache in src/util/resolver.rs; failed lookups never block the UI.
• port names — /etc/services-style mapping from the same resolver.

CLI flags

Defined in src/config/cli.rs via clap derive macros. Generate shell completions with --completions SHELL.

// CAPTURE

// DISPLAY

// OUTPUT

// SYSTEM

// EXAMPLES

Keybind matrix

Defined in src/ui/app.rs. Every toggle that changes display state writes through to ~/.iftoprs.conf immediately — preferences survive across runs without explicit save.

// DISPLAY MODS

// SORT

// NAVIGATION

// FILTER

// CHOOSERS

// ACTIONS

// MOUSE

// GENERAL

Color themes — 31 built-in

Defined in src/config/theme.rs. Press c in the TUI for the live chooser with side-by-side swatch preview. Selection is persisted to ~/.iftoprs.conf. Outside the TUI: iftoprs --list-colors prints every theme with swatches.

Configuration — ~/.iftoprs.conf

TOML file at ~/.iftoprs.conf. Auto-created on first run; every TUI toggle writes through immediately. The repo ships iftoprs.default.conf as a documented reference.

# Color theme (see --list-colors for all 31 options)
theme = "NeonSprawl"

# Network interface to capture on (overridden by -i flag)
# interface = "en0"

# DNS and port resolution
dns_resolution = true
port_resolution = true

# Display toggles
show_ports = true
show_bars = true
show_border = true
show_header = true
show_processes = true
show_cumulative = false
use_bytes = false

# Bar style: Gradient, Solid, Thin, Ascii
bar_style = "Gradient"

# Refresh rate in seconds (1, 2, 5, or 10)
refresh_rate = 1

# Alert threshold in bytes/sec (0.0 = disabled)
# 125000.0    = 1 Mbit/s
# 1250000.0   = 10 Mbit/s
# 125000000.0 = 1 Gbit/s
alert_threshold = 0.0

# Pinned flows — persisted automatically when you press F
pinned = []

Serialization lives in src/config/prefs.rs. The TOML schema is stable; missing keys fall back to defaults so old configs keep working across upgrades.

JSON streaming — --json

Runs the capture engine headless and writes one JSON snapshot per refresh interval to stdout. Pipe to jq, log to a file, ship to a dashboard. Each line is a complete {"flows": [...]} object — no TUI is started, no terminal control bytes are emitted.

sudo iftoprs --json | jq -c '.flows[] | select(.rate_2s > 1000000)'
sudo iftoprs --json > /var/log/iftoprs.ndjson &
sudo iftoprs --json -f "tcp port 443" | head -n 1 | jq .

Each flow record carries the 5-tuple (source, destination, ports, protocol), rate_2s / rate_10s / rate_40s in bytes/sec, cumulative TX / RX totals, resolved hostnames, port names, and (if available) the attributed PID + process name.

Process attribution — Tab view

Shown by default; toggle off with -Z at launch or in the TUI. Background poller in src/util/procinfo.rs calls lsof -i -n -P -F pcn, parses the result, and builds a (local_addr, local_port) → (pid, name) map cached in Arc<Mutex<...>>. The flow renderer joins against the cache on every paint.

• Flows tab (default) — per-flow process column.
• Processes tab — press Tab — aggregates bandwidth per process across all of that process's flows.
• Drill-down — press Enter on a process row to filter the Flows tab to that process. Esc clears the filter.
• Cost — the poller runs at the refresh-rate interval, not per-packet; even on busy hosts the overhead stays measurable but small.

Tooltips — 14 hover & right-click segments

Every segment of the header bar carries a rich contextual tooltip. Hover triggers after 1 s with a 3 s auto-hide; right-click triggers instantly and persists until dismissed. Disable hover (right-click still works) with T.

Flow rows themselves carry a right-click tooltip: TX / RX rates across the three windows, cumulative totals, attributed process, and a 40 s sparkline of recent bandwidth (▁▂▃▅▇█).

Sparkline history

Per-flow rolling ring buffer of 40 samples in src/data/history.rs. Rendered two ways:

• Inline below the selected row when sparkline display is enabled (40 s window, ▁▂▃▅▇█ block characters).
• Inside the right-click tooltip for any flow — not only the selected one.

Samples are folded at the refresh-rate cadence, so the visible window is 40 × refresh_rate seconds. At default 1 s refresh that's a 40 s window; at 10 s refresh it stretches to 400 s.

Bandwidth alerts

Set alert_threshold in ~/.iftoprs.conf (bytes / sec, 0.0 disables). When any flow's instantaneous rate crosses the threshold:

• Border flashes red for a beat.
• Terminal bell (\x07) fires.
• Status bar shows ⚠ ALERT: hostname rate/s.

# in ~/.iftoprs.conf
alert_threshold = 1250000.0     # 10 Mbit/s
alert_threshold = 125000000.0   # 1 Gbit/s

Tests & CI

2,256 test functions across the production crate and integration suite. CI runs on every push and PR to main via GitHub Actions.

Integration tests in tests/integration.rs launch the built binary via the CARGO_BIN_EXE_iftoprs environment variable — not cargo run — so CLI output is read directly from the process and stays reliable in CI. The toolchain is pinned through rust-toolchain.toml with stable + rustfmt + clippy so local and CI runs share the same compiler.

Local checks — identical to CI:

cargo --locked fmt --all --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --locked

Crate layout

Single binary, eight modules, ~21k lines of production Rust:

Full per-file breakdown is in the engineering report.

Dependencies — 14 direct

Platform support

• macOS — libpcap ships with the system; sudo iftoprs works out of the box.
• Linux — install libpcap-dev (Debian / Ubuntu) or libpcap-devel (Fedora / RHEL). Run as root or grant cap_net_raw,cap_net_admin:

  sudo setcap cap_net_raw,cap_net_admin=eip $(which iftoprs)

• Rust toolchain — pinned to stable, Rust 1.85+ (edition 2024).
• Architectures — x86_64 + aarch64 verified on both macOS and Linux.

Repository & links

• Source — GitHub repo.
• Crate — crates.io (cargo install iftoprs).
• Rust API docs — docs.rs.
• Issues — issue tracker.
• CI status — GitHub Actions.
• Engineering report — report.html (LOC breakdown, subsystem map, dependency table, test surface).
• README — full README on GitHub.