whoson 0.2.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
# Windows: download from https://nmap.org/download.html and add to PATH

# 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 ping-only scan (faster, but no port/MAC info without root)
whoson 192.168.1.0/24 -t ping

# SYN stealth scan (faster than tcp, 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 (sudo for MAC/vendor info)
sudo whoson 192.168.1.0/24 -i topology.png --json data.json --csv hosts.csv

Example output

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

Scan Types

Type	Flag	Root	Ports	MAC/Vendor	Speed
TCP connect (default)	-t tcp	No	Yes	With sudo	Moderate
SYN stealth	-t syn	Yes	Yes	Yes	Fast
Ping only	-t ping	No	No	With sudo	Fastest

Use sudo for MAC/vendor detection on any scan type. Without root, you still get IP, hostname, and open ports (on tcp/syn scans).

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