Netwatch

A sysops toolkit for monitoring, scanning, and managing network activity. Track bandwidth usage, set alerts, run benchmarks, manage backups, and generate reports — all from the command line.

Commands

Each network command (scan, monitor, alert, etc.) works in two modes:

• Without arguments — displays the 20 most recent entries of that type
• With arguments — saves the input as a new timestamped entry

Data Storage

All data is stored as plain-text log files in ~/.local/share/netwatch/:

• Each command type gets its own log file (e.g., scan.log, monitor.log, alert.log)
• Entries are stored in timestamp|value format for easy parsing
• A unified history.log tracks all activity across command types
• Export to JSON, CSV, or TXT at any time with the export command

Set the NETWATCH_DIR environment variable to override the default data directory.

Requirements

• Bash 4.0+ (uses set -euo pipefail)
• Standard Unix utilities: date, wc, du, tail, grep, sed, cat
• No external dependencies or API keys required

When to Use

1. Monitoring bandwidth usage — use monitor, top, and usage to track which processes or hosts are consuming the most bandwidth in real time
2. Network security scanning — use scan and check to audit open ports, verify DNS resolution, and ensure services are reachable
3. Setting up alerting — use alert to log threshold-based rules (e.g., notify when bandwidth exceeds 100 Mbps or a host goes unreachable)
4. Benchmarking network performance — use benchmark and compare to measure and compare latency, throughput, and jitter across different configurations
5. Managing network backups and recovery — use backup, restore, and cleanup to document config snapshots, disaster recovery steps, and housekeeping operations

Examples

# Scan the local network for active hosts
netwatch scan "192.168.1.0/24 — found 23 active hosts, 3 with open SSH"

# Monitor bandwidth on the main interface
netwatch monitor "eth0 averaging 45 Mbps download, 12 Mbps upload over last hour"

# Set an alert for high usage
netwatch alert "Trigger notification when any host exceeds 500 Mbps sustained for 5 minutes"

# Run a benchmark
netwatch benchmark "Speedtest: 940 Mbps down, 880 Mbps up, 3ms latency to ISP gateway"

# Search for past scan results
netwatch search "192.168"

Output

All commands print results to stdout. Redirect to a file if needed:

netwatch stats > network-report.txt
netwatch export json

Powered by BytesAgain | bytesagain.com | hello@bytesagain.com