# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.trentbauer.com/guides/installation-guides/crowdsec/unifi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.