# 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`