UI Toolkit

A comprehensive suite of tools for UniFi network management and monitoring.

Note: This project is not affiliated with, endorsed by, or sponsored by Ubiquiti Inc. UniFi is a trademark of Ubiquiti Inc.

Features

Dashboard

Real-time system status including:

• Gateway Info - Model, firmware, uptime
• Resource Usage - CPU and RAM utilization
• Network Health - WAN, LAN, WLAN, VPN status with diagnostic reasons
• Connected Clients - Wired and wireless counts
• WAN Status - IP, ISP, latency, uptime (supports 3+ WANs dynamically)
• Debug Info - One-click copy of system info for issue reporting

Wi-Fi Stalker

Track specific client devices through your UniFi infrastructure.

• Device tracking by MAC address (wireless and wired)
• Roaming detection between access points
• Connection history with timestamps and CSV export
• Signal strength, radio band (2.4/5/6 GHz), and SSID tracking
• Device analytics: dwell time, favorite AP, presence pattern heatmap
• Block/unblock devices directly from the UI
• Webhook alerts (Slack, Discord, n8n) for connect, disconnect, roam, block, and unblock events

Threat Watch

Monitor IDS/IPS security events from your UniFi gateway.

• Real-time event monitoring (requires UniFi OS)
• Threat categorization and analysis
• Top attackers and targets
• Ignore rules: filter noise by IP address and severity level
• Sortable event columns and advanced filtering
• Webhook alerts (Slack, Discord, n8n)

Network Pulse

Real-time network monitoring dashboard.

• Gateway status (model, firmware, uptime, WAN)
• Device counts (total clients, wired, wireless, APs, switches)
• Chart.js visualizations (clients by band, clients by SSID, top bandwidth)
• Clickable AP cards with detailed client views
• WebSocket-powered live updates

UI Product Selector (External)

Build the perfect UniFi network at uiproductselector.com

---

Quick Start

Requirements

• Docker (recommended) or Python 3.9+
• Ubuntu 22.04/24.04 (or other Linux)
• UniFi OS controller (UDM, UCG, Cloud Key Gen2+) — standalone/self-hosted controllers are not supported as of v1.11.0

Local Deployment (LAN Only)

No authentication, access via http://localhost:8000

Prerequisites: Install Docker first - see docs/INSTALLATION.md

# Clone and setup
git clone https://github.com/Crosstalk-Solutions/unifi-toolkit.git
cd unifi-toolkit
./setup.sh  # Select 1 for Local

# Start
docker compose up -d

Access at http://localhost:8000

Production Deployment (Internet-Facing)

Authentication enabled, HTTPS with Let's Encrypt via Caddy

Prerequisites: Install Docker first - see docs/INSTALLATION.md

# Clone and setup
git clone https://github.com/Crosstalk-Solutions/unifi-toolkit.git
cd unifi-toolkit
./setup.sh  # Select 2 for Production
# Enter: domain name, admin username, password

# Open firewall ports
sudo ufw allow 80/tcp && sudo ufw allow 443/tcp

# Start with HTTPS
docker compose --profile production up -d

Access at https://your-domain.com

---

Documentation

Guide	Description
INSTALLATION.md	Complete installation guide with troubleshooting
SYNOLOGY.md	Synology NAS Container Manager setup
QNAP Guide	QNAP Container Station setup (community)
Unraid Guide	Unraid Community apps Setup
QUICKSTART.md	5-minute quick start reference

---

Common Commands

Action	Command
Start (local)	docker compose up -d
Start (production)	docker compose --profile production up -d
Stop	docker compose down
View logs	docker compose logs -f
Restart	docker compose restart
Reset password	./reset_password.sh
Update	./upgrade.sh

---

Configuration

Setup Wizard (Recommended)

Run the interactive setup wizard:

./setup.sh

The wizard will:

• Generate encryption key
• Configure deployment mode (local/production)
• Set up authentication (production only)
• Create your .env file

Manual Configuration

Copy and edit the example configuration:

cp .env.example .env

Required Settings

Variable	Description
ENCRYPTION_KEY	Encrypts stored credentials (auto-generated by setup wizard)

Deployment Settings (Production Only)

Variable	Description
DEPLOYMENT_TYPE	local or production
DOMAIN	Your domain name (e.g., toolkit.example.com)
AUTH_USERNAME	Admin username
AUTH_PASSWORD_HASH	Bcrypt password hash (generated by setup wizard)

UniFi Controller Settings

Configure via .env or the web UI (web UI takes precedence):

Variable	Description
UNIFI_CONTROLLER_URL	Local controller IP/hostname (e.g., https://192.168.1.1)
UNIFI_API_KEY	API key (recommended — generate in UniFi OS Settings → Admins)
UNIFI_USERNAME	Username (fallback if not using API key)
UNIFI_PASSWORD	Password (fallback if not using API key)
UNIFI_SITE_ID	Site ID from URL, not friendly name (default: default). For multi-site, use ID from /manage/site/{id}/...
UNIFI_VERIFY_SSL	SSL verification (default: false)

Note: Use your controller's local IP address (e.g., https://192.168.1.1). Cloud access via unifi.ui.com is not supported.

Tool Settings

Variable	Description
STALKER_REFRESH_INTERVAL	Device refresh interval in seconds (default: 60)

---

Security

Authentication

• Local mode: No authentication (trusted LAN only)
• Production mode: Session-based authentication with bcrypt password hashing
• Rate limiting: 5 failed login attempts = 5 minute lockout

HTTPS

Production deployments use Caddy for automatic HTTPS:

• Let's Encrypt certificates (auto-renewed)
• HTTP to HTTPS redirect
• Security headers (HSTS, X-Frame-Options, etc.)

Multi-Site Networking

When managing multiple UniFi sites, always use site-to-site VPN:

✅ RECOMMENDED: VPN Connection
┌──────────────────┐         ┌──────────────────┐
│  UI Toolkit      │◄──VPN──►│  Remote UniFi    │
│  Server          │         │  Controller      │
└──────────────────┘         └──────────────────┘

❌ AVOID: Direct Internet Exposure
Never expose UniFi controllers via port forwarding

VPN Options: UniFi Site-to-Site, WireGuard, Tailscale, IPSec

---

Troubleshooting

Can't connect to UniFi controller

• UniFi OS required — standalone/self-hosted controllers are not supported (v1.11.0+). If you're running the Java-based controller software, v1.10.3 is the last compatible version.
• Set UNIFI_VERIFY_SSL=false for self-signed certificates
• API key auth is recommended — generate in UniFi OS Settings → Admins
• Verify network connectivity to controller

Device not showing as online

• Wait 60 seconds for the next refresh cycle
• Verify MAC address format is correct
• Confirm device is connected in UniFi dashboard

Let's Encrypt certificate fails

• Verify DNS A record points to your server
• Ensure ports 80 and 443 are open
• Check Caddy logs: docker compose logs caddy

Rate limited on login

• Wait 5 minutes for lockout to expire
• Use ./reset_password.sh if you forgot your password

Docker issues

• Verify .env exists and contains ENCRYPTION_KEY
• Check logs: docker compose logs -f
• Pull latest image: docker compose pull && docker compose up -d

---

Running with Python (Alternative to Docker)

# Clone repository
git clone https://github.com/Crosstalk-Solutions/unifi-toolkit.git
cd unifi-toolkit

# Create virtual environment (Python 3.9+)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run setup wizard
./setup.sh

# Start application
python run.py

---

Project Structure

unifi-toolkit/
├── app/                    # Main application
│   ├── main.py            # FastAPI entry point
│   ├── routers/           # API routes (auth, config)
│   ├── static/            # CSS, images
│   └── templates/         # HTML templates
├── tools/                 # Individual tools
│   ├── wifi_stalker/      # Wi-Fi Stalker tool
│   ├── threat_watch/      # Threat Watch tool
│   └── network_pulse/     # Network Pulse tool
├── shared/                # Shared infrastructure
│   ├── config.py          # Settings management
│   ├── database.py        # SQLAlchemy setup
│   ├── unifi_client.py    # UniFi API wrapper
│   └── crypto.py          # Credential encryption
├── docs/                  # Documentation
├── data/                  # Database (created at runtime)
├── setup.sh               # Setup wizard
├── upgrade.sh             # Upgrade script
├── reset_password.sh      # Password reset utility
├── Caddyfile              # Reverse proxy config
├── docker-compose.yml     # Docker configuration
└── requirements.txt       # Python dependencies

---

Development

Running Tests

The project includes a comprehensive test suite covering authentication, caching, configuration, and encryption.

# Install development dependencies
pip install -r requirements-dev.txt

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_auth.py -v

# Run with coverage
pytest tests/ --cov=shared --cov=app -v

Test modules:

• tests/test_auth.py - Authentication, session management, rate limiting (23 tests)
• tests/test_cache.py - In-memory caching with TTL expiration (19 tests)
• tests/test_config.py - Pydantic settings and environment variables (13 tests)
• tests/test_crypto.py - Fernet encryption for credentials (14 tests)

---

Support

• Community: #unifi-toolkit on Discord
• Issues: GitHub Issues
• Documentation: docs/

Buy Me a Coffee

If you find UI Toolkit useful, consider supporting development:

---

Credits

Developed by Crosstalk Solutions

• YouTube: @CrosstalkSolutions

---

License

MIT License