📡 CYBER // SONAR — Home Network Device Scanner & Telemetry

CYBER // SONAR is a lightweight, zero-dependency, tactical intranet telemetry appliance designed to discover, track, audit, and visualize every physical device active on your local network in real-time.

Built with a high-concurrency Python backend (FastAPI + Asyncio) and a bespoke cyber-themed tactical UI featuring a 60 FPS HTML5 Canvas Sonar Radar.

---

📸 Feature Tour & Interface Walkthrough

1. Interactive 60 FPS Sonar Topology Radar

The Sonar Topology view maps your local network as a living tactical radar screen. Devices are projected onto concentric range rings using polar coordinates $(r, \theta)$ derived from their IP octet and latency. A continuous sweep beam illuminates connected nodes in real-time with phosphor persistence fades and interactive node hover cards.

• Gateway Nexus: The central hub represents your default gateway router.
• Color-Coded Status: Emerald for online devices, amber for unidentified alerts, and cyan for your primary gateway.
• Live Node Sidebar: Quick-access list of all discovered hosts with instant telemetry inspection.

---

2. Device Matrix & Hardware Telemetry Table

The Device Matrix tab presents a dense, high-readability overview of all hardware connected to your intranet. Each row displays real-time connection status, resolved hostnames, IP leases, hardware MAC addresses, IEEE OUI manufacturer resolution, device category badges, open ports, and last-seen timestamps.

• Instant Search & Filter Pills: Filter on-the-fly by ALL, ONLINE, UNKNOWN, and OFFLINE or search by IP, MAC, vendor, or custom nickname.
• Port Visibility: Immediate insight into accessible services (HTTP, HTTPS, SSH, WebSockets).

---

3. Device Telemetry Inspector & Custom Labeling

Clicking INSPECT on any node or table row opens the slide-out Telemetry Inspector Drawer. This drawer provides an in-depth hardware profile and allows you to assign permanent custom nicknames and categorized device badges that persist in SQLite across scans and DHCP lease shifts.

• Custom Nicknames: Label random MACs with friendly identifiers like "Husain's iPhone", "Living Room Apple TV", or "Home Assistant Server".
• Categorization Engine: Assign tags (💻 Workstation, 📱 Mobile, 📺 Smart TV, 🕹️ Console, 💡 IoT, 🖨️ Printer).
• Device Maintenance: One-click option to forget inactive devices from historical records.

---

4. Real-Time Chronological Event Stream

The Event Timeline ledger is driven by a SQLite state-diff engine. Every time a background or manual sweep executes, the engine compares the previous network snapshot against the new state and logs atomic events.

• 🟢 DEVICE_JOINED / DEVICE_RECONNECTED: Logged whenever a new device connects to your Wi-Fi.
• 🟡 DEVICE_LEFT: Emitted when a device drops offline or leaves the premises.
• 🔵 IP_CHANGED: Automatically tracked when a device's DHCP IP lease changes while preserving its hardware profile and custom nickname.

---

5. Scanner Configuration & Subnet Controls

The Scanner Configuration modal lets you customize your telemetry engine according to your home or lab requirements.

• Configurable Auto-Scan Intervals: Choose between rapid telemetry (15s), standard monitoring (60s), or periodic sweeps (5–15 mins).
• Custom Subnet Targeting: Automatically defaults to your active network interface or accepts custom CIDR notation (e.g. 192.168.1.0/24, 10.0.0.0/24).
• Cache Purge & Rescan: One-click database wipe to clear stale devices and run a fresh authentic intranet sweep.

---

⚡ Core Capabilities

• 🌐 Zero-Dependency High-Concurrency Discovery: Sweeps entire /24 subnets (254 host IPs) in seconds via parallel asynchronous socket probing and kernel ARP table synchronization.
• 🔍 Offline IEEE OUI Hardware Resolution: Built-in vendor lookup table covering thousands of hardware manufacturers (Apple, Nokia, Intel, Xiaomi, Espressif, Broadcom, Raspberry Pi, TP-Link, Samsung, etc.) with automatic private/randomized MAC detection.
• 🍏 ZeroConf / Bonjour / mDNS Hostname Resolution: Active discovery across Apple (_companion-link, _airplay), Google Cast, HomeKit (_hap), and NetBIOS services to resolve device friendly names (e.g., "Husain's MacBook Air").
• 🔊 Procedural Web Audio Synthesizer: Custom synthesized tactical audio soundscape (sonar pings, sweep hums, detection alerts) built with Web Audio API.

---

🏗️ Architecture Overview

graph TD
    A[Physical Intranet / Subnet] -->|Parallel ICMP & Socket Sweep| B[Scanner Engine]
    B -->|Kernel ARP Parsing / arp -a| C[MAC & IP Discovery]
    C -->|ZeroConf & mDNS dns-sd| D[Bonjour Name Resolver]
    C -->|IEEE OUI Lookup Table| E[Hardware Vendor Resolver]
    D --> F[FastAPI REST Core]
    E --> F
    F <-->|WAL Mode / State Diffing| G[(SQLite Telemetry DB)]
    F <-->|REST Endpoints / Static Mount| H[Tactical Sonar Dashboard UI]

Loading

---

🚀 Quick Start

1. Prerequisites

• Python 3.9 or higher
• macOS or Linux

2. Installation

Clone the repository and install dependencies:

git clone https://github.com/husainhakim/NetworkDeviceScanner.git
cd NetworkDeviceScanner
pip install -r requirements.txt

3. Run the Scanner

Run the single-command starter script:

python3 start.py

Or using the shell launcher:

chmod +x run.sh
./run.sh

The tactical web dashboard will automatically open in your default browser at: 👉 http://127.0.0.1:8000

---

💻 CLI Options

# Run on a custom port
python3 start.py --port 9000

# Run in headless / server mode (no browser auto-open)
python3 start.py --no-browser

# Custom host binding
python3 start.py --host 0.0.0.0 --port 8000

---

📡 API Reference

Method	Endpoint	Description
GET	/api/status	Current scan state, network interface info, subnet CIDR, and global telemetry stats.
GET	/api/devices	List all discovered devices with optional filters (?status=online|offline|unknown&search=query).
GET	/api/devices/{mac}	Get detailed telemetry for a specific hardware MAC address.
PUT	/api/devices/{mac}/label	Update custom nickname and device category (computer, mobile, iot, router, etc.).
DELETE	/api/devices/{mac}	Forget/remove a device from historical records.
POST	/api/scan	Trigger an immediate manual subnet discovery sweep.
POST	/api/purge	Purge database cache and execute a fresh discovery cycle.
GET	/api/events	Chronological audit log of connection joins, leaves, and IP changes.
GET	/api/history	Historical log of scan durations and device counts.
GET/POST	/api/settings	Retrieve or update auto-scan interval and custom subnet target.

---

🧪 Testing

Run the comprehensive unit and integration test suite:

pytest -v tests/test_scanner.py

---

📁 Directory Structure

NetworkDeviceScanner/
├── assets/               # Embedded UI screenshots and visual documentation
│   ├── device_inspector.jpg
│   ├── device_matrix.jpg
│   ├── event_timeline.jpg
│   ├── scanner_config.jpg
│   └── sonar_topology.jpg
├── backend/
│   ├── database.py       # SQLite persistence layer (WAL mode, diff engine)
│   ├── main.py           # FastAPI server and background scan orchestrator
│   ├── oui_lookup.py     # Offline IEEE OUI database and MAC normalization
│   └── scanner.py        # Subnet sweep, socket probes, ARP parsing, and Bonjour
├── frontend/
│   ├── css/
│   │   └── style.css     # Tactical Sonar styling & glassmorphism theme
│   ├── js/
│   │   ├── app.js        # UI controller, state manager, and Web Audio synth
│   │   └── radar.js      # 60 FPS HTML5 Canvas Sonar visualizer
│   └── index.html        # Tactical HUD structure
├── tests/
│   └── test_scanner.py   # Full test suite (OUI, DB sync, REST endpoints)
├── project_journey.md    # Technical learning document & networking paradigms
├── requirements.txt      # Python dependencies (FastAPI, Uvicorn, Pytest)
├── run.sh                # Executable shell launcher
├── start.py              # CLI launcher with auto-port detection
└── .gitignore            # Git exclusion rules