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

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:

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:

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

2.9 KiB Raw Permalink Blame History