A fused common operating picture: live air tracks from a public ADS-B feed and object detections from overhead imagery, on one map, with an automatically generated SITREP.
Real output: the project's OBB detector (CUDA) over the bundled public-domain
NAIP scene of LAX — regenerate with python make_hero.py.
The vision pipeline is split on purpose:
- Precise object counts → a real detector on GPU. RT-DETR / YOLO (Ultralytics) runs on the RTX 3080 (CUDA) and produces bounding boxes and counts — the thing general vision models can't do reliably.
- Everything else → OpenAI. GPT vision writes a qualitative scene assessment of the image, and a second call fuses the detector's counts with that assessment into a SITREP.
In a deployment the OpenAI calls swap for a local model (e.g. Ollama) so no imagery leaves the enclave.
backend/reporting.pyis the only thing that changes.
| Component | Path | Role |
|---|---|---|
| Detection | backend/detection.py |
Ultralytics detector (CUDA) + rasterio georef |
| Reporting | backend/reporting.py |
OpenAI scene assessment + SITREP |
| Live tracking | backend/tracking.py |
OpenSky poller → WebSocket broadcast |
| Storage | backend/db.py |
PostGIS (SQLite fallback) |
| API | backend/main.py |
/api/detect, /ws/tracks, /healthz, /metrics |
| Map UI | frontend/ |
Leaflet ops console |
pip install -r requirements.txt
cp .env.example .env # optional: add OpenSky creds for a denser feed
uvicorn backend.main:app --reload
# open http://localhost:8000Runs the live aircraft map immediately (SQLite fallback, no detector needed).
pip install -r requirements-ml.txt # ultralytics + rasterio; installs torch
# add your OpenAI key to .envUpload an overhead image in the UI. Georeferenced GeoTIFFs plot detections on the map; plain image chips still get counts + a SITREP.
docker compose up --buildSee .env.example. Key vars: OPENAI_API_KEY, OPENSKY_CLIENT_ID/SECRET,
TRACK_BBOX, DETECTOR_MODEL, DATABASE_URL.
- Live ADS-B map (OpenSky → WebSocket → Leaflet)
- GPU detection endpoint + georeferencing
- OpenAI scene assessment + SITREP
- PostGIS storage, Docker, CI with security gates
- Deploy (API/track/UI tier is GPU-free; detection maps to a GPU node)
- AuthN/Z (currently open — see Security below)
- AIS (maritime) feed as a second track source
- Local-model reporting backend (Ollama) for offline use
Structured to map onto a subset of NIST SP 800-53 controls. Items marked (planned) are intentionally not yet implemented.
| Control | Implementation |
|---|---|
| AC-6 (least privilege) | Container runs as non-root appuser; least-privilege DB user |
| AU-2/AU-3 (audit) | Structured logging of access + detections (expand — planned) |
| CM-6 (config settings) | Pinned slim base image, minimal packages, no shell extras |
| RA-5 (vuln scanning) | Trivy image scan in CI (fails on HIGH/CRITICAL) |
| SA-11 (developer testing) | Bandit SAST + pytest in CI |
| SI-2 (flaw remediation) | pip-audit dependency scan in CI |
| SC-8 (transmission) | TLS terminated at ingress/proxy (planned — not in compose) |
| SC-28 (data at rest) | DB creds via env/secrets; host volume encryption (planned) |
Zero Trust posture: no implicit network trust between services; API and DB are isolated on the compose network with a scoped DB user. Per-request authentication is (planned) — today the API is open and intended for local/demo use.
STIG-aligned hardening: non-root runtime, slim base, dependency pinning, image vulnerability gate. Run a container STIG/CIS benchmark scan before any real deployment.
Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE.
This project depends on Ultralytics YOLO, which is AGPL-3.0 licensed. AGPL-3.0 is therefore used here for license compatibility. If you deploy a modified version of this software over a network, AGPL-3.0 section 13 requires that you offer the corresponding source to its users.