netwatchdog 0.1.0

See every device on your network and know what each one is — in plain English — and get told when something new shows up. Read-only, no packet capture.

netwatchdog

See every device on your network, know what each one actually is — in plain English — and get told the moment something new shows up.

netwatchdog scans your local network, identifies each device (router, phone, TV, printer, that suspicious no-name smart plug…), and remembers what it saw so it can flag new arrivals on the next run.

It is read-only: it pings and reads your OS's neighbor/ARP table. No packet capture, no port scanning, no router login.

_{Example scan (fictional devices). Real output is color-coded by device type.}

What it tells you

• Who's here — every device on your LAN, with its IP and hostname.
• What each one is — vendor + a plain category (phone, media, printer, network gear, IoT chip, or Unknown), so the things worth a second look stand out.
• What's new — anything that wasn't on your network last time gets flagged, with advice on what to do about it.

Device identification uses a built-in table for the most-wanted categories and, optionally, the full public Wireshark OUI list (downloaded once, no account).

Install

pip install netwatchdog

Usage

netwatchdog                 # scan, identify, save/update baseline, print a report
netwatchdog --no-ping       # skip the ping sweep (faster, reads existing table)
netwatchdog --no-manuf      # don't download the full vendor database
netwatchdog --json          # emit the full report as JSON (build your own UI)
netwatchdog -b ~/mynet.json # use a specific baseline file

The first run saves a baseline of what's on your network. Later runs compare against it and highlight new devices. Your baseline (netwatch_baseline.json) describes your own LAN and is git-ignored — keep it local.

Tip: give devices a friendly name in the baseline file so future scans read cleanly, and investigate anything marked IoT chip or Unknown that you don't recognize.

Read-only by design

netwatchdog only sends pings and reads the neighbor table your OS already keeps. It never captures packets, scans ports, or logs into your router. This is a hard design boundary — see SECURITY.md.

Development

git clone https://github.com/GreenHarvestDev/netwatchdog.git
cd netwatchdog
pip install -e ".[dev]"
ruff check . && ruff format --check . && mypy && pytest

Tests are fully offline — subprocess, psutil, and socket are mocked, so the suite runs in well under a second. See CONTRIBUTING.md; new device-identification data and ARP/route format parsers are welcome (with a test).

License

MIT © 2026 GreenHarvestDev