docs.rs failed to build netoproc-0.1.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

netoproc

Per-process network traffic monitor for macOS

Overview

netoproc is a terminal-based network monitoring tool for macOS that shows per-process, per-socket, per-connection network traffic in real time. It captures packet headers via BPF (Berkeley Packet Filter) and correlates them with process and socket information from macOS system APIs.

Unlike nettop (Apple's built-in), netoproc provides per-connection traffic rates, a dedicated DNS observatory, a pipe-friendly snapshot mode for scripting, and htop-style keyboard navigation.

Prerequisites

macOS 26.0 (Tahoe) or higher
Rust stable toolchain (edition 2024)
Root privileges (sudo) for BPF device access

Install Rust via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Installation

Build from source

git clone https://github.com/XuanLee-HEALER/netoproc.git
cd netoproc
cargo build --release
sudo ./target/release/netoproc

From crates.io (once published)

cargo install netoproc

Usage

netoproc requires root privileges. Always run with sudo:

# Interactive TUI (default)
sudo netoproc

# Snapshot mode (TSV output)
sudo netoproc snapshot

# Snapshot in JSON
sudo netoproc snapshot --format json

# Monitor a specific interface
sudo netoproc monitor --interface en0

# Filter by process name
sudo netoproc monitor --filter firefox

# Fast refresh (500ms)
sudo netoproc monitor --interval 0.5

See docs/USAGE.md for the complete user guide with all options, views, keyboard shortcuts, output formats, and examples.

Features

Four TUI views: Process, Connection, Interface, DNS
Per-connection metrics: RX/TX rates, RTT, jitter, retransmissions
DNS observatory: Live query log, resolver latency stats
Snapshot mode: TSV and JSON output for scripting and piping
Sparkline charts: Visual traffic trends in the terminal
Keyboard navigation: htop-style filtering, sorting, row expansion

Architecture

Three-thread model:

BPF capture thread: Reads raw packets from /dev/bpfN via Berkeley Packet Filter
Stats poller thread: Correlates packets with processes/sockets, publishes state via ArcSwap
TUI/snapshot thread: Renders the interactive display or serializes output

See docs/DESIGN.md for the full architecture documentation.

Development Setup

git clone https://github.com/XuanLee-HEALER/netoproc.git
cd netoproc

# Check compilation
just check

# Build (debug mode)
just build

# Run unit tests (no sudo needed)
just test

# Run all tests including integration (requires sudo)
just test-all

Running Tests

# Unit tests only
just test

# All tests (requires sudo)
just test-all

# Specific test
cargo test test_name

# Lint check
just clippy

# Full lint pass (check + clippy + fmt)
just lint

Linting & Formatting

# Format code
just fmt

# Format check (CI)
just fmt-check

# Lint with Clippy
just clippy

# Combined lint (check + clippy + fmt-check)
just lint

netoproc 0.1.0