whoson 0.1.0

Lightweight subnet audit tool -- see what is alive on your network

whoson

A lightweight subnet audit tool. Scan a network, see what's alive, and export a topology image -- all from the terminal.

Install

# Prerequisites: nmap must be installed
brew install nmap        # macOS
sudo apt install nmap    # Debian/Ubuntu
sudo dnf install nmap    # Fedora/RHEL

# Install whoson
pip install whoson

Usage

# 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

# Or as JPEG or SVG
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 TCP connect scan instead of ping
whoson 192.168.1.0/24 -t tcp

# 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
whoson 192.168.1.0/24 -t tcp -i topology.png --json data.json --csv hosts.csv

Example output

Scanning 192.168.1.0/24  (254 usable addresses, ping 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

Host Classification

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
Workstation	Default	Blue

Export Formats

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

The -i / --image flag detects the format from the file extension (.png, .jpg, .jpeg, .svg).

Scope and Limitations

whoson shows what hosts are alive and classifies them by type. It does not discover actual Layer 2/3 topology -- it cannot determine switch port connections or router adjacencies. The image shows a star topology (all hosts connected to the gateway) because that is all that can be honestly inferred from a scan.

For real topology discovery using CDP/LLDP/SNMP, see LibreNMS, Secure Cartography, or NetDisco.

Dependencies

Runtime: python-nmap + Pillow (2 packages).

System: nmap must be available on PATH.

Development

git clone https://github.com/daniissac/whoson.git
cd whoson
pip install -e ".[dev]"
pytest

License

MIT