NetWatch — Real-Time Network Monitoring

A lightweight, real-time network monitoring CLI tool written in Python.

View on GitHub Quick Install
Built by Yewo Mkandawire

Who Is This For?

NetWatch fits anywhere Python runs and people need to know when things break.

Small Business IT Admin

You manage 10–30 servers and network devices with no budget for enterprise NMS tools. NetWatch runs on any machine with Python and emails you the moment a device goes offline.

Home Lab Enthusiast

You run a self-hosted setup — Raspberry Pi, NAS, router, VMs — and want to know immediately when something drops without paying for a cloud monitoring service.

DevOps / Site Reliability Engineer

You need a dead-simple availability check to run alongside your existing stack — no agent installs, no dashboards to configure, just a CLI command or a cron job.

School or University Network Team

You oversee a campus network and need lightweight, auditable monitoring that students and junior staff can understand and extend without specialised training.

Developer Testing Locally

You are building a networked application and need to verify that remote endpoints, ports, and HTTP services are reachable during development and CI runs.

Features

ICMP ping

Raw socket with transparent fallback to the OS ping binary.

TCP port check

Open / closed / timeout per port.

HTTP/HTTPS probe

stdlib urllib only; configurable healthy status codes; SSL bypass option.

Continuous monitor

One thread per device, live status table, SIGINT/SIGTERM clean shutdown.

Email alerts

STARTTLS (587) or implicit TLS (465), exponential back-off retry, 300 s cooldown.

YAML config

${ENV_VAR} placeholder expansion, full validation with descriptive errors.

Zero heavy runtime deps

Only PyYAML, tabulate, jsonschema.

Requirements

Installation

  1. 1. Clone the repository
    2. git clone https://github.com/yewo-devnet/netwatch.git
cd netwatch
  2. 2. Install dependencies
    3. pip install -r requirements.txt
  3. 3. Install the package (Optional, to put `netwatch` on your PATH)
    4. pip install -e .

Configuration

Copy netwatch.yaml and edit it for your environment. Set the SMTP password in the environment — never in the file:

export NETWATCH_SMTP_PASSWORD=your_password

Here is a sample netwatch.yaml configuration file:

smtp:
  host: smtp.example.com
  port: 587                        # 587=STARTTLS, 465=implicit TLS
  username: alerts@example.com
  password: ${NETWATCH_SMTP_PASSWORD}
  recipients:
    - admin@example.com

monitoring:
  interval: 60          # seconds between polls
  alert_cooldown: 300   # seconds before re-alerting on same DOWN device
  log_file: netwatch.log
  log_level: INFO

devices:
  - label: Core Router
    host: 192.168.1.1
    checks: [ping]

  - label: Web Server
    host: 10.0.0.50
    checks: [ping, port, http]
    ports: [22, 80, 443]
    url: https://10.0.0.50/health
Key Type Default Description
smtp.host String - SMTP server hostname for email alerts
smtp.port Integer - SMTP server port (e.g., 587 for STARTTLS)
smtp.username String - Username to authenticate with SMTP server
smtp.password String - Password for SMTP. Should reference an environment variable like ${ENV_VAR}
smtp.recipients List of Strings - Email addresses to receive alert notifications
monitoring.interval Integer 60 Seconds between continuous monitoring polls
monitoring.alert_cooldown Integer 300 Seconds before re-alerting on the same DOWN device
monitoring.log_file String netwatch.log Path where the application logs will be saved
monitoring.log_level String INFO Logging verbosity level (e.g., INFO, DEBUG)
devices List of Objects - The list of devices and services you want to monitor
devices[].label String - Friendly name to identify the device in logs and alerts
devices[].host String - IP address or hostname of the device
devices[].checks List of Strings - Which checks to run: ping, port, http
devices[].ports List of Integers - (Optional) List of TCP ports to probe if port check is active
devices[].url String - (Optional) Target URL to request if http check is active

Usage

NetWatch provides several sub-commands for on-demand checking or continuous monitoring.

Ping

Ping a host to verify network reachability via ICMP.

python -m netwatch ping 8.8.8.8

Port

Check the status of specific TCP ports on a host.

python -m netwatch port 8.8.8.8 -p 53,80,443

HTTP

Probe an HTTP or HTTPS endpoint for health.

python -m netwatch http https://example.com

Monitor

Start continuous monitoring of all configured devices in the background.

NETWATCH_SMTP_PASSWORD=secret python -m netwatch monitor -c netwatch.yaml

Config Validate

Verify that your YAML configuration file is structurally correct.

NETWATCH_SMTP_PASSWORD=secret python -m netwatch config validate netwatch.yaml

Running Tests

If you're developing or contributing, you can run the test suite to ensure code health.

pytest --tb=short -q

The test suite fully covers ICMP ping fallbacks, TCP port checking, HTTP probes, the threading engine, email alerting, configuration validation, and logging.