UniFi Security Dashboard

A self-hosted Docker Compose stack that connects to a local Ubiquiti UniFi console (Dream Machine Pro, UDR, or equivalent) and surfaces firewall policy health, threat intelligence, and configuration gaps through a web dashboard and an MCP server for Claude Code / Codex integration.

---

Screenshots

| | | |---|---| | | | | Dashboard — summary cards and policy action distribution | Firewall — zone-based policy matrix with allow/block posture | | | | | Assessment — scored security checks with remediation guidance | CVE Alerts — device inventory with firmware exposure view | | | | | Threat Feeds — blocklist sources, MISP integration, and pending rule approvals | VLANs — network inventory with zone assignments | | | | | Scanner — RFC1918 port scan for firewall validation | Settings — UniFi connection, CVE monitoring, and threat feed controls |

---

What it does

• Firewall policy visualisation — zone-based policy matrix showing allow/block/reject posture across all zone pairs, with per-policy hit counts matched from syslog
• Live firewall event log — syslog receiver parses UniFi kernel block/allow/reject events and cross-references them back to the rule that fired
• IDS/IPS status — detects whether Intrusion Prevention is enabled, whether it is in detection-only or prevention mode, and flags configuration gaps
• Policy conflict and drift detection — identifies shadowed rules, duplicate policies, and tracks any change in the policy set via SHA-256 snapshot hashing
• Scored security assessment — 10 automated checks (IDS enabled, default-deny WAN posture, guest isolation, logging coverage, permissive any-any rules, and more) with remediation recommendations
• Port scan validation — triggers nmap against RFC1918 targets only, cross-references open ports against expected zone policies to surface enforcement gaps
• CVE monitoring (optional) — polls the NVD modified feed and Ubiquiti security bulletins for HIGH and CRITICAL CVEs, cross-references them against firmware versions on your connected devices, and surfaces upgrade alerts
• Threat feed integration (optional, experimental) — polls public IP blocklists (FireHOL, Spamhaus DROP, or custom feeds) and pushes them to UniFi as address groups and firewall rules; also supports MISP (Malware Information Sharing Platform) as an authenticated threat intelligence source; supports Manual mode (approval per change) or Auto Push mode
• Data retention — batched pruning of firewall logs, threat events, and scan results on a configurable schedule so the database doesn't grow unbounded on small hosts
• Push notifications (optional) — ntfy and generic webhook alerts for newly active attention-feed findings, with a configurable severity threshold and flap suppression
• Prometheus metrics (optional) — bearer-token-protected /api/v1/metrics endpoint for external monitoring
• MCP server — 15 tools for Claude Code / Codex to query live dashboard data conversationally

---

Architecture

nginx (:443 HTTPS, :80 -> redirect)
 ├── /api/*   →  api:8000      FastAPI + SQLAlchemy, polls UniFi API every 60s
 └── /*       →  frontend      React SPA served by nginx (built from Vite)

api:8000       also runs a UDP syslog receiver on :514
mcp:8001       MCP server, calls api:8000 over the internal Docker network
scanner:8002   nmap micro-service, internal only — RFC1918 targets only
postgres:5432  PostgreSQL 16, persistent volume pgdata

Four service images are published to GitHub Container Registry:

| Image | Purpose | | ----- | ------- | | ghcr.io/maddogwarner/unifi-dashboard/api | FastAPI backend | | ghcr.io/maddogwarner/unifi-dashboard/frontend | React SPA | | ghcr.io/maddogwarner/unifi-dashboard/mcp | MCP server | | ghcr.io/maddogwarner/unifi-dashboard/scanner | nmap wrapper |

---

Prerequisites

• Docker 24+ with the Compose plugin (docker compose version)
• UniFi Dream Machine Pro, UDR, or compatible console running UniFi Network 9.x+ (zone-based firewall policy API requires 9.x)
• A UniFi API key — generated at: UniFi Network → Settings → Control Plane → Integrations → Create API Key
• The machine running the stack must be reachable by the UniFi console over the network (required for syslog)

Note on SSL: Local UniFi consoles use self-signed certificates by default. Set UNIFI_VERIFY_SSL=false in your .env to allow connections without certificate validation. If your console has a trusted cert, set it to true.

---

Deployment

Option A — Pre-built images from GHCR (recommended)

No build step required. Docker Compose will pull the latest published images.

# 1. Get the Compose file and env template
curl -O https://raw.githubusercontent.com/MadDogWarner/unifi-dashboard/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/MadDogWarner/unifi-dashboard/main/.env.example

# 2. Create your env file
cp .env.example .env

# 3. Edit .env — required values
#    UNIFI_HOST      e.g. https://192.168.1.1
#    UNIFI_API_KEY   from UniFi Integrations page
#    UNIFI_SITE      usually "default"
#    POSTGRES_PASSWORD  change from the example value
nano .env

# 4. Pull and start
docker compose pull
docker compose up -d

# 5. Check all services are healthy
docker compose ps

The dashboard will be available at https://<host-ip>. HTTP requests to port 80 redirect to HTTPS.

Option B — Build from source

git clone https://github.com/MadDogWarner/unifi-dashboard.git
cd unifi-dashboard
cp .env.example .env
nano .env   # set UNIFI_HOST, UNIFI_API_KEY, UNIFI_SITE, POSTGRES_PASSWORD
docker compose up --build -d

The dashboard will be available at https://<host-ip>. HTTP requests to port 80 redirect to HTTPS.

---

TLS / HTTPS

The dashboard runs HTTPS on port 443 by default. HTTP port 80 redirects to HTTPS.

Self-signed certificate (default)

On first start, nginx automatically generates a self-signed RSA 2048 certificate valid for 10 years and writes it to certs/server.crt and certs/server.key. Your browser will warn about an untrusted certificate. This is expected for a self-hosted LAN dashboard; add a permanent browser exception.

Custom certificate

1. Obtain a certificate and private key in PEM format from your private CA, pfSense/OPNsense PKI, or openssl.
2. Name them server.crt (full certificate chain) and server.key (private key).
3. Place both files in the certs/ directory at the project root before starting the stack.
4. Start or restart nginx: docker compose restart nginx

The entrypoint only generates a self-signed cert if either file is missing. Existing complete certificate pairs are never overwritten.

Let's Encrypt (certbot)

Symlink your Certbot live directory into certs/:

ln -sf /etc/letsencrypt/live/yourdomain/fullchain.pem certs/server.crt
ln -sf /etc/letsencrypt/live/yourdomain/privkey.pem certs/server.key

Add a certbot deploy hook to run docker compose restart nginx after each renewal.

Stopping and upgrading

# Stop
docker compose down

# Upgrade to latest images (Option A)
docker compose pull
docker compose up -d

# Wipe database and start fresh (destructive)
docker compose down -v
docker compose up -d

---

Configuration

Copy .env.example to .env and set the values below.

| Variable | Required | Default | Description | | -------- | -------- | ------- | ----------- | | UNIFI_HOST | Yes | — | Local UniFi console URL, e.g. https://192.168.1.1 | | UNIFI_API_KEY | Yes | — | API key from UniFi Network → Settings → Control Plane → Integrations | | UNIFI_SITE | Yes | default | UniFi site name. Find yours at Settings → System → Site Name | | UNIFI_VERIFY_SSL | No | false | Set true only if the console certificate is trusted by your system | | POSTGRES_PASSWORD | Yes | — | Database password — change from the example value before first run | | POSTGRES_DB | No | unifi_dashboard | Database name | | POSTGRES_USER | No | dashboard | Database user | | AUTH_SECRET | Yes | — | Long random secret used to sign dashboard JWTs. Generate with openssl rand -hex 32 | | AUTH_TOKEN_LIFETIME_SECONDS | No | 86400 | Dashboard login token lifetime in seconds | | SYSLOG_PORT | No | 514 | UDP port the syslog receiver listens on | | POLL_INTERVAL_SECONDS | No | 60 | How often to poll the UniFi API. Minimum 10 | | LOG_RETENTION_DAYS | No | 30 | Initial seed for the firewall-log retention setting | | METRICS_TOKEN | No | — | Enables /api/v1/metrics with this bearer token. Generate with openssl rand -hex 32 | | MCP_AUTH_TOKEN | Yes for MCP | — | Long random bearer token required by the MCP server | | MCP_AUTH_DISABLED | Dev only | false | Set true only for isolated local MCP development | | MCP_RESOURCE_SERVER_URL | No | http://localhost:8001 | Public MCP URL used in protected-resource metadata | | VITE_API_URL | Dev only | http://localhost:8000 | Frontend dev proxy target. Not used in the Docker Compose stack |

---

Dashboard Authentication

The dashboard requires login before accessing API-backed pages. On a fresh database, the first browser visit redirects to /setup so you can create the initial administrator account. The first registered account is automatically promoted to superuser, and open registration is closed after that point.

Generate and set AUTH_SECRET before starting the API:

openssl rand -hex 32

AUTH_SECRET=<paste-generated-secret-here>
AUTH_TOKEN_LIFETIME_SECONDS=86400

All dashboard API routes require Authorization: Bearer <token> except health, login, setup status, and first-time registration. Additional accounts can be created by a superuser via POST /api/v1/users/.

---

Syslog Setup

The dashboard cross-references firewall block/allow events to policies by matching rule names from syslog. Without syslog configured, the dashboard will still show policy metadata from the API but hit counts will remain zero.

Configure remote syslog on the UniFi console:

1. UniFi Network → Settings → System → Advanced → Remote Logging
2. Set Syslog Host to the IP address of the machine running this stack
3. Set Syslog Port to 514 (or the SYSLOG_PORT value from your .env)
4. Enable the Firewall log category
5. Click Apply Changes

Docker Compose publishes UDP ${SYSLOG_PORT:-514} from the API container to the host. Confirm the mapping after startup:

docker compose port api 514/udp

Expected log format (kernel firewall events):

kernel: [WAN_LOCAL-default-D]IN=eth4 OUT= SRC=1.2.3.4 DST=192.168.1.1 LEN=60 PROTO=TCP SPT=54321 DPT=22

The action is encoded in the rule name suffix: D = drop, A = accept, R = reject.

Firewall: The host running this stack must allow inbound UDP on port 514 from the UniFi console. If using ufw: sudo ufw allow from <unifi-ip> to any port 514 proto udp

---

MCP Server

The MCP server runs on port 8001 and exposes tools that Claude Code can call to query your live UniFi security data. It requires bearer-token authentication by default and Docker Compose binds it to 127.0.0.1:8001 so it is reachable only from the host running the stack.

Generate a long random token and set it in .env before starting the MCP service:

openssl rand -hex 32