.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
There are two ways to get CrowdSec's threat intel onto a perimeter firewall. You can install the full plugin, which puts a Security Engine with its Log Processor, LAPI (Local API) and firewall bouncer on the box itself. Or you can skip the agent entirely and have the firewall pull a plain list of malicious IPs from CrowdSec's blocklist integration endpoint into a native alias. This guide covers the second route, on OPNsense and pfSense both, because it's the one people keep overcomplicating.
I've grown fond of the agentless approach for small or busy firewalls. A URL Table alias is a mechanism both platforms have shipped for years, and there's nothing to upgrade on the device. When something breaks you debug an HTTP fetch rather than a service chain. The trade-off is real though: without an engine, the firewall detects nothing on its own and reports nothing back. If you're new to how the wider system fits together, the what is CrowdSec primer covers the moving parts before you commit to either route.
Create the integration in the Console Blocklists tab
The integration endpoint is a hosted URL that serves the merged content of every blocklist you attach to it, one IP per line. Setting one up takes about two minutes in the CrowdSec Console:
- Sign in at app.crowdsec.net and open the Blocklists section, then the Integrations tab.
- Create a new integration and pick the firewall type. The Console shows OPNsense and pfSense cards with tailored instructions, though the output format is identical plain text.
- Copy the generated credentials and endpoint URL. It has this shape:
https://admin.api.crowdsec.net/v1/integrations/YOUR_INTEGRATION_ID/contentAuthentication is HTTP basic auth, and since firewall alias fetchers rarely have a separate credentials field, you embed them in the URL directly:
https://USERNAME:[email protected]/v1/integrations/YOUR_INTEGRATION_ID/contentThen attach blocklists to the integration from the catalog. On the free Community tier you can subscribe to up to three curated lists, and the Console blocklists documentation notes that content refreshes about every two hours, so a fresh subscription can take that long to show up in what the endpoint serves. Treat the credentials like any other secret. They're sitting in a URL your firewall config now contains, which also means they end up in config backups.
Build the URL Table alias in OPNsense
- Go to Firewall > Aliases and add a new alias.
- Set the type to URL Table (IPs). This matters; a plain URL alias won't refresh on a schedule.
- Name it something you'll recognize in rules, like
crowdsec_blocklist, and paste the basic auth URL as the content. - Set the refresh interval to match the roughly two hour server-side cycle. Pulling every hour just fetches the same content twice.
- Save and apply.
Now the rule, and this is where the classic mistake lives. Create a block rule on the WAN interface with the alias as the source, and drag it above anything permissive. OPNsense evaluates rules first-match, so a block rule sitting below a broad allow rule is decoration. I've reviewed more than one config where the CrowdSec alias was populated, the rule was green and traffic from listed IPs sailed through anyway because a port forward matched first. Enable logging on the rule while you're at it; those log lines are the only visibility this setup gives you.
pfSense URL Table alias setup
The pfSense side is nearly identical. Under Firewall > Aliases, use the URLs tab, add an alias of type URL Table (IPs) and paste the same credential-embedded URL. pfSense expresses the update frequency in days, so the pulled copy lags the two hour server refresh more than OPNsense's does. For a blocklist of known-bad reputation IPs that lag is acceptable; these aren't decisions that expire in minutes. Reference the alias from a WAN block rule, again above your allow rules, and you're done with the plumbing.
Verify the alias is populated
An empty alias fails silently, so check it before trusting it. On OPNsense, Firewall > Diagnostics > Aliases shows the resolved contents. On pfSense it's Diagnostics > Tables, where you pick the alias name from the dropdown. From a shell on either platform, the pf table behind the alias answers directly:
pfctl -t crowdsec_blocklist -T show | head
pfctl -t crowdsec_blocklist -T show | wc -lA working integration with a few lists attached returns tens of thousands of entries. Zero entries means the fetch failed: wrong credentials, a typo in the integration ID, a refresh that hasn't run yet or a TLS-inspecting proxy mangling the pull. Test the URL with curl from the firewall to separate an auth problem from an alias problem. One thing the docs flag for very large setups: uncompressed pulls truncate around 300,000 entries due to a response size cap, with pagination and compression as the escape hatches. On the free tier's three lists you won't get anywhere near it.
Pick blocklists without flooding the firewall
The catalog makes over-subscribing easy, and I'd argue restraint wins here. CrowdSec's own curated lists lean on reputation data aggregated from the community network, while the free third party blocklists bring in outside feeds like Firehol-sourced material. Each list has a description and a size in the catalog. Read both. A home firewall gains nothing from blocking scanners that only target enterprise VPN gear, and every extra list grows the table and the odds of a false positive knocking out something you care about. Start with a general reputation list plus one matched to what you expose, then let the block rule's logs tell you what a third would add. If a legitimate address does land in a list you subscribe to, allowlisting works at the Console level; the mechanics are in the CrowdSec allowlist guide for OPNsense.
Run the integration next to a local Security Engine
The two routes coexist fine, and plenty of setups end up with both: an engine somewhere doing real detection and the firewall pulling the blocklist alias as a cheap perimeter layer. Expect overlap. An engine already receives the community blocklist through the CAPI (Central API), so some IPs will be blocked twice, once by the alias at the edge and once by whichever bouncer the engine feeds. Nothing breaks; pf just never consults the second layer for a packet the first one dropped. What the alias route can't replace is detection from your own logs, so the servers behind that firewall still want an engine of their own. That's exactly the setup where I keep the heavy parts off the firewall: a CrowdSec install on a Debian box behind it, or on the VPS side, where LumaDock's CrowdSec templates deploy Ubuntu 24.04 with CrowdSec already wired to nginx or Apache during ordering, so the web tier arrives protected without any of this manual assembly.
Give the setup a week, then read the block rule's logs. The moment you see the alias quietly dropping the same scanner subnets your server logs used to complain about is the moment this stops feeling like an academic exercise.
