nikola
49 lines
1.7 KiB
Markdown
49 lines
1.7 KiB
Markdown
# 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)
|