88 lines
2.5 KiB
Markdown
88 lines
2.5 KiB
Markdown
# NetTrak
|
|
|
|
NetTrak is a Dockerized network inventory web app that scans a subnet and catalogs:
|
|
- Devices discovered on the network
|
|
- Open ports per device
|
|
- Service fingerprint details from `nmap`
|
|
- HTTP headers and lightweight banners when available
|
|
|
|
Results are persisted in SQLite for change tracking (new/updated/missing devices and ports).
|
|
|
|
## Features
|
|
|
|
- Dark mode UI by default
|
|
- 3-pane layout:
|
|
- Left: discovered machines
|
|
- Right-top: selected machine details
|
|
- Right-bottom: collapsible port records with headers/banners
|
|
- Background scan execution
|
|
- Live scan progress with ETA
|
|
- SQLite persistence for historical tracking
|
|
- Concurrent host scanning for faster runs
|
|
|
|
## Tech Stack
|
|
|
|
- Backend: FastAPI + SQLite
|
|
- Scanner: `nmap` + lightweight Python probes
|
|
- Frontend: Static HTML/CSS/JS
|
|
- Deployment: Docker / Docker Compose
|
|
|
|
## Run With Docker Compose
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
Then open: `http://localhost:1337`
|
|
|
|
Database file is stored at `./data/nettrak.db` via a bind mount.
|
|
|
|
## Configuration
|
|
|
|
Environment variables:
|
|
- `NETTRAK_DB_PATH` (default: `/data/nettrak.db`)
|
|
- `NETTRAK_SUBNET` (default: `192.168.2.0/24`)
|
|
- `NETTRAK_TOP_PORTS` (default: `100`)
|
|
- `NETTRAK_SCAN_WORKERS` (default: `12`)
|
|
- `NETTRAK_PORT_PROBE_TIMEOUT` (default: `0.4`)
|
|
- `NETTRAK_ENABLE_OS_DETECTION` (default: `0`)
|
|
- `NETTRAK_ENABLE_DOCKER_INSIGHTS` (default: `0`)
|
|
- `NETTRAK_DOCKER_HOST_IP` (optional, used when Docker publishes on `0.0.0.0`)
|
|
|
|
In Compose, these are already set.
|
|
|
|
## LAN Scanning Notes
|
|
|
|
- LAN host discovery can be limited in bridged container networking.
|
|
- MAC addresses are best-effort in bridged mode; for most reliable MAC/ARP discovery, run in host networking and keep `NET_RAW`/`NET_ADMIN` capabilities.
|
|
- For best results on Linux hosts, enable host networking in `docker-compose.yml`:
|
|
|
|
```yaml
|
|
network_mode: host
|
|
```
|
|
|
|
- Some `nmap` OS detection capabilities may require elevated privileges. The app automatically falls back if OS detection fails.
|
|
|
|
## Docker Container Port Awareness
|
|
|
|
NetTrak can optionally annotate host ports that are published by Docker containers on the scan host.
|
|
|
|
To enable:
|
|
- set `NETTRAK_ENABLE_DOCKER_INSIGHTS=1`
|
|
- mount the Docker socket:
|
|
|
|
```yaml
|
|
volumes:
|
|
- /var/run/docker.sock:/var/run/docker.sock:ro
|
|
```
|
|
|
|
If your Docker bindings are `0.0.0.0`, set `NETTRAK_DOCKER_HOST_IP` to the host LAN IP so mappings can be attributed correctly.
|
|
|
|
## API Endpoints
|
|
|
|
- `GET /api/health`
|
|
- `GET /api/devices`
|
|
- `GET /api/devices/{id}`
|
|
- `GET /api/scans?limit=20`
|
|
- `POST /api/scans/run?subnet=192.168.2.0/24`
|