Hey everyone! I work at CrowdSec so take this as a vendor post. I noticed there's a good guide here for another feed, and people keep asking about CrowdSec on OPNsense, so here's how to set it up both ways, straight from our docs.
There are two ways to use CrowdSec on OPNsense, and they work fine together:
- **The plugin (os-crowdsec)** runs the CrowdSec Security Engine on the firewall itself. It reads OPNsense's logs, spots attacks, and blocks the attacking IPs before they reach anything behind the firewall, including machines that don't run CrowdSec.
- **Blocklists with no plugin.** If you'd rather not install anything, OPNsense can pull a CrowdSec blocklist into a URL Table (IPs) alias and block it with a normal firewall rule.
### Option 1: the plugin
- Go to **System > Firmware > Plugins**, tick **Show community plugins** on the right, select **os-crowdsec** and install it. It installs three packages: `os-crowdsec` (the plugin), `crowdsec` and `crowdsec-firewall-bouncer`.
- Don't enable or start the services from the shell like on a regular FreeBSD box. The plugin manages them.
- Refresh the page and open **Services > CrowdSec > Overview** to check the services are running.
- In **Services > CrowdSec > Settings**, the Log Processor, the LAPI and the Remediation Component are on by default. The `crowdsecurity/freebsd` and `crowdsecurity/opnsense` collections come preinstalled and update on their own.
- Private IP ranges are whitelisted by default (since 1.6.3), so a local decision won't block something on 192.168.x.y.
To test it, ban yourself for two minutes from the OPNsense shell (keep a second IP handy in case):
```
cscli decisions add -t ban -d 2m -i <your_ip_address>
```
Your SSH session should freeze and you'll be locked out for two minutes. Don't test by failing SSH logins on purpose: the default ban is 4 hours, and CrowdSec reads the logs from the start, so it can ban you for failed logins from before you installed it.
### Option 2: blocklists, no plugin
- In the CrowdSec Console (free account), go to **Blocklist > Integrations**, pick **OPNsense** and click **Connect**.
- Give it a name. You can turn on **IP aggregation** (groups IPs into CIDR ranges to keep the list small) and set a **pull limit** (10,000 IPs by default).
- Copy the username and password right away: they're shown only once. If you lose them, you can regenerate them from the integration page.
- Subscribe the integration to blocklists. The free tier gives you 3. Some of the free lists are third-party lists: we check them against known-safe IPs, but we don't curate their data, so they can have false positives. The catalog shows each list's overlap with the others, which helps you pick.
In OPNsense, create an alias of type **URL Table (IPs)** under **Firewall > Aliases**, with this URL:
```
https://<username>:<password>@admin.api.crowdsec.net/v1/integrations/<integration_id>/content
```
On the free tier the list is pulled every 24 hours, so a daily refresh is enough.
- Add a firewall rule that blocks traffic whose source is that alias.
- Check the alias filled up under **Firewall > Diagnostics > Aliases**.
Two things to keep in mind: the credentials sit in the alias URL, so treat your config backups accordingly. And if you raise the pull limit a lot, keep it under about 300,000 entries unless you turn on compression, or the response gets cut off.
### Which one?
The plugin reacts to what hits your firewall and needs a bit more setup. The blocklist route takes a few minutes and blocks known attackers before they show up at all. Plenty of people run both.
Docs:
- Plugin: https://docs.crowdsec.net/u/getting_started/installation/opnsense/
- Plugin settings and testing: https://docs.crowdsec.net/docs/getting_started/install_crowdsec_opnsense/
- Blocklists on OPNsense: https://docs.crowdsec.net/u/integrations/opnsense/
Happy to answer questions in the comments, and I'll pull in one of our engineers for the tricky ones.