91 lines
2.9 KiB
Markdown
91 lines
2.9 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_PORT_SPEC` (optional, nmap `-p` syntax, ex: `1-10000` or `22,80,443,8989`)
|
|
- `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.
|
|
|
|
Note: Docker socket integration only has direct knowledge of the local Docker daemon (the host running NetTrak). Remote hosts are detected by network scanning only, so ensure your scan profile includes the needed ports (for example `NETTRAK_PORT_SPEC=1-10000` for `8989`).
|
|
|
|
## 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`
|