whoson

A lightweight subnet audit tool. Scan a network, see what's alive, diff changes, 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

# Scan multiple subnets at once
whoson 192.168.1.0/24 10.0.0.0/24

# Save a topology diagram as PNG, JPEG, or SVG
whoson 192.168.1.0/24 -i topology.png
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 info)
whoson 192.168.1.0/24 -t ping

# 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 (sudo for MAC/vendor/OS info)
sudo whoson 192.168.1.0/24 -i topology.png --json data.json --csv hosts.csv

Scan Diffing

Save a baseline scan and compare later to spot what changed:

# Save today's scan
whoson 192.168.1.0/24 --save baseline.json

# Later, compare against the baseline
whoson 192.168.1.0/24 --diff baseline.json

Output shows added, removed, and changed hosts:

+ 192.168.1.42  new host (workstation)
- 192.168.1.50  gone (was: workstation)
~ 192.168.1.10  port 8080 opened

Watch Mode

Continuously rescan and report changes:

# Rescan every 60 seconds
whoson 192.168.1.0/24 --watch 60

# Or use minute notation
whoson 192.168.1.0/24 --watch 5m

Known-Host Inventory

Compare scan results against an expected inventory CSV to flag rogue or missing hosts:

whoson 192.168.1.0/24 --inventory hosts.csv

Inventory CSV format:

IP,Hostname,Type
192.168.1.1,router,gateway
192.168.1.10,web-srv,server

Output:

ROGUE (1 unknown hosts):
  ! 192.168.1.42  -
MISSING (1 expected hosts not found):
  ? 192.168.1.50  db  (expected: server)
OK (2 hosts match inventory)

Example output

Scanning 192.168.1.0/24  (254 usable addresses, tcp scan)
Found 5 hosts in 4.2s

IP              Hostname       Type         OS                 MAC                Vendor   Ports
--------------------------------------------------------------------------------------------------
192.168.1.1     router.local   gateway      Cisco IOS 15.1     AA:BB:CC:DD:EE:01  Cisco    -
192.168.1.10    web-srv        server       Linux 5.4          AA:BB:CC:DD:EE:10  Dell     80,443
192.168.1.15    db-srv         server       Ubuntu 20.04       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      HP LaserJet        AA:BB:CC:DD:EE:99  HP       9100

Scan Types

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

Use sudo for MAC/vendor and OS detection on any scan type. OS fingerprinting (nmap -O) is enabled automatically when running as root.

Host Classification

Hosts are classified using OS fingerprint data (when available) and open ports:

Type	Criteria	Color
Gateway	OS contains network keywords (IOS, RouterOS, etc.) or IP ends in .1/.254	Red
Server	OS contains server keywords (Linux, Ubuntu, etc.) or open ports: 22, 80, 443, 25, 53, etc.	Teal
Printer	OS contains printer keywords (LaserJet, Ricoh, etc.) or open ports: 515, 631, 9100	Green
Workstation	Default	Blue

CLI Reference

whoson [-h] [-t {ping,tcp,syn}] [-i FILE] [--json FILE] [--csv FILE]
       [--save FILE] [--diff FILE] [--watch INTERVAL]
       [--inventory FILE] [-q]
       SUBNET [SUBNET ...]

Flag	Description
SUBNET	One or more networks in CIDR notation
-t, --type	Scan type: ping, tcp (default), syn
-i, --image FILE	Save topology image (.png, .jpg, .svg)
--json FILE	Save topology data as JSON
--csv FILE	Save host list as CSV
--save FILE	Save scan result JSON for later diffing
--diff FILE	Compare current scan against a saved baseline
--watch INTERVAL	Rescan at interval, show changes (e.g. 60, 5m)
--inventory FILE	Compare scan against known-host inventory CSV
-q, --quiet	Suppress table output (only write files)

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). Zero new dependencies for all features.

System: nmap must be available on PATH.

Development

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