netwatch ~ ~/labs/netwatch.md

stable·v0.25.0

netwatch.tui

netwatch

Network forensics that fits in your terminal.

NetWatch is a real-time network forensics TUI. Most terminal network tools answer one question — "which process is using bandwidth?" — and stop. Full packet analyzers answer "what happened?", but offline, after the fact, in a heavyweight GUI. NetWatch lives in the gap: live triage.

It decodes 17 L7 protocols, decrypts TLS 1.3 application data, fingerprints clients with JA4, and detects beaconing, port scans, and DNS tunneling — in real time, in one zero-config binary. Built for blue-teamers, incident responders, and homelabbers who need live triage and evidence capture, not just a bandwidth meter.

$brew install matthart1983/tap/netwatch

TUILinuxmacOSMIT★ 1.9k · matthart1983/netwatch ↗

~ $ netwatchtui

// netwatch · loops · no audio▶ playing

// 01 · install

Install

macOS / Linux · Homebrew

$brew install matthart1983/tap/netwatch

Cargo

$cargo install netwatch-tui

Requires Rust 1.70+ and libpcap (sudo apt install libpcap-dev on Linux; included on macOS).

From source

$git clone https://github.com/matthart1983/netwatch.git && cd netwatch && cargo build --release

// 02 · static linux builds

Static Linux builds

On Arch, Fedora, Alpine, or any distro that reports "libpcap.so.0.8: cannot open shared object file", grab the -static release tarball — it bundles libpcap and has no runtime dependencies.

// 03 · quick start

Quick start

NetWatch runs with zero config. Without root it shows interface stats, connections, and configuration; with root it adds health probes and packet capture.

1
Interface stats, connections, config — no root required
$netwatch
2
Full mode — adds ICMP health probes + packet capture
$sudo netwatch
3
Write a starter config to your platform config directory
$netwatch --generate-config

// 04 · see it decrypt tls in 60 seconds

See it decrypt TLS in 60 seconds

The fastest way to understand what NetWatch is — watch it read the plaintext of a TLS 1.3 session you control, the same SSLKEYLOGFILE way Wireshark does. No MITM, no proxy. The decrypted application data renders inline; a keylog miss never breaks capture, the record just stays opaque.

1
Launch, then press "c" in the Packets tab to start capturing
$sudo netwatch
2
Drive any cooperating client at the default keylog path
$SSLKEYLOGFILE=/tmp/sslkeylog.txt curl https://example.com
3
In the Packets tab, filter to the decrypted records and open one
$decrypted:true

// 05 · what makes it different

What makes it different

Most terminal network tools stop at "which process is using bandwidth." NetWatch keeps going.

🔓 TLS 1.3 decryptionPoint a cooperating client’s SSLKEYLOGFILE at NetWatch and read decrypted application data live in the Packets tab. AES-128/256-GCM and ChaCha20-Poly1305. Read-only, debugging-oriented — it decrypts traffic you control, never third-party or malware traffic.

🧬 JA4 / JA4Q fingerprintingFoxio-spec client fingerprints for TLS and QUIC. Pivot on a fingerprint with the ja4:<fingerprint> display filter to find every flow from the same client stack.

📡 17 L7 protocol decodersTLS, QUIC (SNI from reassembled CRYPTO frames), HTTP, DNS, SSH, MQTT, SNMP, BitTorrent, FTP, NetBIOS, SSDP, STUN, LLMNR, NTP, DHCP, mDNS — with TCP stream reassembly and handshake timing.

⚙️ Kernel-level process attributionAn eBPF kprobe tells you which process opened a connection — not lsof polling. Graceful fallback when eBPF isn’t available; PKTAP on macOS. The Connections header shows the active source.

🚨 Built-in network intelligencePort-scan, beaconing, and DNS-tunnel detection running in the background. A critical alert auto-freezes an armed Flight Recorder so evidence is captured before you even look.

🎥 Flight RecorderArm a rolling 5-minute capture, then freeze any incident into a portable evidence bundle (.pcap plus connection / health / DNS / alert context) for bug reports and post-mortems.

🛡️ Landlock sandbox (Linux)After setup, NetWatch drops its capabilities and locks itself into a kernel-enforced filesystem allow-list. A forensics tool that parses hostile traffic can never read your SSH keys, browser profiles, or /etc/shadow.

// 06 · the tabs

The tabs

Switch with 1–9. Tab 9 (Insights) appears when AI Insights is enabled.

1 · DashboardInterfaces, aggregate bandwidth graph, top connections, gateway/DNS health, latency heatmap. Useful in 5 seconds.

2 · ConnectionsEvery socket with process name + PID, protocol, state, GeoIP, and per-connection latency sparklines. Sort any column; jump to filtered packets.

3 · InterfacesPer-interface IPv4/IPv6, MAC, MTU, RX/TX sparklines, errors, drops.

4 · PacketsLive capture + deep decode, stream reassembly, display/BPF filters, bookmarks, PCAP export.

5 · StatsProtocol hierarchy with byte totals + distribution bars; TCP handshake histogram (min/avg/median/p95/max).

6 · TopologyASCII map of machine → gateway → DNS → top hosts, health-colored, with built-in traceroute.

7 · TimelineGantt-style connection timeline color-coded by TCP state; network-intel alerts land here. Windows 1m–1h.

8 · ProcessesPer-process bandwidth ranking with live RX/TX, totals, and connection counts.

9 · Insights (opt-in)Feeds a live network snapshot to a local or cloud LLM every 15s and renders bullet-point analysis. Off by default; enable in Settings. No API keys in NetWatch.

// 07 · display filters

Display filters

Wireshark-style filter syntax in the Packets tab (press /).

tcp                        # Protocol
192.168.1.42               # IP address (src or dst)
ip.src == 10.0.0.1         # Directional
port 443                   # Port
stream 7                   # Stream index
app:tls                    # L7 protocol
sni:example.com            # TLS/QUIC server name
host:api.github.com        # HTTP host / resolved name
ja4:t13d1516h2_...         # JA4 fingerprint
ech:true                   # Encrypted ClientHello present
decrypted:true             # Only TLS-decrypted records
tcp and port 443           # Combinators (and / or)
!dns                       # Negation
google                     # Bare word → contains "google"

// 08 · keyboard controls

Keyboard controls

Global keys. Each tab adds its own — see the full reference in the README.

Key	Action
1–9	Switch tabs
↑ ↓	Navigate
p	Pause / resume
r	Force refresh
c	Start/stop capture (Packets)
/	Display filter (Packets)
R / F / E	Arm recorder / freeze / export incident bundle
T	Traceroute
W	Whois lookup
w	Export to .pcap
t	Cycle theme
,	Settings
?	Help
q	Quit

// 09 · running without sudo (linux)

Running without sudo (Linux)

Packet capture and eBPF attribution need elevated capabilities, but not the whole TUI as root. Grant them once with: sudo setcap 'cap_net_raw,cap_bpf,cap_perfmon+eip' "$(which netwatch)". Re-run after every install — setcap attaches to a specific binary, and cargo install / release tarballs overwrite it.

// 10 · permissions

Permissions

Degrades gracefully — features that need root show a clear message, never crash.

Feature	netwatch	sudo netwatch
Interface stats & rates	✓	✓
Active connections	✓	✓
Network configuration	✓	✓
Health probes (ICMP)	—	✓
Packet capture	—	✓

// 11 · incident bundles

Incident bundles

When the Flight Recorder is armed, NetWatch keeps a bounded rolling window of evidence. On freeze or export it writes a self-contained directory — netwatch_incident_YYYYMMDD_HHMMSS/ — containing summary.md, manifest.json, connections.json, health.json, bandwidth.json, dns.json, alerts.json, and packets.pcap when capture data is available.

That keeps the packet evidence and the operational context that explains it together, which makes bug reports, incident reviews, and demos far easier.