Introduction
# 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