cs-unifi-bouncer

README

CrowdSec Unifi Bouncer

A CrowdSec Bouncer for Unifi appliance

[!CAUTION] This was only tested with an UDM in a homelab environment. Further testing is needed

[!NOTE]
Due to various quirks of the Unifi API this got more complicated than originally planned.

Description

This repository aim to implement a CrowdSec bouncer for the routers of Unifi to block malicious IP to access your services. For this it leverages Unifi API to populate a dynamic Firewall Address List. Specically the Go Library go-unifi is used.

Acknowledgment

This is a Fork of funkolab/cs-mikrotik-bouncer and would not have been possible without this previous work

Usage

For now, this web service is mainly thought to be used as a container.
If you need to build from source, you can get some inspiration from the Dockerfile.

Prerequisites

You should have a Unifi appliance and a CrowdSec instance running.
The container is available as docker image ghcr.io/teifun2/cs-unifi-bouncer. It must have access to CrowdSec and to Unifi.

Generate a bouncer API key following CrowdSec documentation

Procedure

1. Get a bouncer API key from your CrowdSec with command cscli bouncers add unifi-bouncer
2. Copy the API key printed. You WON'T be able the get it again.
3. Paste this API key as the value for bouncer environment variable CROWDSEC_BOUNCER_API_KEY, instead of "MyApiKey"
4. Start bouncer with docker-compose up bouncer in the example directory
5. It will directly communicate with your Unifi appliance and configure Rules and IP Groups

Configuration

The bouncer configuration is made via environment variables:

Name	Description	Default	Required
CROWDSEC_BOUNCER_API_KEY	CrowdSec bouncer API key required to be authorized to request local API	none	✅
CROWDSEC_URL	Host and port of CrowdSec agent	http://crowdsec:8080/	✅
CROWDSEC_ORIGINS	Space separated list of CrowdSec origins to filter from LAPI (EG: "crowdsec cscli")	none	❌
CROWDSEC_UPDATE_INTERVAL	Interval Frequency Querying the Crowdsec API for changes to the blocklist.	5s	❌
LOG_LEVEL	Minimum log level for bouncer in zerolog levels	1	❌
UNIFI_HOST	Unifi appliance address	none	✅
UNIFI_USER	Unifi appliance username	none	✅
UNIFI_PASS	Unifi appliance password	none	✅
UNIFI_IPV6	Enable / Disable IPv6 support	true	❌
UNIFI_SITE	Unifi Site Configuration in case of multiple sites	default	❌
UNIFI_MAX_GROUP_SIZE	UDM has a max IP Group size of 10'000 This might be different for other appliances	10000	❌
UNIFI_IPV4_START_RULE_INDEX	If you have other custom Rules defined in your Firewall this might need to be changed to prevent collisions	22000	❌
UNIFI_IPV6_START_RULE_INDEX	If you have other custom Rules defined in your Firewall this might need to be changed to prevent collisions	27000	❌
UNIFI_SKIP_TLS_VERIFY	Skips Certificate check for unifi controllers without proper SSL Certificate	false	❌
UNIFI_LOGGING	Generate Syslog entries when the firewall rules are matched	false	❌

Contribution

Any constructive feedback is welcome, feel free to add an issue or a pull request. I will review it and integrate it to the code.