NETWATCH

Network monitoring and observability platform for authorized network administration.

Netwatch is a modular, cross-platform network observability tool designed to help an authorized user understand the state of networks they own or administer. It provides interface discovery, host monitoring, host intelligence (MAC/vendor), service observation, typed security events, change detection, latency analysis, a sweep/scan command, a security report, a Python plugin system, and a live terminal dashboard.

Authorization warning: Netwatch is a defensive administration tool. Only operate against systems and networks you are explicitly authorized to monitor. See SECURITY.md.

Features

• netwatch-ops version — version and build information
• netwatch-ops interfaces — local network interface discovery
• netwatch-ops hosts — monitored host inventory (with MAC address and vendor)
• netwatch-ops services — discovered open TCP services
• netwatch-ops events — typed security event stream (stored in SQLite)
• netwatch-ops monitor <targets...> — continuous monitoring (ping + TCP service checks)
• netwatch-ops monitor --scan — discover hosts on your local subnet and monitor them
• netwatch-ops monitor --network 192.168.100.0/24 — monitor a specific subnet
• netwatch-ops scan [--services] — one-shot host/service discovery sweep
• netwatch-ops status — at-a-glance network and monitoring summary
• netwatch-ops report — security posture report (hosts, services, exposure, events)
• netwatch-ops plugins list|run — Python analysis/reporting plugins
• netwatch-ops tui — live terminal security-operations dashboard
• netwatch-ops config — configuration inspection and initialization
• REST API server (netwatch-ops monitor --api)
• Structured logging (text/json, levels)
• SQLite storage with a swappable storage abstraction
• Output formats: terminal, json, csv
• Security-focused analysis: change detection, latency spikes, exposure review

Quick Start

# Build
make build

# Basic usage
./bin/netwatch-ops version
./bin/netwatch-ops interfaces

# Configure targets (~/.config/netwatch/config.yaml)
./bin/netwatch-ops config --init

# Monitor one or more hosts continuously
./bin/netwatch-ops monitor 192.168.1.1 192.168.1.12

# With the REST API enabled
./bin/netwatch-ops monitor --api 192.168.1.1

# Discover and monitor every host on your local (e.g. WiFi) subnet
./bin/netwatch-ops monitor --scan

# Monitor a specific subnet
./bin/netwatch-ops monitor --network 192.168.100.0/24

# Read data
./bin/netwatch-ops hosts
./bin/netwatch-ops hosts --format json
./bin/netwatch-ops services --format csv
./bin/netwatch-ops events --limit 20

# One-shot security sweep (probe only, no persistent monitoring)
./bin/netwatch-ops scan --services

# At-a-glance status + security report
./bin/netwatch-ops status
./bin/netwatch-ops report

# Plugins: list and run analysis/reporting modules
./bin/netwatch-ops plugins list
./bin/netwatch-ops plugins run network_report posture

# Live dashboard (Ctrl+C to exit)
./bin/netwatch-ops tui

If no targets are given, the monitor targets the machine's local address. Use --scan to discover and monitor every host on your local (e.g. WiFi) subnet, or --network CIDR to target a specific subnet. Targets can also be declared in the configuration file (see below).

Installation

Requirements:

• Go 1.22+ (uses CGO for SQLite; a C compiler is required)

make install          # installs to /usr/local/bin

Configuration

The default configuration file is ~/.config/netwatch/config.yaml. Override with the NETWATCH_CONFIG environment variable.

monitoring:
  interval: 30s
  timeout: 5s

database:
  path: ~/.local/share/netwatch/netwatch.db

logging:
  level: info        # debug | info | warn | error
  format: text       # text | json

api:
  enabled: false
  addr: ":8080"

tui:
  enabled: false

targets:
  - address: 192.168.1.1
    enabled: true

Generate a default configuration file:

netwatch-ops config --init
netwatch-ops config --path

Configuration is validated on load. Invalid configurations produce helpful errors.

CLI Reference

netwatch-ops version
netwatch-ops interfaces [--format terminal|json|csv]
netwatch-ops hosts [--format terminal|json|csv]
netwatch-ops services [--format terminal|json|csv]
netwatch-ops events [--format terminal|json|csv] [--limit N] [--host ID] [--category CATEGORY]
netwatch-ops monitor [targets...] [--interval 5s] [--api] [--scan | --network CIDR]
netwatch-ops scan [targets...|--scan | --network CIDR] [--services]
netwatch-ops status [--format terminal|json|csv]
netwatch-ops report
netwatch-ops plugins list [--format terminal|json|csv]
netwatch-ops plugins run NAME [ACTION] [--format terminal|json]
netwatch-ops config [--init] [--path]
netwatch-ops tui [--interval 2s]

Exit codes

• 0 — success
• 1 — runtime error (bad config, database failure, invalid input)

Data Model

Model	Fields
Host	id, address, hostname, mac, vendor, interface, status (up/down/unknown), latency, last_seen, first_seen, services
Service	id, host_id, protocol, port, state, name, version, first_seen, last_seen
Event	id, code, timestamp, severity (debug/info/notice/warning/critical), category (host/service/network/anomaly/security/config/interface/system), source, message, host_id, service_id, metadata
Measurement	id, host_id, address, latency, packet_loss, status, timestamp
Interface	name, mac, ipv4, ipv6, state, rx/tx bytes, rx/tx packets, errors, drops, speed

Event codes include HOST_NEW, HOST_ONLINE, HOST_OFFLINE, SERVICE_NEW, SERVICE_DISAPPEARED, LATENCY_SPIKE, HOST_DISCOVERED, EXPOSURE_REVIEW, UNUSUAL_CONNECTIVITY, and lifecycle codes like MONITOR_STARTED/MONITOR_STOPPED.

Severity ranking: debug < info < notice < warning < critical.

Storage

Netwatch stores data in SQLite (default ~/.local/share/netwatch/netwatch.db). The storage.Store interface abstracts persistence so the backend can be replaced without touching the engine, monitors, or API.

API

See API.md for the full API reference.

Architecture

See ARCHITECTURE.md for the detailed design, language boundaries, and roadmap.

Development

See DEVELOPMENT.md and CONTRIBUTING.md.

License

Copyright (c) Netwatch contributors. All rights reserved.