> For the complete documentation index, see [llms.txt](https://www.trentbauer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.trentbauer.com/guides/installation-guides/crowdsec/unifi.md).

# UniFi

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td>Total Time Required</td><td>20 minutes</td></tr><tr><td>Difficulty</td><td>Easy</td></tr><tr><td>Required Knowledge</td><td>Crowdsec, UniFi</td></tr></tbody></table>

<img src="/files/ey3i8si6v8x957kjAto9" alt="" class="gitbook-drawing">

## Prerequisites

* Crowdsec account
* Your UniFi Firewall is on [the supported list](https://app.crowdsec.net/hub/author/Teifun2/remediation-components/cs-unifi-bouncer) (may work with unsupported)
* [Your Crowdsec enrollment key](/guides/installation-guides/crowdsec.md#generate-your-enrol-key)

#### This stack monitors...

* Syslog data from UniFi controller
* Crowdsec blocklists (if subscribed)
* [Additional blocklists that are normally paid](https://github.com/wolffcatskyy/crowdsec-blocklist-import?tab=readme-ov-file#included-blocklists)
* 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

{% hint style="info" %}
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
{% endhint %}

### 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&#x20;

{% hint style="warning" %}
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
{% endhint %}

## Deploy Compose stack

Fill out the below env file and deploy your stack

```dotenv
# --- 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=
```

{% hint style="warning" %}
If port 514 is not available on your host, you will need to update the port at [#forward-logs](#forward-logs "mention") to whatever port you select.
{% endhint %}

{% @github-files/github-code-block url="<https://github.com/trentnbauer/HomelabPublic/blob/main/docker-compose/crowdsec-unifi.yml>" %}

### Host Firewall

1. SSH into your host
2. Allow your syslog port through the firewall (by default 514)

{% hint style="info" %}
If you need to change your syslog port, don't forget to update UniFi at [#forward-logs](#forward-logs "mention") and your .env file   [#deploy-compose-stack](#deploy-compose-stack "mention")
{% endhint %}

### Register the blocklist container

1. Exec into the Crowdsec engine container
2. Run the below command

   ```bash
   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

   <pre class="language-bash" data-overflow="wrap"><code class="lang-bash">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
   </code></pre>

{% hint style="info" %}
This allows the blocklist container to authenticate to the Crowdsec engine. You may need to restart the blocklist and crowdsec engine containers after this
{% endhint %}

### 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&#x20;

[There is a known bug where too many blocked IPs crashes the UniFi network application](https://github.com/wolffcatskyy/crowdsec-blocklist-import?tab=readme-ov-file#firewall-bouncer-limits--ipset-sizing)

#### 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**](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

{% hint style="info" %}
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.
{% endhint %}