network-device-monitor

# Network Device Monitor Monitor your network for unknown devices. Works with any router that exposes an HTTP admin panel. Tracks device state changes and alerts on new connections. ## Quick Start ```bash # Scan your network (requires nmap) python3 {baseDir}/scripts/scan-network.py --subnet 192.168.1.0/24 # Quick ARP-based scan (faster) python3 {baseDir}/scripts/scan-network.py --subnet 192.168.1.0/24 --arp ``` ## Options - `--subnet CIDR` — Network range to scan (required) - `--arp` — Use ARP scan (faster, requires root) - `--known FILE` — JSON file with known devices (MAC → name mapping) - `--state FILE` — State file for tracking changes (default: `~/.network-state.json`) - `--alerts` — Only output when unknown devices are found - `--json` — Output as JSON - `--table` — Pretty-print as table ## State Tracking The monitor saves device state between runs: ```json { "last_scan": "2026-03-29T12:00:00", "devices": { "AA:BB:CC:DD:EE:FF": { "ip": "192.168.1.100", "hostname": "my-laptop", "first_seen": "2026-03-29T10:00:00", "last_seen": "2026-03-29T12:00:00", "status": "online" } }, "unknown_devices": ["11:22:33:44:55:66"] } ``` ## Alert Mode Run with `--alerts` for cron/heartbeat integration: ```bash # Only prints output if unknown devices are detected python3 scan-network.py --subnet 192.168.1.0/24 --alerts ``` ## Known Devices Format Create a `known-devices.json`: ```json { "AA:BB:CC:DD:EE:FF": "My Laptop", "11:22:33:44:55:66": "Smart TV", "DE:AD:BE:EF:00:00": "Game Console" } ``` ## Notes - ARP scan requires root: `sudo python3 scan-network.py --arp` - nmap scan works without root but is slower - Works on Linux and macOS - No external API dependencies