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 multi-WAN)

Wi-Fi Stalker

Track specific Wi-Fi client devices through your UniFi infrastructure. - Device tracking by MAC address - Roaming detection between access points - Connection history with timestamps - Block/unblock devices directly from the UI - Blocked device indicator in device list - 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 - Threat categorization and analysis - Top attackers and targets - 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-3.12
• Ubuntu 22.04/24.04 (or other Linux)
• Access to UniFi Controller

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	Controller URL (e.g., https://192.168.1.1)
UNIFI_USERNAME	Username (legacy controllers)
UNIFI_PASSWORD	Password (legacy controllers)
UNIFI_API_KEY	API key (UniFi OS: UDM, UCG, Cloud 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)

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

• Set UNIFI_VERIFY_SSL=false for self-signed certificates
• UniFi OS devices (UDM, UCG) require an API key, not username/password
• 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-3.12 only, NOT 3.13+)
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 (22 tests) - tests/test_cache.py - In-memory caching with TTL expiration (18 tests) - tests/test_config.py - Pydantic settings and environment variables (13 tests) - tests/test_crypto.py - Fernet encryption for credentials (15 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