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 managemen
   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 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=

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

services:
  syslog:
    image: linuxserver/syslog-ng:4.10.2@sha256:ba6129e03d4ef21f4e822919b53914ab934b14949c6794e4a9fa32e4a3a5111b
    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
          
  engine:
    image: crowdsecurity/crowdsec:v1.7.6@sha256:63b595fef92de1778573b375897a45dd226637ee9a3d3db9f57ac7355c369493
    restart: unless-stopped
    labels:
      - AH.CS.UniFi=true
    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.2.2@sha256:16590b6fc7cb784fc2fc2fbd7fa3a2782f12823e2787dfb55f63fc8521bc4853
    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
      - 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
          
  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:-8000} # USG3P=8000, UDR=15000, UDM Pro=50000
    entrypoint: /bin/sh -c "while true; do /usr/local/bin/import.sh; echo 'Sleeping for 6 hours...'; sleep 21600; done"
    # This container is designed to be re-ran manually by the user or manually via a CRON job. I've altered the entrypoint command to sleep the container for 6 hours instead.
    networks:
      crowdsec:
        aliases:
          - blocklist
          
  init:
    image: alpine:3.23.3
    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:76d1f7341bee169cf08ed56f19d0194ff40ad970d8dfa096316499a3ebf148b0
    restart: always
    network_mode: none
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/run/docker.sock:/var/run/docker.sock

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

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. Browse to https://unifi/network/default/settings/policy-table

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

3. Click on Delete and then proceed

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

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

6. 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

2. Restart the stack and see how you go

This setting defaults to 8000 - I would suggest halving this and seeing how it goes. You can slowly increase it once its happy.