NetWatch

Lightweight network monitoring and diagnostics CLI for engineers, sysadmins and DevOps.

Real ICMP, TCP and DNS checks. Local SQLite history. Outage detection. Reports.
No cloud. No external database. No fake metrics.

What is NetWatch?

NetWatch is a local-first command-line network monitoring tool designed for people who need a simple way to watch hosts, IP addresses and domains from a terminal.

It performs real checks against the targets you configure and keeps the results locally in SQLite. NetWatch can track availability, latency, packet loss, outages and recovery events without requiring a hosted monitoring service.

                    ┌──────────────────────┐
                    │      NetWatch CLI     │
                    └──────────┬───────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
           ICMP/Ping          TCP              DNS
              │                │                │
              └────────────────┼────────────────┘
                               │
                       ┌───────▼───────┐
                       │     SQLite    │
                       └───────┬───────┘
                               │
                 ┌─────────────┼─────────────┐
                 │             │             │
              Dashboard     History       Reports
                              │
                       JSON / CSV / HTML

Features

Feature	Description
ICMP monitoring	Real ping checks using the system `ping` command
TCP monitoring	Real TCP connection checks against a host and port
DNS monitoring	Real DNS resolution checks through the system resolver
Live dashboard	Terminal monitoring interface powered by Rich
Outage detection	Detects DOWN/UP transitions and records downtime
Historical data	Every check is stored locally in SQLite
Per-target settings	Custom interval, timeout, method and thresholds
Reports	Export monitoring data as JSON, CSV or standalone HTML
Diagnostics	`netwatch doctor` helps diagnose installation/environment issues
Local-first	No cloud account, external database or monitoring server required
Cross-platform	Designed for macOS and Linux
No root required	Normal operation does not require `sudo`

Installation

Clone the repository and run the installer:

git clone https://github.com/netforge201/netwatch.git
cd netwatch
chmod +x install.sh
./install.sh

The installer:

Detects a Python 3.11+ interpreter.
Creates an isolated virtual environment.
Installs NetWatch and its dependencies.
Installs the netwatch command into ~/.local/bin.
Adds ~/.local/bin to PATH when necessary.
Verifies the installation with netwatch --version.

After installation:

netwatch --help

If the command cannot be found, run:

netwatch doctor

Quick start

Add a few targets:

netwatch add 8.8.8.8 --name google-dns
netwatch add 1.1.1.1 --name cloudflare
netwatch add example.com --method dns

Start monitoring:

netwatch start

The terminal dashboard displays the current state of every target.

NetWatch

TARGET          STATUS       LATENCY       LOSS
google-dns      UP           18.7 ms       0%
cloudflare      UP           21.4 ms       0%
example.com     UP           31.2 ms       0%

Monitoring 3 target(s) | interval: 5s

Press Ctrl+C to stop the live view.

CLI

Targets

netwatch add TARGET
netwatch remove NAME
netwatch list

Examples:

netwatch add 8.8.8.8
netwatch add google.com
netwatch add 192.168.1.1 --name gateway
netwatch add 8.8.8.8 --name google-dns --interval 5 --timeout 2
netwatch add example.com --method dns
netwatch add 192.168.1.1 --method tcp --port 443

Available target options:

--name       Friendly target name
--interval   Seconds between checks
--timeout    Check timeout in seconds
--method     icmp, tcp or dns
--port       TCP port when using --method tcp

Targets are persisted in the local SQLite database and survive restarts.

Monitoring

netwatch start
netwatch start --daemon
netwatch stop
netwatch status

History and inspection

netwatch history
netwatch history NAME
netwatch inspect NAME

Historical data can be used to review availability, latency, failures and outages.

Reports

netwatch export --format json
netwatch export --format csv
netwatch export --format html

Format	Purpose
JSON	Machine-readable monitoring data
CSV	Spreadsheet-friendly export
HTML	Standalone human-readable report

Configuration

netwatch config show
netwatch config path
netwatch config edit

Diagnostics

netwatch doctor

General options

netwatch --help
netwatch --version
netwatch --verbose
netwatch --quiet

Monitoring methods

ICMP

netwatch add 192.168.1.1 --method icmp

Uses the operating system's ping utility and records the response time.

TCP

netwatch add 192.168.1.1 --method tcp --port 443

Attempts a real TCP connection to the specified port and measures the connection time.

DNS

netwatch add example.com --method dns

Performs a real DNS resolution through the system resolver and records the result.

Status model

NetWatch uses four main states:

Status	Meaning
UP	Target is reachable and within configured thresholds
DEGRADED	Target is reachable but latency/loss exceeds configured thresholds
DOWN	Consecutive failures reached the configured failure threshold
UNKNOWN	Not enough data has been collected yet

Every status is based on an actual recorded check.

Outage detection

NetWatch records status transitions and outage periods locally.

When a target changes:

UP → DOWN

NetWatch opens an outage record.

When the target recovers:

DOWN → UP

the outage is closed and its downtime duration becomes available through inspection and reports.

Configuration

The default configuration is stored at:

~/.config/netwatch/config.yaml

A typical configuration looks like:

interval: 5
timeout: 2
failure_threshold: 1

thresholds:
  latency_warning: 100
  packet_loss_warning: 5

targets: []

Configuration locations can be customized with:

NETWATCH_CONFIG_DIR
NETWATCH_DATA_DIR
NETWATCH_STATE_DIR

Other supported environment overrides include:

NETWATCH_INTERVAL
NETWATCH_TIMEOUT
NETWATCH_FAILURE_THRESHOLD
NETWATCH_LATENCY_WARNING
NETWATCH_PACKET_LOSS_WARNING

Data storage

NetWatch stores its state locally in SQLite.

Default database:

~/.local/share/netwatch/netwatch.db

The database contains monitoring targets, individual check results, status events and outage/recovery records.

No PostgreSQL, MySQL, Redis or Docker installation is required.

Architecture

The project is intentionally split into small components:

netwatch/
├── checks/        ICMP, TCP and DNS checks
├── config/        Configuration loading
├── database/      SQLite database layer
├── monitoring/    Monitoring engine and status handling
├── storage/       Persistent models and repositories
├── ui/            Terminal presentation
└── utils/         Shared utilities

tests/             Automated test suite
docs/              Project documentation

For more details, see docs/architecture.md.

Development

Clone the project:

git clone https://github.com/netforge201/netwatch.git
cd netwatch

Create a development environment:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

You can also use the bundled launcher:

./netwatch.sh --help

Testing

Run the test suite:

pytest

Run the linter:

ruff check .

The tests cover CLI behaviour, configuration, target management, database operations, monitoring logic, status transitions, outage/recovery handling, statistics, exports and error handling.

Network operations are mocked at the check boundary so the test suite does not depend on Internet availability.

Security and responsible use

NetWatch is a monitoring and diagnostics tool.

It:

performs only the checks explicitly configured by the user;
does not exploit vulnerabilities;
does not brute-force credentials;
does not bypass authentication;
does not perform destructive actions;
does not contain offensive exploitation functionality.

Only monitor systems and networks that you own or are authorized to monitor.

If you discover a security issue, please use GitHub's private security reporting mechanisms rather than publishing sensitive details in a public issue.

Roadmap

Planned ideas include:

Slack, webhook and email notifications;
HTTP/HTTPS endpoint monitoring;
status-code and response-body assertions;
distributed monitoring;
configurable historical-data retention;
additional monitoring protocols.

Support NetForge

If NetWatch is useful to you, you can support its development.

Your contribution helps with development, testing, maintenance, documentation and future open-source network tools.

Crypto donations

Important: Always verify the network before sending. Sending an asset through the wrong network may result in permanent loss of funds.

USDT — TRC-20

TYtLvfgG9szPoRUcNpsz3paYzynFmLS5Go

Network: TRON / TRC-20

TON

UQDpx5wZ03QD5tCFT6fkhKGJ-LRFhAfn7hYohEUSNoJcv6JS

Network: TON

Thank you for supporting independent open-source development.

Contributing

Issues, ideas and pull requests are welcome.

Before submitting a pull request:

pytest
ruff check .

For monitoring/check logic, please add tests that mock the underlying network operation rather than relying on a live external host.

License

NetWatch is released under the MIT License.

See LICENSE.

Русская версия

Что такое NetWatch?

NetWatch — локальный CLI-инструмент для мониторинга сети и доступности хостов, IP-адресов и доменов.

Он выполняет реальные проверки ICMP, TCP и DNS, сохраняет результаты в локальную SQLite-базу и позволяет отслеживать доступность, задержку, потери пакетов, отказы и восстановления.

Без облачного сервиса, внешней базы данных и искусственно сгенерированных показателей.

Возможности

Реальные ICMP, TCP и DNS-проверки.
Живой терминальный мониторинг.
Локальная SQLite-база.
История всех проверок.
Обнаружение DOWN/UP и расчёт длительности простоя.
Индивидуальные настройки для каждой цели.
Экспорт JSON, CSV и HTML.
Команда netwatch doctor для диагностики.
macOS и Linux.
Обычная работа без sudo.

Установка

git clone https://github.com/netforge201/netwatch.git
cd netwatch
chmod +x install.sh
./install.sh

После установки:

netwatch --help

Если команда не находится:

netwatch doctor

Быстрый старт

netwatch add 8.8.8.8 --name google-dns
netwatch add 1.1.1.1 --name cloudflare
netwatch add example.com --method dns

netwatch start

Остановить мониторинг:

Ctrl+C

Основные команды

netwatch add TARGET
netwatch remove NAME
netwatch list

netwatch start
netwatch stop
netwatch status

netwatch history
netwatch history NAME
netwatch inspect NAME

netwatch export --format json
netwatch export --format csv
netwatch export --format html

netwatch config show
netwatch config path
netwatch config edit

netwatch doctor
netwatch --help
netwatch --version

Методы мониторинга

ICMP

netwatch add 192.168.1.1 --method icmp

Реальный ping и измерение времени ответа.

TCP

netwatch add 192.168.1.1 --method tcp --port 443

Реальное TCP-подключение к указанному порту.

DNS

netwatch add example.com --method dns

Реальное разрешение доменного имени через системный DNS-резолвер.

Статусы

Статус	Значение
UP	Цель доступна и показатели находятся в пределах порогов
DEGRADED	Цель доступна, но задержка или потери превышают пороги
DOWN	Достигнут порог последовательных неудачных проверок
UNKNOWN	Пока недостаточно данных

Отчёты

netwatch export --format json
netwatch export --format csv
netwatch export --format html

JSON подходит для автоматической обработки, CSV — для таблиц, HTML — для самостоятельного просмотра отчёта.

Разработка

git clone https://github.com/netforge201/netwatch.git
cd netwatch

python3 -m venv .venv
source .venv/bin/activate

pip install -e ".[dev]"

Тесты:

pytest

Линтер:

ruff check .

Безопасность

NetWatch предназначен для мониторинга и диагностики.

Он не выполняет эксплуатацию уязвимостей, подбор паролей, обход аутентификации или разрушительные действия.

Используйте инструмент только для систем и сетей, которые вы имеете право мониторить.

Поддержать NetForge

Если NetWatch оказался полезен, вы можете поддержать дальнейшую разработку проекта и других open-source сетевых инструментов NetForge.

USDT — TRC-20

TYtLvfgG9szPoRUcNpsz3paYzynFmLS5Go

Сеть: TRON / TRC-20

TON

UQDpx5wZ03QD5tCFT6fkhKGJ-LRFhAfn7hYohEUSNoJcv6JS

Сеть: TON

Важно: всегда проверяйте сеть перед отправкой средств. Использование неправильной сети может привести к безвозвратной потере средств.

Спасибо за поддержку независимой open-source разработки.

Лицензия

MIT — см. LICENSE.

Name		Name	Last commit message	Last commit date
docs		docs
netwatch		netwatch
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh
netwatch.sh		netwatch.sh
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

NetWatch

What is NetWatch?

Features

Installation

Quick start

CLI

Targets

Monitoring

History and inspection

Reports

Configuration

Diagnostics

General options

Monitoring methods

ICMP

TCP

DNS

Status model

Outage detection

Configuration

Data storage

Architecture

Development

Testing

Security and responsible use

Roadmap

Support NetForge

Crypto donations

USDT — TRC-20

TON

Contributing

License

Русская версия

Что такое NetWatch?

Возможности

Установка

Быстрый старт

Основные команды

Методы мониторинга

Статусы

Отчёты

Разработка

Безопасность

Поддержать NetForge

USDT — TRC-20

TON

Лицензия

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages