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:a35e85b7ae1ca94ce1aff877a6576829ac6188d655406eb3fd824cc2bc5c2a65
    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
    entrypoint: >
      /bin/bash -c "
      cscli machines add blocklist --password $$BLOCKLISTPASSWORD -f /etc/crowdsec/blocklist_credentials.yaml --force && 
      /bin/bash /docker_start.sh" 
      
  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.1.0@sha256:4783e1c6b06bbf4aab7b41708da9f0505e1911987bb29c489140d5db64c9bf30
    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:8e4165deae9ad8f31f3185e497be61561e8cab653d54113374c7937699a85921
    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:

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

Host Firewall

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

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.