feat: add scan diffing, OS fingerprinting, watch mode, multi-subnet, and inventory check (v0.3.0)

Author: daniissac

README.md

@@ -1,6 +1,6 @@
 # whoson
 
-A lightweight subnet audit tool. Scan a network, see what's alive, and export a topology image -- all from the terminal.
+A lightweight subnet audit tool. Scan a network, see what's alive, diff changes, and export a topology image -- all from the terminal.
 
 [![PyPI](https://img.shields.io/pypi/v/whoson)](https://pypi.org/project/whoson/)
 [![CI](https://github.com/daniissac/whoson/actions/workflows/ci.yml/badge.svg)](https://github.com/daniissac/whoson/actions/workflows/ci.yml)
@@ -24,75 +24,146 @@ pip install whoson
 # Scan a subnet and print a host table
 whoson 192.168.1.0/24
 
-# Save a topology diagram as PNG
-whoson 192.168.1.0/24 -i topology.png
+# Scan multiple subnets at once
+whoson 192.168.1.0/24 10.0.0.0/24
 
-# Or as JPEG or SVG
+# Save a topology diagram as PNG, JPEG, or SVG
+whoson 192.168.1.0/24 -i topology.png
 whoson 192.168.1.0/24 -i topology.jpg
 whoson 192.168.1.0/24 -i topology.svg
 
 # Export as JSON or CSV
 whoson 192.168.1.0/24 --json results.json
 whoson 192.168.1.0/24 --csv hosts.csv
 
-# Use ping-only scan (faster, but no port/MAC info without root)
+# Use ping-only scan (faster, but no port info)
 whoson 192.168.1.0/24 -t ping
 
-# SYN stealth scan (faster than tcp, requires root)
+# SYN stealth scan (requires root)
 sudo whoson 10.0.0.0/24 -t syn
 
 # Quiet mode -- only write files, no terminal output
 whoson 192.168.1.0/24 -i out.png --json out.json -q
 
-# Combine everything (sudo for MAC/vendor info)
+# Combine everything (sudo for MAC/vendor/OS info)
 sudo whoson 192.168.1.0/24 -i topology.png --json data.json --csv hosts.csv
 ```
 
+### Scan Diffing
+
+Save a baseline scan and compare later to spot what changed:
+
+```bash
+# Save today's scan
+whoson 192.168.1.0/24 --save baseline.json
+
+# Later, compare against the baseline
+whoson 192.168.1.0/24 --diff baseline.json
+```
+
+Output shows added, removed, and changed hosts:
+
+```
++ 192.168.1.42  new host (workstation)
+- 192.168.1.50  gone (was: workstation)
+~ 192.168.1.10  port 8080 opened
+```
+
+### Watch Mode
+
+Continuously rescan and report changes:
+
+```bash
+# Rescan every 60 seconds
+whoson 192.168.1.0/24 --watch 60
+
+# Or use minute notation
+whoson 192.168.1.0/24 --watch 5m
+```
+
+### Known-Host Inventory
+
+Compare scan results against an expected inventory CSV to flag rogue or missing hosts:
+
+```bash
+whoson 192.168.1.0/24 --inventory hosts.csv
+```
+
+Inventory CSV format:
+
+```csv
+IP,Hostname,Type
+192.168.1.1,router,gateway
+192.168.1.10,web-srv,server
+```
+
+Output:
+
+```
+ROGUE (1 unknown hosts):
+  ! 192.168.1.42  -
+MISSING (1 expected hosts not found):
+  ? 192.168.1.50  db  (expected: server)
+OK (2 hosts match inventory)
+```
+
 ### Example output
 
 ```
 Scanning 192.168.1.0/24  (254 usable addresses, tcp scan)
 Found 5 hosts in 4.2s
 
-IP              Hostname       Type         MAC                Vendor   Ports
---------------------------------------------------------------------------------
-192.168.1.1     router.local   gateway      AA:BB:CC:DD:EE:01  Cisco    -
-192.168.1.10    web-srv        server       AA:BB:CC:DD:EE:10  Dell     80,443
-192.168.1.15    db-srv         server       AA:BB:CC:DD:EE:15  Dell     3306
-192.168.1.50    -              workstation  AA:BB:CC:DD:EE:50  Apple    -
-192.168.1.99    hp-printer     printer      AA:BB:CC:DD:EE:99  HP       9100
+IP              Hostname       Type         OS                 MAC                Vendor   Ports
+--------------------------------------------------------------------------------------------------
+192.168.1.1     router.local   gateway      Cisco IOS 15.1     AA:BB:CC:DD:EE:01  Cisco    -
+192.168.1.10    web-srv        server       Linux 5.4          AA:BB:CC:DD:EE:10  Dell     80,443
+192.168.1.15    db-srv         server       Ubuntu 20.04       AA:BB:CC:DD:EE:15  Dell     3306
+192.168.1.50    -              workstation  -                  AA:BB:CC:DD:EE:50  Apple    -
+192.168.1.99    hp-printer     printer      HP LaserJet        AA:BB:CC:DD:EE:99  HP       9100
 ```
 
 ## Scan Types
 
-| Type | Flag | Root | Ports | MAC/Vendor | Speed |
-|------|------|------|-------|------------|-------|
-| TCP connect (default) | `-t tcp` | No | Yes | With `sudo` | Moderate |
-| SYN stealth | `-t syn` | Yes | Yes | Yes | Fast |
-| Ping only | `-t ping` | No | No | With `sudo` | Fastest |
+| Type | Flag | Root | Ports | MAC/Vendor | OS Detection | Speed |
+|------|------|------|-------|------------|--------------|-------|
+| TCP connect (default) | `-t tcp` | No | Yes | With `sudo` | With `sudo` | Moderate |
+| SYN stealth | `-t syn` | Yes | Yes | Yes | Yes | Fast |
+| Ping only | `-t ping` | No | No | With `sudo` | With `sudo` | Fastest |
 
-Use `sudo` for MAC/vendor detection on any scan type. Without root, you still get IP, hostname, and open ports (on tcp/syn scans).
+Use `sudo` for MAC/vendor and OS detection on any scan type. OS fingerprinting (`nmap -O`) is enabled automatically when running as root.
 
 ## Host Classification
 
+Hosts are classified using OS fingerprint data (when available) and open ports:
+
 | Type | Criteria | Color |
 |------|----------|-------|
-| Gateway | IP ends in `.1` or `.254` | Red |
-| Server | Open ports: 22, 80, 443, 25, 53, etc. | Teal |
-| Printer | Open ports: 515, 631, 9100 | Green |
+| Gateway | OS contains network keywords (IOS, RouterOS, etc.) or IP ends in `.1`/`.254` | Red |
+| Server | OS contains server keywords (Linux, Ubuntu, etc.) or open ports: 22, 80, 443, 25, 53, etc. | Teal |
+| Printer | OS contains printer keywords (LaserJet, Ricoh, etc.) or open ports: 515, 631, 9100 | Green |
 | Workstation | Default | Blue |
 
-## Export Formats
+## CLI Reference
 
-| Format | Flag | Description |
-|--------|------|-------------|
-| PNG | `-i out.png` | Raster topology image |
-| JPEG | `-i out.jpg` | Raster topology image (compressed) |
-| SVG | `-i out.svg` | Vector topology image (scalable) |
-| JSON | `--json FILE` | Full topology data with metadata |
-| CSV | `--csv FILE` | Host list with IP, hostname, type, MAC, vendor, ports |
+```
+whoson [-h] [-t {ping,tcp,syn}] [-i FILE] [--json FILE] [--csv FILE]
+       [--save FILE] [--diff FILE] [--watch INTERVAL]
+       [--inventory FILE] [-q]
+       SUBNET [SUBNET ...]
+```
 
-The `-i` / `--image` flag detects the format from the file extension (`.png`, `.jpg`, `.jpeg`, `.svg`).
+| Flag | Description |
+|------|-------------|
+| `SUBNET` | One or more networks in CIDR notation |
+| `-t`, `--type` | Scan type: `ping`, `tcp` (default), `syn` |
+| `-i`, `--image FILE` | Save topology image (`.png`, `.jpg`, `.svg`) |
+| `--json FILE` | Save topology data as JSON |
+| `--csv FILE` | Save host list as CSV |
+| `--save FILE` | Save scan result JSON for later diffing |
+| `--diff FILE` | Compare current scan against a saved baseline |
+| `--watch INTERVAL` | Rescan at interval, show changes (e.g. `60`, `5m`) |
+| `--inventory FILE` | Compare scan against known-host inventory CSV |
+| `-q`, `--quiet` | Suppress table output (only write files) |
 
 ## Scope and Limitations
 
@@ -102,7 +173,7 @@ For real topology discovery using CDP/LLDP/SNMP, see [LibreNMS](https://www.libr
 
 ## Dependencies
 
-**Runtime:** `python-nmap` + `Pillow` (2 packages).
+**Runtime:** `python-nmap` + `Pillow` (2 packages). Zero new dependencies for all features.
 
 **System:** `nmap` must be available on `PATH`.