.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
The SSH session freezes mid-keystroke, the OPNsense GUI stops loading and your phone still browses fine because it's on mobile data. That's the tell that the firewall is fine and CrowdSec holds a decision against your address. I've done this to myself twice, once by testing the ssh-bf scenario against my own WAN address and once by fumbling a password five times after a long day. If you're locked out right now, jump straight to the cscli unban below, then come back and build an allowlist so there's no third time.
CrowdSec on OPNsense has three overlapping allowlist mechanisms as of the 1.7.x line (v1.7.8 while I'm writing this): the crowdsecurity/whitelists parser, centralized allowlists managed through cscli and Console-level allowlists. They do different jobs, and picking the wrong one is why the OPNsense forum and r/opnsense keep collecting threads about IPs that stay banned after being whitelisted. This guide covers all of them, plus the unban itself.
Where CrowdSec decisions come from on OPNsense
Get a root shell on the firewall and look at what's actually banned before touching anything:
cscli decisions listThe plugin also lists decisions in the OPNsense admin interface under Services > CrowdSec, which is handy for a quick look, but the shell is faster for surgery. Either way, the column that matters is Origin, because the fix depends on who made the call.
Decisions with origin crowdsec came from your own Log Processor reading logs on the firewall itself, like failed SSH logins or port scans caught in the filter log. These respond to local whitelists and allowlists. Origin CAPI (Central API) is the community blocklist every engine pulls automatically. It never contains private addresses, so a LAN host carrying a CAPI ban means something upstream is mangling the source IP (NAT reflection is my usual suspect). Origin lists means a Console blocklist you subscribed to, and entries from those come back on every refresh until you allowlist the IP centrally or drop the subscription. I've covered feeding those lists to a firewall separately in the guide to CrowdSec blocklists on OPNsense and pfSense.
If cscli decisions list comes back empty while you're clearly blocked, CrowdSec probably isn't your problem and you want the CrowdSec OPNsense troubleshooting checklist instead. Check the rest of your ruleset too. I once blamed CrowdSec for twenty minutes while an unrelated GeoIP rule sat there doing exactly what I'd told it to.
Delete the active decision with cscli
The immediate unban is one command:
cscli decisions delete -i 203.0.113.42Swap in your banned address. For a whole range, use -r 203.0.113.0/24 instead. The firewall bouncer (CrowdSec now calls it a Remediation Component, but everyone still searches for bouncer) streams decisions from the LAPI (Local API) every few seconds, so the pf table entry disappears almost immediately and your session starts responding again. Run cscli decisions list once more to confirm the entry is gone.
Resist cscli decisions delete --all in a panic. It wipes the community and subscribed entries along with the one that bit you, and the engine spends the next refresh pulling thousands of them back anyway.
The crowdsecurity/whitelists parser and private IP ranges
Now the prevention layer. The first mechanism is a parser whitelist, applied while log events are being enriched, before any scenario can trigger. On OPNsense these files live under /usr/local/etc/crowdsec/parsers/s02-enrich/, and since CrowdSec 1.6.3 the crowdsecurity/whitelists parser ships there by default with the RFC1918 private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) already whitelisted. The official OPNsense install docs call this out, and it changes the debugging picture: on a current install, a banned LAN IP almost never comes from a local scenario. Either the install predates 1.6.3 and was upgraded without the parser, or the origin isn't local at all (a stubborn decision can also simply predate the parser). Which is why you check the origin column first.
You can add your own ranges at this layer, but don't edit whitelists.yaml itself. It's a hub-managed file, and the moment you touch it the hub marks it tainted and stops upgrading it. Drop a separate file next to it instead:
cat > /usr/local/etc/crowdsec/parsers/s02-enrich/01-my-whitelist.yaml <<'EOF'
name: my/whitelist
description: "office and monitoring ranges"
whitelist:
reason: "trusted networks"
cidr:
- "203.0.113.0/24"
EOFParser whitelists also take expressions, which is the real reason to use them. You can whitelist an event pattern rather than an address, say a monitoring probe that keeps tripping a scenario, with a line like expression: - "evt.Meta.http_path == '/health'" in place of the cidr block. After any parser change, restart the CrowdSec service from Services > CrowdSec in the GUI. The plugin owns service management on OPNsense, so skip service crowdsec restart at the shell. Parser changes need that restart; the centralized allowlists below don't.
Create a centralized allowlist with cscli allowlists
Since 1.6.8, CrowdSec has proper centralized allowlists, and for plain IPs and CIDR ranges this is the mechanism I'd pick every time. They live in the LAPI database and apply the moment you add an entry, no restart. And they cover decisions from local scenarios and subscribed blocklists alike, so the bouncer never receives a ban for an allowlisted address in the first place.
cscli allowlists create my_lan -d "trusted LAN"
cscli allowlists add my_lan 192.168.20.0/24
cscli allowlists add my_lan 203.0.113.42
cscli allowlists inspect my_lanThe inspect output shows each value with its expiration (never, unless you set one) and a "Managed by Console" flag, which matters in a minute.
One habit worth copying: name allowlists by purpose, mgmt_access or monitoring_probes, rather than one giant catch-all. Six months from now you'll want to expire the monitoring vendor's range without re-auditing everything else in the list.
Why an allowlisted IP stays banned
Here's the trap that fills forum threads. Allowlists and whitelists only prevent new decisions. An existing decision keeps running until it expires or you delete it, so the complete fix for a self-ban is always both halves: allowlist the address, then cscli decisions delete -i the active decision. The CrowdSec whitelist documentation states this explicitly, and it's still the most common reason people conclude that whitelisting "doesn't work" on OPNsense. It works. It just isn't retroactive.
Console allowlists for blocklist content
The third layer sits in the CrowdSec Console. Allowlists created there get pushed to your enrolled engines and show up in cscli allowlists inspect with "Managed by Console: yes". The point is fleet-wide consistency: allowlist your office range once and every enrolled engine honors it, including against the content arriving from subscribed blocklists. For a single OPNsense box the local cscli route does the same job with less clicking. Once you're running an engine on the firewall plus a few more on servers behind it, central management stops being optional in practice.
Allowlist a dynamic home IP
Home connections rotate addresses, which makes a single-IP allowlist rot quietly until the day you're locked out again. Two ways I handle it.
The blunt option is allowlisting your ISP's assignment range. Find your current public address with a what is my IP lookup, run whois on it to see the allocated block, then sanity-check the CIDR with an IPv4 subnet calculator before adding it with cscli allowlists add. Yes, this also allowlists your ISP neighbors. For the management plane of a home firewall that already demands authentication I accept that trade, and I'd rather carry it than be locked out at a bad moment. On anything customer-facing I wouldn't.
The cleaner option is DNS. Give your home connection a DDNS hostname, then either reference it from an OPNsense host alias on a pass rule, or use the postoverflow whitelist the docs describe with the LookupHost() helper, which resolves the hostname each time a scenario overflows. That route costs a DNS lookup per overflow, which on a home firewall is nothing.
Test the whitelist with cscli explain
Don't wait for the next false positive to discover a typo in your whitelist. Feed a real log line through the parser chain and watch where it lands:
grep 203.0.113.42 /var/log/filter/latest.log | tail -n 1 | cscli explain -f- --type LABELReplace LABEL with the type label from the matching acquisition file under /usr/local/etc/crowdsec/acquis.d/. A working parser whitelist shows the s02-enrich stage ending in [whitelisted] and a final verdict of "parser success, ignored by whitelist". Over time cscli metrics also grows a whitelist table with hit counts per whitelist, which is how you eventually spot the one silently eating events it shouldn't.
Keep a second session open while testing
Two habits have saved me more often than any config. First, test with short decisions instead of real attacks. The official docs suggest exactly this:
cscli decisions add -t ban -d 2m -i YOUR_PUBLIC_IPA two minute self-ban proves the whole chain works (decision, bouncer, pf table, your frozen session) and then lets you back in on its own. Second, before any of this, open a spare path in, an SSH session from a different IP or an LTE hotspot at minimum. Established sessions can die the instant a ban lands, so the spare path is the one that does the rescuing. I've written up broader safe CrowdSec rollout habits separately, and they apply double on the device standing between you and your own network.
And once the panic passes, add the allowlist anyway. Future you types passwords just as badly at 1 AM.
