Drop-in install of the official CrowdSec firewall bouncer on UniFi OS devices — with persistence that survives firmware updates, reboots, and controller reprovisioning. Includes an intelligent sidecar proxy that scores and prioritizes threats when you have more decisions than your device can hold.
Tip
v2.4.0 Released — AbuseIPDB reporting is now built into the sidecar. Automatically report locally-banned IPs to AbuseIPDB, contributing your CrowdSec detections to community threat intelligence. See AbuseIPDB Reporting to enable it. Release notes
Caution
Beware of impostor repositories. The official CrowdSec UniFi Bouncer is hosted at wolffcatskyy/crowdsec-unifi-bouncer. We do not distribute ZIP file downloads or executable installers. If you see a repo offering "one-click downloads" of this project, it may contain malware. Always install via the official instructions below.
Note: This project was developed with and is supported by AI. Issues and PRs are triaged and responded to by AI agents. If you need a human just ask, but honestly AI is faster, smarter, and nicer.
New to CrowdSec? CrowdSec is a free, open-source security engine that detects and blocks malicious IPs using crowd-sourced threat intelligence. Get started with the official install guide.
- One-line install —
curl | bashbootstrap onto any supported UniFi device - Firmware-proof persistence — survives UniFi OS updates, reboots, and controller reprovisioning
- Auto-detection — identifies your device model and applies safe ipset limits automatically
- Sidecar proxy — scores 120K+ decisions across 7 factors, fits the highest-priority threats into your device's capacity
- Stream-aware capping (v2.3.0) — prevents ipset overflow on high-churn CAPI streams with configurable eviction
- Prometheus metrics — monitor ipset fill ratio, dropped decisions, and sidecar effectiveness
- Grafana dashboard — included, ready to import
- AbuseIPDB reporting (v2.4.0) — automatically reports locally-banned IPs to AbuseIPDB, contributing to community threat intelligence
- LOG rules for detection (v2.5.0) — iptables LOG rules make dropped packets visible to CrowdSec, enabling port scan detection and AbuseIPDB reporting
- Lightweight — 15 MB RAM for the bouncer, 8 MB for the sidecar
- The Problem
- Quick Start
- Architecture
- Device Compatibility
- Installation
- Configuration
- Sidecar Proxy
- AbuseIPDB Reporting
- LOG Rules for Detection
- Prometheus Metrics
- Troubleshooting
- Migration from v1.x
- Related Projects
- Contributing
Two problems, one project.
Problem 1: Persistence. The official bouncer binary works perfectly on UniFi devices, but UniFi OS doesn't make it easy to keep it running. Firmware updates wipe your iptables rules. Controller reprovisioning silently removes custom firewall rules. Systemd service links disappear. You install it, it works, then one day it's quietly stopped blocking anything.
Problem 2: Capacity. CrowdSec's community blocklist (CAPI) can push 100,000+ decisions to your bouncer. UniFi devices have hardware-limited ipset capacity (15K-30K entries depending on model). When the ipset fills up, new IPs fail silently — "Hash is full" errors buried in the log, zero alerting, and your most dangerous new threats get dropped while stale entries from last month sit in the set.
The solution: An installer, persistence scripts, and an optional sidecar proxy that handles all of this. Install once, forget about it.
Prerequisites: A running CrowdSec LAPI instance and SSH root access to your UniFi device.
# 1. On your CrowdSec host — create a bouncer API key
cscli bouncers add my-unifi-bouncer
# Save the API key output
# 2. SSH into your UniFi device and install
ssh root@YOUR_UNIFI_IP
curl -sSL https://raw.githubusercontent.com/wolffcatskyy/crowdsec-unifi-bouncer/main/bootstrap.sh | bash
# 3. Configure — set your LAPI address and API key
$EDITOR /data/crowdsec-bouncer/crowdsec-firewall-bouncer.yaml
# 4. Start
systemctl start crowdsec-firewall-bouncer
# 5. Verify
ipset list crowdsec-blacklists -t | grep "Number of entries"That's it. The bouncer auto-detects your device, sets safe ipset limits, and persists across firmware updates.
SSH into your UniFi device and run:
curl -sSL https://raw.githubusercontent.com/wolffcatskyy/crowdsec-unifi-bouncer/main/bootstrap.sh | bashThis downloads all required files and runs the installer automatically.
# Clone this repo
git clone https://github.com/wolffcatskyy/crowdsec-unifi-bouncer.git
cd crowdsec-unifi-bouncer
# Copy files to your UniFi device
scp install.sh setup.sh detect-device.sh detect-sidecar.sh ensure-rules.sh \
log-rules.sh ipset-capacity-monitor.sh metrics.sh \
crowdsec-firewall-bouncer.service crowdsec-unifi-metrics.service \
crowdsec-firewall-bouncer.yaml.example \
root@<UNIFI_IP>:/tmp/
# SSH in and run installer
ssh root@<UNIFI_IP>
cd /tmp && bash install.shEdit /data/crowdsec-bouncer/crowdsec-firewall-bouncer.yaml and set your api_url and api_key. If using the sidecar proxy, point api_url at port 8084 instead of the LAPI port 8080.
See the full configuration reference for all settings, startup commands, and verification steps.
Three persistence mechanisms keep the bouncer running through firmware updates and controller reprovisioning. An optional sidecar proxy scores 120K+ decisions across 7 factors so your device's limited ipset always holds the highest-priority threats.
See docs/architecture.md for the full diagram and persistence mechanism details.
The bouncer auto-detects your UniFi device model and applies safe ipset limits. Supported tiers: Enterprise (80K), Pro (50K), Consumer (15K). UX and UXG-Lite are not supported.
See docs/device-compatibility.md for the full device matrix, environment variables, and usage scenarios.
The sidecar scores all LAPI decisions across 7 factors (scenario severity, origin, freshness, recidivism, and more) and returns only the top N that fit your device. Your local detections and manual bans always survive — only low-signal bulk imports are dropped.
Deploy it if your LAPI has more than ~15K-30K decisions, or if you subscribe to community blocklists. See docs/sidecar.md for setup and scoring details.
Enable in the sidecar to automatically report locally-detected bans to AbuseIPDB. Reporting is fire-and-forget and never affects bouncer operation. Only local detections are reported — CAPI and blocklist-import decisions are skipped to avoid circular reporting.
See docs/abuseipdb.md for configuration and scenario-to-category mapping.
The bouncer blocks malicious IPs, but by default UniFi routers silently drop packets with no log entry. Without visibility into dropped traffic, CrowdSec cannot detect patterns like port scans from already-blocked IPs, and has nothing to report to AbuseIPDB or CAPI.
The log-rules.sh script solves this by inserting iptables LOG rules immediately before every DROP rule in UniFi's WAN firewall chains. Dropped packets are logged to syslog with structured prefixes like [UNIFI-WAN_LOCAL-D-ALL], making them parseable by crowdsec-unifi-parser.
What this enables:
- CrowdSec detection of port scans and brute force from blocked IPs
- AbuseIPDB reporting of detected attacks (via the sidecar)
- CAPI contribution (sharing your detections with the CrowdSec community)
LOG rules are automatically maintained by ensure-rules.sh (runs every 5 minutes via cron), so they survive reboots and firmware updates. They are rate-limited (10/min burst 20) to avoid log flooding.
Setup: LOG rules are deployed automatically during installation. To check status or manage manually:
# Check current LOG rule status
/data/crowdsec-bouncer/log-rules.sh --status
# Manually redeploy
/data/crowdsec-bouncer/log-rules.sh
# Remove all LOG rules
/data/crowdsec-bouncer/log-rules.sh --removeSyslog forwarding: To complete the detection loop, configure your UniFi device to forward syslog to your CrowdSec instance. See the crowdsec-unifi-parser for parser configuration.
The bouncer exposes metrics on port 9101 (ipset fill ratio, blocked IPs, dropped decisions). The sidecar exposes effectiveness metrics on port 8084. A Grafana dashboard is included at grafana/crowdsec-unifi-bouncer-dashboard.json.
See docs/metrics.md for the full metrics reference.
Common issues: bouncer starts but no IPs blocked, iptables rules disappearing, service lost after firmware update, sidecar 502s, ipset full.
See docs/troubleshooting.md for diagnostics and solutions.
If upgrading from v1.x:
- Stop and remove the old Docker container
- Delete old firewall groups from UniFi controller (named
crowdsec-ban-*) - Delete old firewall rules (indices 20000-20013)
- Follow the Installation steps above
The native bouncer uses ipset/iptables directly:
- No MongoDB thrashing -- v1.x API approach caused router freezes at 2000+ IPs
- No UniFi credentials needed
- No Docker overhead -- single Go binary, 15 MB RAM
- Faster response -- 10s polling vs 60s
| Project | Description |
|---|---|
| crowdsec-unifi-suite | One-command installer for the full stack |
| crowdsec-blocklist-import | Import 28+ threat feeds into CrowdSec |
| crowdsec-unifi-parser | Parse UniFi firewall logs for CrowdSec |
Contributions are welcome. Please open an issue to discuss significant changes before submitting a PR.
- Shell scripts are linted with ShellCheck via CI
- Go code (sidecar) follows standard Go conventions
- All PRs run through CI before merge
This project uses AI-assisted support for faster issue responses. If you'd prefer to speak with a human, mention it in your issue and the maintainer will be notified.
MIT -- see LICENSE
- CrowdSec + UniFi Installation Guide by Trent Bauer
Changelog Highlights
v2.4.0 -- AbuseIPDB reporting. Automatically reports locally-banned IPs to AbuseIPDB with scenario-to-category mapping, daily rate limiting, and smart origin filtering. Fire-and-forget, never affects bouncer operation.
v2.3.0 -- Stream-aware decision capping. MAX_DECISIONS and EVICTION_MODE control CAPI decision limits. Local decisions always pass through.
v2.2.0 -- Effectiveness metrics for the sidecar proxy: per-origin kept/dropped counters, score distribution, recidivism stats, false-negative detection. Multi-arch Docker images published to GHCR.
v2.1.0 -- Intelligent sidecar proxy with 7-factor scoring. Prioritizes decisions so the most dangerous threats always make it into your ipset.
v2.0.0 -- Complete rewrite. Replaced the Python/Docker bouncer (UniFi controller API) with the official Go binary using ipset/iptables directly. No MongoDB thrashing, no credentials needed, 15 MB RAM.
See the full changelog for all releases.
- CrowdSec -- the open-source security engine
- crowdsecurity/cs-firewall-bouncer -- the official Go binary
- unifi-utilities/unifios-utilities -- community patterns for persisting custom services on UniFi OS
- Trent Bauer -- community guide and writeup