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)
• INLINECODE3 - DNS lookups (usually pre-installed)
• INLINECODE4 access recommended for MAC address discovery

Quick Start

CODEBLOCK0

Configuration

Configure named networks in ~/.config/network-scanner/networks.json:

CODEBLOCK1

Then scan by name:

CODEBLOCK2

Safety Features

The scanner includes multiple safety checks to prevent accidental abuse:

1. 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.

CODEBLOCK3

Commands

CODEBLOCK4

Output Formats

Markdown (default):
CODEBLOCK5

JSON (--json):
CODEBLOCK6

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