UniFi

Total Time Required

20 minutes

Difficulty

Easy

Required Knowledge

Crowdsec, UniFi

Prerequisites

• Crowdsec account

• Your UniFi Firewall is on the supported list (may work with unsupported)

• Your Crowdsec enrollment key

This stack monitors...

• Syslog data from UniFi controller

• Crowdsec blocklists (if subscribed)

• Additional blocklists that are normally paid

• Crowdsec whitelists

... And changes

• UniFi firewall

UniFi changes

Service account

You will need to generate a service account for the UniFi bouncer to log into and use

1. Navigate to https://unifi/network/default/admins/

2. Untick "Admin Permissions"

3. Create a new user and fill out the below

   First name	Crowdsec
   Last name	Bouncer
   Admin	True
   Restrict to local access	True
   Username	<randomly generated>
   Password	<randomly generated>
   Use a predifined role	False
   Unifi	Full management
   OTHER ROLES	None

4. Save your username and password to your text editor

5. Click on Create

We are randomly generating the username and password as this account has full write access (although only in LAN) to your UniFi controller - you do not want to use simple credentials for this level of access

Forward Logs

1. Navigate to https://unifi/network/default/settings/cybersecure/traffic-logging

2. Set Syslog to SIEM server or external

3. Set the server address to the IP of the machine that will run this stack

4. Click on Apply Changes

Enable Firewall zones

1. Navigate to https://unifi/network/default/settings/zones

2. Enable Firewall zones

this will import your existing firewall rules and port forwards to the new Firewall zones, but please test and ensure your critical infrastructure is still working

Deploy Compose stack

Fill out the below env file and deploy your stack

# --- CrowdSec Configuration ---
CROWDSEC_ENROLL_KEY=
MAX_DECISIONS=4000
BOUNCER_KEY=MandatoryUnsolvedSnippetMonetizeDrizzle8
BLOCKLISTPASSWORD=OccupantCorporalVividness9DiabetesCrumb

# --- Syslog Configuration ---
# The port your UniFi equipment will send logs to
SYSLOG_PORT=514
TZ=UTC

# --- UniFi Controller Configuration ---
# The IP or Hostname of your UniFi Controller (UDM/Gateway)
UNIFI_HOST=https://unifi
SKIP_TLS_VERIFY=true
UNIFI_USER=
UNIFI_PASS=

If port 514 is not available on your host, you will need to update the port at Forward Logs to whatever port you select.

https://github.com/trentnbauer/HomelabPublic/blob/main/docker-compose/crowdsec-unifi.yml

services:
  syslog:
    image: linuxserver/syslog-ng:4.10.2@sha256:b77c32d93b9e9b84f4fdd9261d7dd1db3b8a6f90391459b1ca51c82af9828bf8
    labels:
      - AH.CS.UniFi=true
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s
    restart: unless-stopped
    environment:
      - TZ=${TZ:-UTC}  
    ports:
      - ${SYSLOG_PORT:-514}:5514/udp
      - ${SYSLOG_PORT:-514}:6601/tcp 
    volumes:
      - syslog:/config
      - logs:/var/log
    networks:
      crowdsec:
        aliases:
          - syslog
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "2"
          
  engine:
    image: crowdsecurity/crowdsec:v1.7.8@sha256:2f527c9bb8b367120eb08b82890aa912ce96bfa1ada93dda0721700e4b4e0dde
    restart: unless-stopped
    labels:
      - AH.CS.UniFi=true
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "2"
    depends_on:
      init:
        condition: service_completed_successfully
      syslog:
        condition: service_started
    environment:
      - COLLECTIONS=crowdsecurity/unifi crowdsecurity/whitelist-good-actors
      - BOUNCER_KEY_unifi=${BOUNCER_KEY:-MandatoryUnsolvedSnippetMonetizeDrizzle8}
      - ENROLL_INSTANCE_NAME=UniFi
      - DISABLE_LOCAL_API=false
      - DISABLE_ONLINE_API=false
      - ENROLL_KEY=${CROWDSEC_ENROLL_KEY}
      - BLOCKLISTPASSWORD=${BLOCKLISTPASSWORD:-OccupantCorporalVividness9DiabetesCrumb}
      - TZ=${TZ:-UTC}  
    healthcheck:  
      test: ["CMD", "cscli", "version"]
      interval: 30s
      timeout: 10s
      retries: 5
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s
    volumes:
      - crowdsec:/etc/crowdsec
      - logs:/var/log/syslog:ro
      - db:/var/lib/crowdsec/data
    networks:
      crowdsec:
        aliases:
          - crowdsec
      
  bouncer:
    image: ghcr.io/teifun2/cs-unifi-bouncer:v1.4.0@sha256:6d68590366ed57b38bc4c30b99849299b686023174e58847ccc94059ab9d5f2b
    restart: unless-stopped
    labels:
      - AH.CS.UniFi=true
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s
    environment:
      - CROWDSEC_URL=http://crowdsec:8080
      - UNIFI_MAX_GROUP_SIZE=${MAX_DECISIONS:-4000}
      - BATCH_SIZE=${MAX_DECISIONS:-4000}
      - UNIFI_MAX_GROUP_SIZE=${MAX_DECISIONS:-4000}
      - CROWDSEC_BOUNCER_API_KEY=${BOUNCER_KEY:-MandatoryUnsolvedSnippetMonetizeDrizzle8}
      - UNIFI_HOST=${UNIFI_HOST:-https://unifi}
      - UNIFI_USER=${UNIFI_USER}
      - UNIFI_PASS=${UNIFI_PASS}
      - UNIFI_SKIP_TLS_VERIFY=${SKIP_TLS_VERIFY:-true}
      - TZ=${TZ:-UTC}  
    depends_on:
      engine:
        condition: service_healthy
    networks:
      crowdsec:
        aliases:
          - bouncer
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "2"
          
  blocklist:
    image: ghcr.io/wolffcatskyy/crowdsec-blocklist-import:3.3.2@sha256:dc562b89ec4642f5e587641408059b0e880cc4b460546527cc3831470e809538
    depends_on:
      engine:
        condition: service_healthy
    restart: unless-stopped
    labels:
      - AH.CS.UniFi=true
    environment:
      - CROWDSEC_LAPI_URL=http://crowdsec:8080
      - CROWDSEC_MACHINE_ID=blocklist
      - CROWDSEC_MACHINE_PASSWORD=${BLOCKLISTPASSWORD:-OccupantCorporalVividness9DiabetesCrumb}
      - MODE=lapi
      #- MODE=docker
      #- CROWDSEC_CONTAINER=crowdsec-unifi-engine
      - DECISION_DURATION=24h
      - TZ=${TZ:-UTC}
      - MAX_DECISIONS=${MAX_DECISIONS:-4000} # USG3P=8000, UDR=15000, UDM Pro=50000
      - INTERVAL=21600
    #command: sh -c "while true; do python blocklist_import.py; echo 'Sleeping for 6 hours...'; sleep 21600; done"
    networks:
      crowdsec:
        aliases:
          - blocklist
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "2"
          
  init:
    image: alpine:3.23.4
    volumes:
      - crowdsec:/etc/crowdsec
      - logs:/var/log/syslog
    command: >
      sh -c "apk add --no-cache wget ca-certificates &&
             mkdir -p /etc/crowdsec/acquisitions.d &&
             mkdir -p /var/log/syslog &&
             touch /var/log/syslog/messages &&
             chmod -R 777 /var/log/syslog &&
             wget -qO /etc/crowdsec/acquis.yaml https://raw.githubusercontent.com/trentnbauer/HomelabPublic/main/crowdsec/unifi.yaml"

  autoheal:
    deploy:
      replicas: 1
      restart_policy:
        condition: on-failure
        delay: 30s
        max_attempts: 5
        window: 120s
    environment:
      AUTOHEAL_CONTAINER_LABEL: AH.CS.UniFi
      AUTOHEAL_INTERVAL: 60
      AUTOHEAL_START_PERIOD: 240
      AUTOHEAL_DEFAULT_STOP_TIMEOUT: 60
      WEBHOOK_URL: ${AUTOHEAL_WEBHOOK:-}
    image: willfarrell/autoheal@sha256:16c4c3d8c9bdfa5e842f18863556d2a5c685d33cea62a6da9dfbc6ea941df77c
    restart: always
    network_mode: none
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/run/docker.sock:/var/run/docker.sock
    logging:
      driver: "json-file"
      options:
        max-size: "5m"
        max-file: "2"

networks:
  crowdsec:

volumes:
  crowdsec:
  logs:
  syslog:
  db:

Host Firewall

1. SSH into your host

2. Allow your syslog port through the firewall (by default 514)

If you need to change your syslog port, don't forget to update UniFi at Forward Logs and your .env file Deploy Compose stack

Register the blocklist container

1. Exec into the Crowdsec engine container

2. Run the below command

   cscli machines add blocklist --password $BLOCKLISTPASSWORD -f /etc/crowdsec/blocklist_credentials.yaml --force

3. Restart the engine and blocklist containers

4. Check the engine container logs, you should see something similar to the below

   time="2026-04-25T12:43:59+10:00" level=info msg="(blocklist/blocklist-import) external/blocklist (AbuseIPDB) for 1000/1000 decisions : 24h ban on Ip 137.184.107.118" module=db
   time="2026-04-25T12:43:59+10:00" level=info msg="(blocklist/blocklist-import) external/blocklist (AbuseIPDB) for 999/1000 decisions : 24h ban on Ip 137.184.105.225" module=db
   time="2026-04-25T12:43:59+10:00" level=info msg="(blocklist/blocklist-import) external/blocklist (AbuseIPDB) for 998/1000 decisions : 24h ban on Ip 137.184.76.231" module=db
   time="2026-04-25T12:43:59+10:00" level=info msg="(blocklist/blocklist-import) external/blocklist (AbuseIPDB) for 997/1000 decisions : 24h ban on Ip 137.184.76.120" module=db
   time="2026-04-25T12:43:59+10:00" level=info msg="(blocklist/blocklist-import) external/blocklist (AbuseIPDB) for 996/1000 decisions : 24h ban on Ip 137.184.64.22" module=db

This allows the blocklist container to authenticate to the Crowdsec engine. You may need to restart the blocklist and crowdsec engine containers after this

Confirm the bouncer has logged into the account

1. Navigate to https://unifi/network/default/admins/

2. Review the list and find Crowdsec Bouncer - the last activity should state "now"

If not, review the bouncer and engine container logs

Enroll the engine

1. Navigate to https://app.crowdsec.net/security-engines

2. Locate the UniFi in the enrollment list

3. Enrol the engine

4. Wait 5 minutes

Check UniFi firewall rules exit

1. Navigate to https://unifi/network/default/settings/zones

2. You will have a stack of "cs-unifi-bouncer" rules

---

Known Issues

UniFi network appliance crashing

This will show as

• Slowness accessing UniFi network software

• Alerts for router being offline

• Router showing as offline in at

There is a known bug where too many blocked IPs crashes the UniFi network application

You will first need to remove the firewall rules and lists

This is a bit of a nightmare as the network application will crash often while you are doing this.

1. Stop the Crowdsec UniFi stack

2. Browse to https://unifi/network/default/settings/policy-table

3. Click on Manage, and tick all of the CS- rules

4. Click on Delete and then proceed

5. Browse to https://unifi/network/default/settings/networks and scroll down to lists

6. Click on Manage, and tick all of the CS- rules

7. Click on Delete and then proceed

Or follow this: https://github.com/wolffcatskyy/crowdsec-blocklist-import?tab=readme-ov-file#recovery-network-app-crash

Adjust the blocklist limit

1. Update the compose env file variable MAX_DECISION - you will need to reduce the number

2. Restart the stack and see how you go

The env file is set to 4000, which I believe is much lower than the cap - IF you have issues, I would suggest halving this and seeing how it goes. You can slowly increase it once its happy.