Metadata-Version: 2.4
Name: whoson
Version: 0.3.0
Summary: Lightweight subnet audit tool -- see what is alive on your network
Author-email: Dani Issac <daniissac@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/daniissac/whoson
Project-URL: Repository, https://github.com/daniissac/whoson
Project-URL: Issues, https://github.com/daniissac/whoson/issues
Keywords: network,scanner,nmap,subnet,topology
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: python-nmap
Requires-Dist: Pillow
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"

# whoson

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

# 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:

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

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

```bash
whoson 192.168.1.0/24 --inventory hosts.csv
```

Inventory CSV format:

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

## Dependencies

**Runtime:** `python-nmap` + `Pillow` (2 packages). Zero new dependencies for all features.

**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
