# whoson

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

[![PyPI](https://img.shields.io/pypi/v/whoson)](https://pypi.org/project/whoson/)
[![CI](https://github.com/daniissac/whoson/actions/workflows/ci.yml/badge.svg)](https://github.com/daniissac/whoson/actions/workflows/ci.yml)

## Install

```bash
# 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

```bash
# 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](https://www.librenms.org/), [Secure Cartography](https://github.com/scottpeterman/secure_cartography), or [NetDisco](https://netdisco.org/).

## Dependencies

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

**System:** `nmap` must be available on `PATH`.

## Development

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

## License

MIT
