NETWATCH is a terminal-based security monitoring tool that gives you continuous, live visibility into every active network connection on your machine, with automatic risk scoring, GeoIP intelligence, VPN status, process path validation, and new-connection alerting.

NetWatch

Real-time network security observability for macOS endpoints.

NetWatch is a terminal-based security monitoring tool that gives you continuous, live visibility into every active network connection on your machine with automatic risk scoring, GeoIP intelligence, VPN status, process path validation, and new-connection alerting. Built for security-conscious individuals, developers, and teams who need to know exactly what their machine is talking to and why.

---

Overview

Modern endpoints make hundreds of concurrent network connections. Most security tools surface this data only after an incident. NetWatch surfaces it in real time — with enough context to act on it immediately.

Every second, NETWATCH:

• Enumerates all active TCP/UDP connections via the OS kernel
• Resolves the owning process and validates its executable path
• Scores each connection's risk level using a multi-factor algorithm
• Looks up the geographic origin of every external IP in the background
• Detects new connections the moment they appear
• Monitors VPN tunnel status and alerts when traffic is exposed

---

Installation

Requirements: Python 3.10+, macOS (Linux compatible with minor limitations)

BASH
pip install netwatch-scan  

Or install from source:

BASH
git clone https://github.com/kyegomez/netwatch  
cd netwatch  
pip install -e .  

Usage

BASH
# Standard mode  
netwatch

# Full process visibility (recommended)  
sudo netwatch

# With DNS hostname resolution for remote IPs  
sudo netwatch --resolve  

Press Ctrl+C to stop.

---

Features

System Dashboard

Live header panel showing the full network context of your machine, updated every second:

Connection Table

Live-updated table with one row per active connection:

Automatic Risk Scoring

Each connection is scored across multiple dimensions:

Port base score

Modifier conditions

Rating thresholds: ≥ 4 → HIGH, ≥ 2 → MED, < 2 → LOW

New Connection Detection

Every connection is tracked by a (local_addr, remote_addr, pid) key with a first-seen timestamp. Connections that appeared within the last 6 seconds are flagged with ★ and a highlighted row background. The highlight expires automatically.

GeoIP Intelligence

Remote IP geographic lookups run in background threads via ip-api.com and are cached per session. Private/RFC 1918 addresses resolve immediately as local. Results appear in the COUNTRY column as they arrive.

Process Path Validation

The full executable path of each process is inspected. Binaries making network connections from the following locations are flagged as suspicious and receive a +2 risk penalty:

• /tmp/, /private/tmp/, /var/tmp/
• /var/folders/
• Downloads/, Desktop/

Standard system paths (/usr/, /System/, /Applications/, /Library/Application Support/) are not flagged.

VPN Status

Network interfaces are scanned each tick for active tunnel adapters. When no VPN is detected, the system panel border turns red and a warning is displayed inline. Detects WireGuard (wg), OpenVPN (tun), macOS VPN (utun), IPSec (ipsec), PPP, and TAP adapters.

Statistics Panel

A live sidebar showing:

• Risk summary (HIGH / MED / LOW counts)
• Connection breakdown by TCP state
• Top 6 processes by connection count

---

Requirements

• Python 3.10+
• macOS (Linux compatible with minor limitations — WiFi SSID and gateway detection use macOS-specific tooling)
• Root access recommended for full process visibility

Dependencies:

psutil>=5.9  
rich>=13.0  

---

Display Reference

Risk Indicators

Flag Column

VPN Border Color

Connection Status Colors

---

Architecture

NETWATCH is a single-file Python script with no external services, no telemetry, and no persistent storage. All data is gathered locally from the OS kernel via psutil. The only outbound requests are:

1. Public IP lookup — one HTTPS request to api.ipify.org on startup, refreshed every 60 seconds
2. GeoIP lookups — one HTTP request to ip-api.com per unique external IP, cached for the session lifetime

All lookups run in daemon threads and never block the render loop. If either service is unavailable (e.g. on a restricted network), the tool degrades gracefully — displaying unavailable or … in the affected fields while all local monitoring continues uninterrupted.

---

Threat Coverage

---

Limitations

• Per-connection bandwidth measurement is not currently implemented — total interface throughput is shown in the header
• GeoIP accuracy depends on ip-api.com data quality; CDN and VPN exit IPs may show unexpected countries
• WiFi SSID and gateway detection use macOS-specific commands (airport, route) and will not work on Linux without modification
• Full process visibility (executable paths, process names for all PIDs) requires root on macOS
• ip-api.com has a rate limit of 45 requests/minute on the free tier; sessions with many unique external IPs may see delayed GeoIP resolution

---

Roadmap

• IP reputation lookup against AbuseIPDB / threat intel feeds
• Per-process bandwidth metering (KB/s per connection)
• Anomaly baseline — alert on first-ever outbound connection per process
• Port scan / sweep detection (multiple ports from same remote IP)
• DNS leak detection (DNS traffic bypassing VPN resolver)
• Connection history log (JSONL append with timestamp, risk, process)
• --alert mode — system notification on HIGH-risk connection
• Linux support (SSID via iwgetid, gateway via ip route)

---

License

APACHE 2.0

Source: https://github.com/kyegomez/netwatch