Initial commit

README.md

@@ -0,0 +1,63 @@
+# 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
+- SQLite persistence for historical tracking
+
+## 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:8080`
+
+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`)
+
+In Compose, these are already set.
+
+## LAN Scanning Notes
+
+- LAN host discovery can be limited in bridged container networking.
+- 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.
+
+## 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`