DOCSEARCHbyAlgolia
Submit Docs

NetWatch Documentation

repository·main·Indexed 24 days ago

https://github.com/matthart1983/netwatch

A terminal-based network monitor for real-time forensics and security monitoring. NetWatch provides deep packet inspection, TLS 1.3 decryption, process-to-socket mapping, and automated threat detection. It features a ten-tab TUI for analyzing connections, interfaces, and packets, as well as a compact Lite view for low-resource environments. The tool includes an egress policy linter to detect network drift and supports deployment as a systemd service on Linux or a launchd service on macOS.

Tokens
30.1K
Snippets
50
Records
156
Agent score
82%

What's inside NetWatch

  1. Overview of NetWatch TUI tabs and capabilities

    main

    NetWatch provides a 9-tab TUI for real-time network diagnostics. The available tabs are:

    1. Dashboard: High-level overview.
    2. Connections: Active connections with process attribution (using Linux eBPF kprobe, macOS PKTAP, or lsof fallback).
    3. Interfaces: Interface traffic with rolling sparklines and totals.
    4. Packets: Packet capture with 15 L7 classifiers, display/BPF filters, and PCAP export.
    5. Stats: Network statistics.
    6. Topology: Network topology visualization.
    7. Timeline: Historical network events.
    8. Processes: Process-specific network activity.
    9. Insights: (Opt-in) AI-driven analysis via local or cloud Ollama.

    Key technical features include:

    • TLS 1.3 Decryption: Supported via SSLKEYLOGFILE.
    • Fingerprinting: JA4/JA4Q fingerprinting.
    • Threat Detection: Detects port scans, beaconing, and DNS tunneling.
    • Sandboxing: Uses Landlock (on Linux) for capability dropping and filesystem allow-listing post-initialization.

  2. Explore NetWatch ecosystem and related projects

    main

    NetWatch is part of a suite of monitoring and connectivity tools:

    • Siblings:
      • SysWatch: System monitoring.
      • DiskWatch: Disk monitoring.
    • ESSH: A pure-Rust SSH client with a similar TUI aesthetic, designed to connect to the same environments NetWatch observes.
    • NetWatch Cloud: A hosted fleet monitoring service. It uses a tiny Rust agent (netwatch-agent), an SDK (netwatch-sdk), and a dashboard (netwatch-dashboard) to provide real-time monitoring, latency alerts, and packet loss notifications via email or Slack. The agent, SDK, and dashboard are MIT licensed, while the hosted backend is proprietary.

  3. Run NetWatch with elevated privileges

    main

    NetWatch is designed to degrade gracefully if it lacks necessary permissions.

    • Regular user mode: Provides interface stats, connections, network configuration, and general UI state.
    • Elevated mode (sudo netwatch): Required to unlock packet capture and ICMP-backed health probes on systems that require root/administrative privileges.
    sudo netwatch

  4. Detect network threats with automatic alerts

    main

    NetWatch provides built-in network intelligence that monitors traffic for suspicious patterns and raises color-coded alerts in the Timeline tab without manual configuration.

    Detected threats include:

    • Port-scan detection: Multiple distinct destination ports from a single source within a short window (default: 20 ports / 30s).
    • Beaconing detection: Outbound connections at regular intervals with low jitter, characteristic of Command & Control (C2) traffic (default: ≥5 samples, jitter < 15%).
    • DNS-tunnel detection: High volumes of unique subdomains or abnormally long query names.
    • Bandwidth alerts: Configurable thresholds per interface.

    A critical alert will automatically freeze an active Flight Recorder, ensuring packet evidence is preserved immediately.

  5. How the egress policy linter works

    main

    The NetWatch egress policy linter follows an observe → promote → warn workflow. It is designed to be non-intrusive: it warns but never blocks network traffic.

    Core Workflow

    1. Observe: NetWatch monitors network flows and builds per-process profiles consisting of the process, destination SNI (Server Name Indication), ASN (Autonomous System Number), and ports.
    2. Promote: Users can promote these observed profiles to a formal policy file (<config>/netwatch/egress-policy.toml) using the Shift+P keybinding in the TUI. This creates a baseline of 'known good' behavior.
    3. Warn: Once a policy is active, NetWatch monitors for drift. If a process attempts a connection that deviates from its declared rules, a PolicyViolation alert is triggered.

    Matching Logic

    • SNI-first: The linter primarily matches based on the cleartext ClientHello SNI. This allows for effective matching without requiring TLS keylogs.
    • Address fallback: If SNI is unavailable, it matches on the destination address.
    • ASN matching: Rules can be written to match on an ASN. However, the linter does not automatically promote flows to an ASN; ASN rules must be manually authored by a human to prevent over-permissive policies (e.g., accidentally granting access to an entire hyperscaler).

    Policy Invariants

    • Deterministic & Low-noise: By default, only processes with a declared rule are checked. A violation will explicitly name the rule that was broken.
    • Strict Mode: By setting strict = true in the policy file, you can opt-in to reporting connections from undeclared processes (useful for detecting new, potentially malicious binaries).

  6. How QUIC 1-RTT decryption works

    main

    Unlike TCP-TLS decryption, which only requires the key to open an AEAD record, QUIC decryption requires maintaining protocol state due to several factors:

    1. Short-header parsing: NetWatch must parse short headers which lack the length prefixes found in Initial/Long headers.
    2. DCID-length tracking: Because short headers do not prefix the Destination CID length, NetWatch tracks the CID length from the handshake to correctly locate the packet number.
    3. Connection Mapping: NetWatch maps the connection's CID to the client_random (from the SSLKEYLOGFILE) to find the correct secrets.
    4. Cipher Suite Resolution: Since the ServerHello is encrypted, NetWatch performs trial-decryption across the three supported QUIC v1 suites (AES-128-GCM, AES-256-GCM, and ChaCha20-Poly1305) to identify the correct one.
    5. HTTP/3 Decompression: For HTTP/3 traffic, NetWatch walks QUIC frames to collect STREAM data and performs trial-decompression for gzip, zlib, and brotli formats.

  7. HTTP/3 body decompression support

    main

    NetWatch includes support for decompressing HTTP/3 bodies (RFC 9114) for single-packet, offset-0 data.

    Supported compression formats:

    • gzip / zlib (detected via magic bytes)
    • brotli (fallback)

    Limitations:

    • Currently, it only supports single-packet, offset-0 bodies. Mid-stream fragments that require cross-packet STREAM reassembly are not yet supported (planned for Phase 3b).

  8. Threat hunting with JA4 fingerprints

    main

    NetWatch implements the FoxIO JA4 specification to fingerprint every TLS ClientHello and QUIC Initial packet. Because JA4 fingerprints are stable across connections from the same client software, you can use them to identify specific stacks (e.g., a specific browser version, a CLI tool, or malware) across your network traffic.

    NetWatch includes the FoxIO BSD-3 lookup database and allows you to provide your own custom entries via JSON.

    ja4:t13d1516h2_8daaf6152771_b186095e22b6

  9. Understand NetWatch data processing and collection

    main

    NetWatch processes data through a layered pipeline, moving from raw bytes through network layers to L7 decoders. It performs per-flow stream tracking, handshake timing, TLS 1.3 decryption, JA4 fingerprinting, and threat detection.

    Collector Implementation by Platform

    CollectormacOSLinux
    Connectionslsof + PKTAP/proc/net/tcp + eBPF kprobe
    Packetslibpcap (BPF)libpcap
    Process attributionPKTAPlsof/ss polling, with optional eBPF kprobe overlay

    NetWatch is designed to degrade gracefully: features requiring elevated privileges will display a clear message and fall back to a lower-privilege mode rather than crashing.

  10. Protocol decoders in Deep Packet Inspection

    main

    NetWatch provides real Layer 7 (L7) decoding rather than relying on port-based labels. It uses per-flow stream tracking (byte accumulation and TCP sequence-anomaly detection) to classify traffic.

    Supported decoders include:

    • TLS: Version, SNI, ALPN, ECH flag, and JA4 fingerprint.
    • QUIC: Initial detection, SNI from reassembled CRYPTO frames, ECH, JA4Q, and HTTP/3.
    • HTTP: Method, host, path, and status code.
    • DNS / mDNS / LLMNR: Query name, record type, response code, and reverse-DNS cache (UDP only).
    • SSH: Client/server banner and version.
    • Others: MQTT, SNMP, BitTorrent, FTP, NetBIOS, SSDP, STUN, NTP, DHCP, and ICMP/ARP (at the parse layer).

  11. Use the Flight Recorder to export network incidents

    main

    The Flight Recorder allows you to capture and export network diagnostic data during an incident. Use the following keyboard shortcuts:

    • Shift+R: Arm or disarm the rolling recorder window.
    • Shift+F: Freeze the current incident window (critical network-intel alerts can also trigger this automatically).
    • Shift+E: Export the current incident bundle to your home directory.

    An exported bundle contains:

    • summary.md
    • manifest.json
    • connections.json
    • health.json
    • bandwidth.json
    • dns.json
    • alerts.json
    • packets.pcap (if packet capture was active during the recording)

  12. Use the Egress tab and promote policies in the TUI

    main

    The Egress tab provides a view of per-process network profiles and policy compliance.

    Key Features

    • Egress Tab: Displays a table of per-process profiles including: process name, destination SNI/ASN, ports, and timestamps (first/last seen).
    • Policy Status: A column indicates if a process is in-policy, drift (violating a rule), or unlisted.
    • Promotion: Use the Shift+P keybinding to promote the current observed baseline to your <config>/netwatch/egress-policy.toml file.
    • Filtering: You can filter the Egress tab using existing prefix syntax, such as process: or sni:.