Network Topology Wrapper (MVP)

Internal tool for local network discovery, device tracking, and a live topology view. Designed for quick laptop testing and easy move to an internal VM.

Features (MVP)

• Periodic subnet scan (device presence)
• Device inventory (IP, hostname, guessed type, vendor hint)
• Live topology graph in web UI
• Live online/offline feed (SSE)
• Optional DNS log ingest for "which IP queried which domain"
• Optional ingest endpoints for DHCP lease and flow events

Architecture

• backend/app/main.py: FastAPI app and API routes
• backend/app/state.py: in-memory state manager and topology builder
• backend/app/scanner.py: subnet scanner and hostname/type detection
• backend/app/dnslog.py: optional dnsmasq/unbound log tailing
• frontend/: static HTML/CSS/JS UI
• scripts/: helper setup scripts

Quick Start (Laptop)

1. Copy env file:

cp .env.example .env

2. Adjust SCAN_SUBNET to your LAN (example 192.168.88.0/24).
3. Run with Docker (Linux recommended for host networking):

docker compose up --build

4. Open: http://localhost:8088

API

• GET /api/topology: full topology graph and latest device info
• GET /api/events/stream: server-sent events for live updates
• POST /api/ingest/dns: push DNS query events
• POST /api/ingest/dhcp: push DHCP lease events
• POST /api/ingest/flow: push flow events (lightweight)

Notes

• Accurate topology improves a lot with SNMP + LLDP/CDP enabled on MikroTik/Cisco devices.
• "IP -> domain" visibility depends on DNS logs and client behavior (DoH/DoT may bypass local DNS visibility).

Next Steps (after MVP)

• Add Redis + Postgres for persistence
• Add SNMP LLDP topology poller (MikroTik/Cisco)
• Add auth (basic SSO/reverse proxy)