API Discovery for NGINX

Automatically discover every API endpoint behind your NGINX / NGINX Plus. Detect shadow APIs, build a live API inventory, and catch anomalies with machine learning — all from your existing access logs. Self-hosted, Docker-ready, no code changes.

API Discovery for NGINX turns raw NGINX access logs into a real-time API observability dashboard. It answers the question every platform and security team eventually asks: “What APIs are actually running behind our NGINX?” — including undocumented shadow APIs and forgotten zombie endpoints — without instrumenting your application or changing a single line of code.

---

Screenshots

The actual service shows more information than the screenshots.

---

Features

• 🔎 Automatic API inventory — path-parameter normalization (/users/{id}, /orders/{uuid}) groups raw URIs into real endpoints.
• 🕵️ Shadow API detection — surface endpoints that receive traffic but aren't in your OpenAPI spec.
• 📊 Latency percentiles — p50 / p95 / p99 per endpoint, plus slowest-endpoint ranking.
• 🧠 ML / DL anomaly detection — autoencoder + LSTM models flag abnormal traffic and behavior.
• 🔓 No-auth endpoint flagging — spot endpoints served without an Authorization header.
• 🔐 Session login + RBAC — built-in admin / viewer roles.
• 📤 OpenAPI export — download the discovered surface as an OpenAPI spec.
• 🐳 Two small Docker images — env-var configuration, no config files, no app changes.

---

How it works

┌──────────────────────┐        JSON access logs         ┌───────────────────────────┐
│  Agent                │  ───────────────────────────▶  │  Dashboard                │
│  (on your NGINX host) │        (HTTPS, token auth)      │  collector + web UI :8080 │
│  api-discovery-agent  │                                 │  api-discovery-nginx      │
└──────────────────────┘                                 └───────────────────────────┘

The agent tails your NGINX access log (and optionally the NGINX Plus REST API) and ships records to the dashboard, which aggregates them into an API inventory, runs anomaly detection, and serves the web UI.

---

Quick start

1) Dashboard (on a server you can reach)

docker run -d --name api-discovery-nginx \
  -p 8080:8080 \
  -e INGEST_TOKEN=<shared-token> \
  -v $PWD/output:/app/output \
  gusgh13900/api-discovery-nginx:latest

Open http://<host>:8080 and log in with the default admin account admin / admin1234 (change it immediately under the Users tab).

2) Agent (on your NGINX / NGINX Plus host)

docker run -d --name api-discovery-agent \
  --network host \
  -e DASHBOARD_URL=http://<dashboard-host>:8080 \
  -e INGEST_TOKEN=<same-token-as-above> \
  -e LOG_PATH=/var/log/nginx/api_access.log \
  -v /var/log/nginx:/var/log/nginx:ro \
  -v $PWD/state:/agent/state \
  gusgh13900/api-discovery-agent:latest

docker-compose

The dashboard and agent run on different hosts, so there are two compose files:

# On the dashboard host
INGEST_TOKEN=<shared-token> docker compose -f docker-compose.yml up -d

# On the NGINX host
DASHBOARD_URL=http://<dashboard-host>:8080 INGEST_TOKEN=<shared-token> \
  docker compose -f docker-compose.agent.yml up -d

---

Docker images

Image	Role	Download	On disk
gusgh13900/api-discovery-nginx	Collector server + web dashboard (:8080)	~288 MB	~1 GB
gusgh13900/api-discovery-agent	NGINX log-collecting agent	~21 MB	~56 MB

These sizes — and the image-size badge above — are for the latest tag (currently 1.2.1) on linux/amd64. Download is the compressed size you actually pull; on disk is the extracted size afterwards. Pinned tags can differ significantly — 1.0.0 is still ~2.8 GB to pull, because it shipped the CUDA build of PyTorch. That was fixed in 1.1.0; every release since is listed in the release notes.

Both images are published with latest and pinned version tags (e.g. 1.2.1). Keep the dashboard and agent on the same version tag.

---

Requirements

• NGINX or NGINX Plus producing a JSON access log (a ready-to-copy log_format block is shown on the dashboard image page).
• Docker on both the dashboard host and the NGINX host.
• Works with open-source NGINX — NGINX Plus is optional (only needed for the extra REST API metrics).

---

Use cases

• API security — find shadow / undocumented / zombie APIs that expand your attack surface.
• Platform & SRE — a live, always-current inventory of every service behind the gateway.
• API governance — compare real traffic against your OpenAPI spec and export the delta.
• Performance — spot the slowest endpoints (p95 / p99) without adding APM agents.

---

FAQ

Do I need NGINX Plus? No. It works with open-source NGINX. NGINX Plus only adds optional upstream metrics.

Does it modify my application? No. It reads access logs only — zero code changes, zero request-path overhead.

Does it support ARM? Currently linux/amd64 only.

Where is data stored? In the dashboard's /app/output volume (SQLite + analysis results + accounts). Mount it to persist across restarts.

---

Login & roles

The dashboard requires a session login. On first start a default admin admin / admin1234 is created automatically — change the password after first login. Roles are admin (full access) and viewer (read-only); accounts are managed in the Users tab and persist in the output/ volume.

---

License

Apache-2.0. Use it, modify it, ship it — commercially or otherwise. The source lives in this repository.

Contact

Bug reports · feature requests · deployment questions: gusgh13900@gmail.com

---

_{NGINX® is a registered trademark of F5, Inc. This is an independent project and is not affiliated with, endorsed by, or sponsored by F5 or NGINX. The name “NGINX” is used only to describe compatibility.}