network-scanner

# Network Scanner Discover and identify devices on local or remote networks using nmap. Gathers IP addresses, hostnames (via reverse DNS), MAC addresses, and vendor identification. **Safety First:** Includes built-in protection against accidentally scanning public IP ranges or networks without proper private routing — preventing abuse reports from hosting providers. ## Requirements - `nmap` - Network scanning (`apt install nmap` or `brew install nmap`) - `dig` - DNS lookups (usually pre-installed) - `sudo` access recommended for MAC address discovery ## Quick Start ```bash # Auto-detect and scan current network python3 scripts/scan.py # Scan a specific CIDR python3 scripts/scan.py 192.168.1.0/24 # Scan with custom DNS server for reverse lookups python3 scripts/scan.py 192.168.1.0/24 --dns 192.168.1.1 # Output as JSON python3 scripts/scan.py --json ``` ## Configuration Configure named networks in `~/.config/network-scanner/networks.json`: ```json { "networks": { "home": { "cidr": "192.168.1.0/24", "dns": "192.168.1.1", "description": "Home Network" }, "office": { "cidr": "10.0.0.0/24", "dns": "10.0.0.1", "description": "Office Network" } }, "blocklist": [ { "cidr": "10.99.0.0/24", "reason": "No private route from this host" } ] } ``` Then scan by name: ```bash python3 scripts/scan.py home python3 scripts/scan.py office --json ``` ## Safety Features The scanner includes multiple safety checks to prevent accidental abuse: 1. **Blocklist** — Networks in the `blocklist` config array are always blocked 2. **Public IP check** — Scanning public (non-RFC1918) IP ranges is blocked 3. **Route verification** — For ad-hoc CIDRs, verifies the route uses private gateways **Trusted networks** (configured in `networks.json`) skip route verification since you've explicitly approved them. ```bash # Blocked - public IP range $ python3 scripts/scan.py 8.8.8.0/24 ❌ BLOCKED: Target 8.8.8.0/24 is a PUBLIC IP range # Blocked - in blocklist $ python3 scripts/scan.py 10.99.0.0/24 ❌ BLOCKED: 10.99.0.0/24 is blocklisted # Allowed - configured trusted network $ python3 scripts/scan.py home ✓ Scanning 192.168.1.0/24... ``` ## Commands ```bash # Create example config python3 scripts/scan.py --init-config # List configured networks python3 scripts/scan.py --list # Scan without sudo (may miss MAC addresses) python3 scripts/scan.py home --no-sudo ``` ## Output Formats **Markdown (default):** ``` ### Home Network *Last scan: 2026-01-28 00:10* | IP | Name | MAC | Vendor | |----|------|-----|--------| | 192.168.1.1 | router.local | AA:BB:CC:DD:EE:FF | Ubiquiti | | 192.168.1.100 | nas.local | 11:22:33:44:55:66 | Synology | *2 devices found* ``` **JSON (--json):** ```json { "network": "Home Network", "cidr": "192.168.1.0/24", "devices": [ { "ip": "192.168.1.1", "hostname": "router.local", "mac": "AA:BB:CC:DD:EE:FF", "vendor": "Ubiquiti" } ], "scanned_at": "2026-01-28T00:10:00", "device_count": 2 } ``` ## Use Cases - **Device inventory**: Keep track of all devices on your network - **Security audits**: Identify unknown devices - **Documentation**: Generate network maps for documentation - **Automation**: Integrate with home automation to detect device presence ## Tips - Use `sudo` for accurate MAC address detection (nmap needs privileges for ARP) - Configure your local DNS server for better hostname resolution - Add configured networks to skip route verification on every scan - Add networks you can't reach privately to the blocklist to prevent accidents - Extend `MAC_VENDORS` in the script for better device identification