NetTrak/README.md

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_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.

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