Crosstalk-Solutions/unifi-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.

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

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

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)

Lock a device or a whole network down using UniFi's zone-based firewall. Reversible in one click, and honest about exactly what is and is not being blocked.

• Networks - Editable audit matrix of your VLANs: firewall zone, network isolation, internet access, mDNS, and DHCP DNS at a glance, with per-SSID Wi-Fi client isolation
• DNS Lockdown - Force chosen networks onto approved DNS resolvers and block everything else answering DNS (optionally DNS-over-TLS too)
• Devices - Per-device lockdown presets by MAC: Full lockdown, Internet only, or LAN only, with multi-device selection
• Blocked traffic view - See what each lockdown actually stopped, attributed to its own rules by ID
• Every change is previewed before applying, every rule carries a marker so release can only ever delete its own rules, and a lockdown that stops enforcing (MAC changed, rule disabled in UniFi) is flagged instead of shown green
• Requires the zone-based firewall (UniFi Network 9.0+ on a UniFi OS console)

See docs/HOUSE-ARREST.md for the full guide, including measured limitations.

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

• 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

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

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

Images are published to both GHCR (ghcr.io/crosstalk-solutions/unifi-toolkit) and Docker Hub (crosstalksolutions/unifi-toolkit), and they are identical. :latest is the release channel and only moves on tagged releases. :edge is the beta channel, rebuilt on every merge. See Running the beta channel.

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

Copy and edit the example configuration:

cp .env.example .env

UniFi controller credentials are configured through the web UI after first launch (the gear icon on the dashboard). They are stored encrypted in the database, not read from environment variables.

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

Every secret-carrying variable also accepts a _FILE variant (e.g. ENCRYPTION_KEY_FILE=/run/secrets/key) for Docker Swarm / Kubernetes secrets mounted as files.

• 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

Production deployments use Caddy for automatic HTTPS:

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

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

• 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.
• Stable (GA) firmware only. Early Access firmware changes APIs without notice and is not supported. If a tool suddenly gets errors or empty data, check your firmware channel first (your firmware version is in Debug Info).
• 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

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

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

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

• The toolkit only answers requests addressed to an IP, localhost, a .local-style name, or your configured DOMAIN (anti-DNS-rebinding protection). Add other names, like a Tailscale MagicDNS name or a reverse-proxy alias, to ALLOWED_HOSTS in .env.

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

# 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

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
│   └── house_arrest/      # House Arrest 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

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)
• tests/test_house_arrest_policies.py - House Arrest policy builders, zone resolution, safety checks (199 tests)

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

If you find UI Toolkit useful, consider supporting development:

Developed by Crosstalk Solutions

• YouTube: @CrosstalkSolutions

MIT License