v2.0.0 - Native CrowdSec Firewall Bouncer for UniFi OS

Breaking Change: Complete Architecture Rewrite

v2.0 replaces the Python Docker-based bouncer (which used the UniFi controller API) with the official CrowdSec firewall bouncer Go binary running directly on UniFi OS devices using ipset/iptables.

Why the rewrite?

The v1.x Python bouncer worked by managing UniFi firewall groups through the controller API. While functional, it had significant limitations:

• Required Docker on a separate host
• Needed UniFi controller credentials
• Subject to API rate limits
• 60s minimum update interval
• 256MB+ RAM usage
• Firewall groups limited to ~10K IPs before controller instability

What's new in v2.0

• No Docker required — runs natively on UniFi OS devices (UDM SE, UDM Pro, UDR)
• No UniFi credentials — uses ipset/iptables directly, bypasses the controller API entirely
• 10s update frequency (was 60s)
• ~15MB RAM (was 256MB+)
• 120K+ IP capacity on UDM SE/Pro (was ~10K via API)
• Firmware-update persistence — ensure-rules.sh cron job restores rules after reboots and firmware updates
• UDR boot race fix — ssd1.mount dependency prevents the bouncer from starting before storage is mounted

Installation

See the README for the new installation process using install.sh.

Migration from v1.x

1. Stop and remove the v1.x Docker container
2. Remove the old firewall groups from the UniFi controller (they are no longer used)
3. Follow the v2.0 installation instructions in the README
4. The native bouncer will automatically pick up all CrowdSec decisions

Files

File	Purpose
install.sh	Downloads and installs the CrowdSec firewall bouncer binary
setup.sh	Configures ipset, iptables rules, and cron persistence
ensure-rules.sh	Cron job to restore rules after reboot/firmware update
crowdsec-firewall-bouncer.yaml.example	Example bouncer configuration
crowdsec-firewall-bouncer.service	systemd service file

Companion tools

• crowdsec-blocklist-import — Import external IP blocklists as CrowdSec decisions
• crowdsec-unifi-parser — Parse UniFi syslogs for CrowdSec threat detection

Closed PRs

All 9 pending v1.x feature PRs (#18-#26) have been closed as obsolete — they modified bouncer.py which no longer exists. The features they provided are either handled natively by the Go bouncer, addressed by the new architecture, or available through companion tools.

v1.2.2 - Maintenance

Changes

• Documentation updates
• CONTRIBUTING.md with AI-friendly contribution guidelines
• Note: The health endpoint (/health) referenced in earlier docs is not yet available — it will ship in a future release. Apologies for the confusion.

Docker

docker pull ghcr.io/wolffcatskyy/crowdsec-unifi-bouncer:1.2.2
# or
docker pull ghcr.io/wolffcatskyy/crowdsec-unifi-bouncer:latest

v1.2.1 - Telemetry Enabled by Default

Changes

• Telemetry enabled by default - helps track usage (set TELEMETRY_ENABLED=false to disable)
• Custom Cloudflare Worker - replaced unreliable CountAPI with dedicated worker
• Sends version + IP count - anonymous stats for version distribution and usage scale

Telemetry Dashboard

View stats at: https://bouncer-telemetry.ms2738.workers.dev/

Privacy

• No IP addresses logged
• No personal data collected
• Only tracks: version, approximate IP count range, startup count

v1.2.0 - Usage Analytics

What's New

• Opt-in telemetry: Add TELEMETRY_ENABLED=true to send anonymous startup pings
• Helps track usage without collecting any personal data
• Uses CountAPI (free, anonymous counter)

How to Enable

environment:
  - TELEMETRY_ENABLED=true

Telemetry is disabled by default and only increments a counter when the bouncer starts.

v1.1.0

Changes in v1.1.0

Improvements

• Proper User-Agent identification (crowdsec-unifi-bouncer/1.1.0)
• Added PyPI package structure
• Added comprehensive roadmap
• Docker images on ghcr.io (amd64 + arm64)
• GitHub Actions for automated releases

Documentation

• Performance benchmarks
• Failure modes & recovery
• Testing strategy
• Security considerations

Docker

docker pull ghcr.io/wolffcatskyy/crowdsec-unifi-bouncer:1.1.0

Full changelog: v1.0.0...v1.1.0

v1.0.0 - Initial Release

CrowdSec UniFi Bouncer v1.0.0

A Python-based CrowdSec bouncer that syncs ban decisions to UniFi firewall groups.

Features

• Syncs CrowdSec decisions to UniFi firewall address groups
• Supports multiple groups (bypasses 10K IP limit per group)
• Cookie-based UniFi authentication (works with UniFi OS)
• Stream API for real-time updates
• IPv6 support (optional)
• Origin filtering support
• Docker deployment

Quick Start

git clone https://github.com/wolffcatskyy/crowdsec-unifi-bouncer.git
cd crowdsec-unifi-bouncer
cp .env.example .env
# Edit .env with your credentials
docker compose up -d

Requirements

• CrowdSec LAPI with bouncer API key
• UniFi controller (tested on UniFi OS 4.x)
• Docker

Why Python?

The Go-based bouncer (teifun2/cs-unifi-bouncer) has issues with the go-unifi library API authentication. This Python implementation uses cookie-based auth which works reliably.