feat: initial commit

2026-05-19 14:53:36 +02:00
commit 7d34caf1a2
19 changed files with 1114 additions and 0 deletions
@@ -0,0 +1,48 @@
+# 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:
+```bash
+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):
+```bash
+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)