whoson 0.1.0__tar.gz

whoson-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: whoson
+Version: 0.1.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, 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
+
+# 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 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](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

whoson-0.1.0/README.md

@@ -0,0 +1,109 @@
+# 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
+
+# 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 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](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

whoson-0.1.0/cli.py

@@ -0,0 +1,155 @@
+"""whoson -- lightweight subnet audit tool."""
+
+import argparse
+import sys
+import time
+
+from discovery.nmap_scan import NetworkScanner
+from graph.topology_builder import TopologyBuilder
+from utils.exporters import TopologyExporter
+
+
+def _print_table(scan_results):
+    """Print a host table to stdout."""
+    hosts = scan_results.get('hosts', [])
+    if not hosts:
+        print("No hosts found.")
+        return
+
+    builder = TopologyBuilder()
+
+    rows = []
+    for h in hosts:
+        host_type = builder._classify_host(h)
+        ports = ','.join(str(p['port']) for p in h.get('open_ports', []))
+        rows.append({
+            'ip': h.get('ip', ''),
+            'hostname': h.get('hostname', '') or '-',
+            'type': host_type,
+            'mac': h.get('mac_address', '') or '-',
+            'vendor': h.get('vendor', '') or '-',
+            'ports': ports or '-',
+        })
+
+    col_widths = {
+        'ip': max(len('IP'), max(len(r['ip']) for r in rows)),
+        'hostname': max(len('Hostname'), max(len(r['hostname']) for r in rows)),
+        'type': max(len('Type'), max(len(r['type']) for r in rows)),
+        'mac': max(len('MAC'), max(len(r['mac']) for r in rows)),
+        'vendor': max(len('Vendor'), max(len(r['vendor']) for r in rows)),
+        'ports': max(len('Ports'), max(len(r['ports']) for r in rows)),
+    }
+
+    header = (
+        f"{'IP':<{col_widths['ip']}}  "
+        f"{'Hostname':<{col_widths['hostname']}}  "
+        f"{'Type':<{col_widths['type']}}  "
+        f"{'MAC':<{col_widths['mac']}}  "
+        f"{'Vendor':<{col_widths['vendor']}}  "
+        f"{'Ports':<{col_widths['ports']}}"
+    )
+    sep = '-' * len(header)
+
+    print(header)
+    print(sep)
+    for r in rows:
+        print(
+            f"{r['ip']:<{col_widths['ip']}}  "
+            f"{r['hostname']:<{col_widths['hostname']}}  "
+            f"{r['type']:<{col_widths['type']}}  "
+            f"{r['mac']:<{col_widths['mac']}}  "
+            f"{r['vendor']:<{col_widths['vendor']}}  "
+            f"{r['ports']:<{col_widths['ports']}}"
+        )
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog='whoson',
+        description='Lightweight subnet audit tool -- see what is alive on your network.',
+    )
+    parser.add_argument(
+        'subnet',
+        help='Network in CIDR notation (e.g. 192.168.1.0/24)',
+    )
+    parser.add_argument(
+        '-t', '--type',
+        choices=['ping', 'tcp', 'syn'],
+        default='ping',
+        help='Scan type (default: ping)',
+    )
+    parser.add_argument(
+        '-i', '--image',
+        metavar='FILE',
+        help='Save topology image (format from extension: .png, .jpg, .svg)',
+    )
+    parser.add_argument(
+        '--json',
+        metavar='FILE',
+        dest='json_file',
+        help='Save topology data as JSON',
+    )
+    parser.add_argument(
+        '--csv',
+        metavar='FILE',
+        dest='csv_file',
+        help='Save host list as CSV',
+    )
+    parser.add_argument(
+        '-q', '--quiet',
+        action='store_true',
+        help='Suppress table output (only write files)',
+    )
+
+    args = parser.parse_args(argv)
+
+    scanner = NetworkScanner()
+
+    if not scanner.validate_subnet(args.subnet):
+        print(f"Error: invalid subnet '{args.subnet}'", file=sys.stderr)
+        sys.exit(1)
+
+    info = scanner.get_network_info(args.subnet)
+    if not args.quiet:
+        print(f"Scanning {args.subnet}  ({info['usable_addresses']} usable addresses, {args.type} scan)")
+
+    t0 = time.time()
+    scan_results = scanner.scan_subnet(args.subnet, args.type)
+    elapsed = time.time() - t0
+
+    total = scan_results['total_hosts']
+    if not args.quiet:
+        print(f"Found {total} host{'s' if total != 1 else ''} in {elapsed:.1f}s\n")
+
+    if total == 0:
+        return
+
+    if not args.quiet:
+        _print_table(scan_results)
+
+    builder = TopologyBuilder()
+    topology_data = builder.build_topology(scan_results)
+    exporter = TopologyExporter()
+
+    if args.image:
+        exporter.export_image(topology_data, args.image)
+        if not args.quiet:
+            print(f"\nImage saved to {args.image}")
+
+    if args.json_file:
+        json_str = exporter.export_json(topology_data)
+        with open(args.json_file, 'w', encoding='utf-8') as f:
+            f.write(json_str)
+        if not args.quiet:
+            print(f"JSON saved to {args.json_file}")
+
+    if args.csv_file:
+        csv_str = exporter.export_csv_nodes(topology_data)
+        with open(args.csv_file, 'w', encoding='utf-8') as f:
+            f.write(csv_str)
+        if not args.quiet:
+            print(f"CSV saved to {args.csv_file}")
+
+
+if __name__ == '__main__':
+    main()

whoson-0.1.0/config.py

@@ -0,0 +1,13 @@
+"""Shared configuration constants for n2g."""
+
+NODE_COLORS = {
+    'gateway': '#ff6b6b',
+    'server': '#4ecdc4',
+    'workstation': '#45b7d1',
+    'printer': '#96ceb4',
+    'unknown': '#999999',
+}
+
+SERVER_PORTS = {22, 23, 25, 53, 80, 135, 139, 443, 445, 993, 995}
+
+PRINTER_PORTS = {515, 631, 9100}

whoson-0.1.0/discovery/__init__.py

@@ -0,0 +1 @@
+# Discovery module for network scanning

whoson-0.1.0/discovery/nmap_scan.py

@@ -0,0 +1,114 @@
+import nmap
+import ipaddress
+import logging
+from typing import List, Dict, Any
+import time
+
+class NetworkScanner:
+    def __init__(self):
+        self.nm = nmap.PortScanner()
+        self.logger = logging.getLogger(__name__)
+    
+    def validate_subnet(self, subnet: str) -> bool:
+        """Validate if the provided subnet is valid."""
+        try:
+            ipaddress.ip_network(subnet, strict=False)
+            return True
+        except ValueError:
+            return False
+    
+    def scan_subnet(self, subnet: str, scan_type: str = 'ping') -> Dict[str, Any]:
+        """
+        Scan a subnet for live hosts using Nmap.
+        
+        Args:
+            subnet: Network subnet in CIDR notation (e.g., '192.168.1.0/24')
+            scan_type: Type of scan ('ping', 'tcp', 'syn')
+        
+        Returns:
+            Dictionary containing scan results
+        """
+        if not self.validate_subnet(subnet):
+            raise ValueError(f"Invalid subnet format: {subnet}")
+        
+        scan_results = {
+            'subnet': subnet,
+            'hosts': [],
+            'scan_time': time.time(),
+            'total_hosts': 0
+        }
+        
+        try:
+            # Configure scan arguments based on type
+            if scan_type == 'ping':
+                arguments = '-sn'  # Ping scan only
+            elif scan_type == 'tcp':
+                arguments = '-sT -F'  # TCP connect scan with fast mode
+            elif scan_type == 'syn':
+                arguments = '-sS -F'  # SYN stealth scan with fast mode
+            else:
+                arguments = '-sn'
+            
+            self.logger.info(f"Starting {scan_type} scan of {subnet}")
+            scan_result = self.nm.scan(hosts=subnet, arguments=arguments)
+            
+            for host in self.nm.all_hosts():
+                host_info = {
+                    'ip': host,
+                    'hostname': '',
+                    'state': self.nm[host].state(),
+                    'protocols': [],
+                    'open_ports': [],
+                    'mac_address': '',
+                    'vendor': ''
+                }
+                
+                # Get hostname
+                if 'hostnames' in self.nm[host] and self.nm[host]['hostnames']:
+                    host_info['hostname'] = self.nm[host]['hostnames'][0]['name']
+                
+                # Get MAC address and vendor info
+                if 'addresses' in self.nm[host]:
+                    if 'mac' in self.nm[host]['addresses']:
+                        host_info['mac_address'] = self.nm[host]['addresses']['mac']
+                        if 'vendor' in self.nm[host]:
+                            host_info['vendor'] = list(self.nm[host]['vendor'].values())[0] if self.nm[host]['vendor'] else ''
+                
+                # Get port information if available
+                for protocol in self.nm[host].all_protocols():
+                    host_info['protocols'].append(protocol)
+                    ports = self.nm[host][protocol].keys()
+                    for port in ports:
+                        port_state = self.nm[host][protocol][port]['state']
+                        if port_state == 'open':
+                            host_info['open_ports'].append({
+                                'port': port,
+                                'protocol': protocol,
+                                'service': self.nm[host][protocol][port].get('name', 'unknown')
+                            })
+                
+                scan_results['hosts'].append(host_info)
+            
+            scan_results['total_hosts'] = len(scan_results['hosts'])
+            self.logger.info(f"Scan completed. Found {scan_results['total_hosts']} hosts")
+            
+        except Exception as e:
+            self.logger.error(f"Scan failed: {str(e)}")
+            raise Exception(f"Network scan failed: {str(e)}")
+        
+        return scan_results
+    
+    def get_network_info(self, subnet: str) -> Dict[str, Any]:
+        """Get basic network information."""
+        try:
+            network = ipaddress.ip_network(subnet, strict=False)
+            return {
+                'network_address': str(network.network_address),
+                'broadcast_address': str(network.broadcast_address),
+                'netmask': str(network.netmask),
+                'total_addresses': network.num_addresses,
+                'usable_addresses': network.num_addresses - 2 if network.num_addresses > 2 else 0,
+                'prefix_length': network.prefixlen
+            }
+        except ValueError as e:
+            raise ValueError(f"Invalid network: {str(e)}")

whoson-0.1.0/graph/__init__.py

@@ -0,0 +1 @@
+# Graph module for topology building

whoson-0.1.0/graph/topology_builder.py

@@ -0,0 +1,131 @@
+import ipaddress
+import logging
+from typing import List, Dict, Any
+
+from config import SERVER_PORTS, PRINTER_PORTS
+
+
+class TopologyBuilder:
+    def __init__(self):
+        self.nodes: Dict[str, Dict[str, Any]] = {}
+        self.edges: List[Dict[str, Any]] = []
+        self.logger = logging.getLogger(__name__)
+
+    def build_topology(self, scan_results: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Build network topology from scan results.
+
+        Args:
+            scan_results: Results from network scanner
+
+        Returns:
+            Dict with nodes and edges representing the topology
+        """
+        self.nodes.clear()
+        self.edges.clear()
+        hosts = scan_results.get('hosts', [])
+        subnet = scan_results.get('subnet', '')
+
+        if not hosts:
+            return self.get_graph_data()
+
+        for host in hosts:
+            ip = host['ip']
+            self.nodes[ip] = {
+                'ip': ip,
+                'hostname': host.get('hostname', ''),
+                'state': host.get('state', 'unknown'),
+                'mac_address': host.get('mac_address', ''),
+                'vendor': host.get('vendor', ''),
+                'open_ports': host.get('open_ports', []),
+                'protocols': host.get('protocols', []),
+                'node_type': self._classify_host(host),
+            }
+
+        self._infer_connections(hosts, subnet)
+
+        return self.get_graph_data()
+
+    def _classify_host(self, host: Dict[str, Any]) -> str:
+        """Classify host type based on IP address and open ports."""
+        ip = host['ip']
+        if ip.endswith('.1') or ip.endswith('.254'):
+            return 'gateway'
+
+        host_ports = {port['port'] for port in host.get('open_ports', [])}
+
+        if host_ports & SERVER_PORTS:
+            return 'server'
+
+        if host_ports & PRINTER_PORTS:
+            return 'printer'
+
+        return 'workstation'
+
+    def _infer_connections(self, hosts: List[Dict[str, Any]], subnet: str):
+        """
+        Build a star topology: every host connects to the gateway.
+
+        This is the only topology that can be honestly inferred from a
+        scan without SNMP/CDP/LLDP neighbor data.
+        """
+        try:
+            network = ipaddress.ip_network(subnet, strict=False)
+            gateway_ip = str(network.network_address + 1)
+
+            actual_gateway = None
+            for ip, attrs in self.nodes.items():
+                if attrs.get('node_type') == 'gateway':
+                    actual_gateway = ip
+                    break
+
+            if actual_gateway:
+                gateway_ip = actual_gateway
+
+            if gateway_ip not in self.nodes:
+                return
+
+            host_ips = [h['ip'] for h in hosts]
+            for ip in host_ips:
+                if ip != gateway_ip:
+                    self.edges.append({
+                        'source': ip,
+                        'target': gateway_ip,
+                        'weight': 1.0,
+                        'type': 'gateway',
+                    })
+
+        except (ValueError, ipaddress.AddressValueError) as exc:
+            self.logger.error("Error inferring connections: %s", exc)
+
+    def get_graph_data(self) -> Dict[str, Any]:
+        """Get graph data in a format suitable for D3.js visualization."""
+        nodes = []
+        for ip, attrs in self.nodes.items():
+            nodes.append({
+                'id': ip,
+                'label': attrs.get('hostname') or ip,
+                'ip': ip,
+                'type': attrs.get('node_type', 'workstation'),
+                'hostname': attrs.get('hostname', ''),
+                'state': attrs.get('state', 'unknown'),
+                'mac_address': attrs.get('mac_address', ''),
+                'vendor': attrs.get('vendor', ''),
+                'open_ports': len(attrs.get('open_ports', [])),
+                'protocols': attrs.get('protocols', []),
+            })
+
+        type_counts: Dict[str, int] = {}
+        for attrs in self.nodes.values():
+            nt = attrs.get('node_type', 'unknown')
+            type_counts[nt] = type_counts.get(nt, 0) + 1
+
+        return {
+            'nodes': nodes,
+            'links': list(self.edges),
+            'stats': {
+                'total_nodes': len(nodes),
+                'total_links': len(self.edges),
+                'node_types': type_counts,
+            },
+        }