Introduction
If you’ve recently set up CrowdSec on your server and found yourself staring at unfamiliar terms like “bouncer,” “scenario,” or “hub,” you’re not alone. CrowdSec has its own vocabulary and a powerful CLI that can feel overwhelming at first. This guide breaks down the lingo in plain English and walks you through the most useful commands for monitoring blocks, checking decisions, reviewing alerts, and keeping your setup healthy.
Whether you’re a seasoned sysadmin or just getting started with open-source security tools, this post has you covered.
Part 1: CrowdSec Lingo — The Key Terms You Need to Know
Agent
The core CrowdSec service running on your machine. It reads log files, runs them through parsers and scenarios, and generates alerts and decisions when it detects bad behavior. Think of it as the brain of the operation.
Hub
The CrowdSec community hub is an online repository of shared parsers, scenarios, collections, and postoverflows. When you run cscli hub update, you’re syncing with this repository to get the latest detection content.
Collection
A bundle of parsers and scenarios grouped by technology. For example, the crowdsecurity/nginx collection includes everything CrowdSec needs to understand and react to Nginx logs. Collections are the easiest way to get started — install one and you get everything relevant for that service.
Parser
A parser tells CrowdSec how to read a specific log format. For example, the Nginx parser knows how to break apart an Nginx access log line into structured fields (IP, URL, status code, etc.) that CrowdSec can then analyze.
Scenario
A scenario is a detection rule. It watches for patterns in parsed log data and triggers an alert when something suspicious matches — for example, too many failed logins from the same IP within a short window.
Alert
An alert is generated when a scenario is triggered. It records what happened, who did it (usually an IP address), and which scenario caught it. Alerts are logged and can be reviewed with cscli alerts list.
Decision
A decision is the action taken as a result of an alert — most commonly a ban. Decisions are what your bouncers actually enforce. You can have alerts without active decisions if the scenario doesn’t result in a ban (e.g., simulation mode).
Bouncer
A bouncer is the enforcement layer. It reads CrowdSec’s decisions and acts on them — blocking IPs at the firewall level, refusing connections at the web server, or redirecting users to a CAPTCHA. Common bouncers include:
- cs-firewall-bouncer — blocks IPs using
iptablesornftables - cs-nginx-bouncer — enforces decisions at the Nginx level
- cs-wordpress-bouncer — integrates directly with WordPress
Key distinction: The agent detects. The bouncer enforces. Without a bouncer, CrowdSec just watches and logs.
LAPI (Local API)
The Local API is the communication backbone between the agent, the bouncers, and external tools like cscli. Everything goes through the LAPI. If your bouncer or CLI isn’t working, a LAPI connectivity issue is often the culprit.
cscli
The command-line interface for interacting with CrowdSec. You use it to inspect alerts, manage decisions, install parsers, check bouncer status, and much more.
Postoverflow
A postoverflow is a rule that runs after a scenario fires — typically used to enrich or transform decisions. For example, a postoverflow might convert an IP-specific ban into a wider subnet ban.
Simulation Mode
When simulation mode is enabled for a scenario, CrowdSec logs the alert but does not create a decision. Useful for testing a new scenario without risking false positives on production traffic.
Hub Index / cscli hub update
Running cscli hub update refreshes the local index of available parsers, scenarios, and collections from the CrowdSec Hub. It doesn’t install anything — it just updates the list of what’s available.
Part 2: Essential Commands to Check Blocks, Alerts, and Status
Check What’s Currently Blocked (Decisions)
This is the most important command for day-to-day monitoring:
sudo cscli decisions listShows all active decisions (bans, captchas, etc.), including the IP, the reason, the source (local or community blocklist), and when the ban expires.
Filter by a specific IP:
sudo cscli decisions list --ip 1.2.3.4Filter by range:
sudo cscli decisions list --range 1.2.3.0/24Show only bans from a specific scenario:
sudo cscli decisions list --scenario crowdsecurity/http-bfOutput as JSON (useful for scripting):
sudo cscli decisions list -o jsonView Alerts (Triggered Detections)
Alerts tell you what CrowdSec has detected, even if no ban is currently active:
bash
sudo cscli alerts listShow the last 20 alerts:
sudo cscli alerts list --limit 20Inspect a specific alert by ID:
sudo cscli alerts inspect <alert_id>Filter alerts by IP:
sudo cscli alerts list --ip 1.2.3.4Filter by scenario:
sudo cscli alerts list --scenario crowdsecurity/ssh-bfManually Add or Remove a Decision (Block/Unblock)
Manually ban an IP for 24 hours:
sudo cscli decisions add --ip 1.2.3.4 --duration 24h --reason "manual block"Manually ban an entire subnet:
sudo cscli decisions add --range 1.2.3.0/24 --duration 48h --reason "subnet block"Remove a decision (unban an IP):
sudo cscli decisions delete --ip 1.2.3.4Delete all decisions (use with caution!):
sudo cscli decisions delete --allCheck CrowdSec Agent Status
Overall service status:
sudo systemctl status crowdsecCheck what parsers, scenarios, and collections are installed:
sudo cscli hub listCheck for hub updates (new parsers/scenarios):
sudo cscli hub update
sudo cscli hub upgradeCheck Bouncers
List registered bouncers:
sudo cscli bouncers listThis shows each bouncer, its type, and when it last checked in. If a bouncer is missing or shows an old “last pull” time, it may not be enforcing decisions.
Remove a stale bouncer registration:
sudo cscli bouncers delete <bouncer_name>Check Metrics
Get a snapshot of CrowdSec’s activity — how many events it’s processed, parsed, and triggered:
sudo cscli metricsUseful for verifying that logs are being actively read and that parsers are doing their job.
View CrowdSec Logs
Live log tail:
sudo journalctl -u crowdsec -fView recent logs:
sudo journalctl -u crowdsec --since "1 hour ago"Check the LAPI Connection
Test that the LAPI is reachable:
sudo cscli lapi statusIf this fails, bouncers won’t be able to pull decisions and the CLI won’t work properly. Check that the crowdsec service is running.
Inspect Installed Parsers and Scenarios
List installed parsers:
sudo cscli parsers listList installed scenarios:
sudo cscli scenarios listList installed collections:
sudo cscli collections listInstall a new collection (e.g., for WordPress):
sudo cscli collections install crowdsecurity/wordpressRemove a collection:
sudo cscli collections remove crowdsecurity/wordpressSimulate a Decision Without Banning (Test Mode)
Enable simulation mode for a scenario to see what would be blocked without actually blocking:
sudo cscli simulation enable crowdsecurity/http-bfDisable simulation to go back to live enforcement:
bash
sudo cscli simulation disable crowdsecurity/http-bfPart 3: Quick Reference Cheat Sheet
| Task | Command |
|---|---|
| See all active blocks | sudo cscli decisions list |
| Check if a specific IP is blocked | sudo cscli decisions list --ip 1.2.3.4 |
| View recent alerts | sudo cscli alerts list --limit 20 |
| Manually ban an IP | sudo cscli decisions add --ip 1.2.3.4 --duration 24h |
| Unban an IP | sudo cscli decisions delete --ip 1.2.3.4 |
| Check bouncer status | sudo cscli bouncers list |
| Check LAPI connection | sudo cscli lapi status |
| View what’s installed | sudo cscli hub list |
| Update hub index | sudo cscli hub update |
| Upgrade parsers/scenarios | sudo cscli hub upgrade |
| Live log monitoring | sudo journalctl -u crowdsec -f |
| Activity metrics | sudo cscli metrics |
Bonus Tips
Whitelist your own IP so you never accidentally ban yourself:
Edit /etc/crowdsec/parsers/s02-enrich/whitelists.yaml and add your IP or range under the whitelist section. Reload CrowdSec after:
sudo systemctl reload crowdsecCheck if community blocklists are enabled:
CrowdSec participates in a crowdsourced threat intelligence network. If you’ve enrolled your instance, you benefit from community-reported IPs being blocked proactively. Check enrollment with:
sudo cscli console statusAlways reload after config changes:
sudo systemctl reload crowdsecUse reload rather than restart when possible — it applies changes without dropping the LAPI connection, which keeps bouncers running uninterrupted.
Conclusion
CrowdSec is a powerful tool once you understand how its pieces fit together: the agent detects, scenarios define what’s suspicious, alerts record what was found, decisions are the actions taken, and bouncers do the actual enforcing. Once that mental model clicks, the CLI commands start to make a lot more sense.
Bookmark this post and refer back to it whenever you need a quick reminder. And as always — check your bouncers are actually running, because a CrowdSec install without a bouncer is just a very sophisticated log watcher.