Skip to main content

CrowdSec Security Engine Setup Health-Check

Health Check Version: 0.2.0

Welcome to the interactive Health-Check of your CrowdSec setup. We'll guide you through a series of tests to ensure that your Security Stack is fully functional and ready to protect your services: Detecting, Threat Sharing and Remediating. This guide covers cases of protecting common services such as web servers (HTTP) and SSH.

We'll first test the final functionality of each component (top-down approach) before diving into detailed troubleshooting if issues arise.

This health check is divided into three main sections:

  • 📡 Detection: Ensuring CrowdSec properly detects threats targeting your services.
  • 🔗 Connectivity: Verifying communication with the CrowdSec network to receive the community blocklist.
  • 🛡️ Protection: Confirming that your bouncers automatically block threats detected by CrowdSec

Help us improve this health check guide by sharing your experience: 📝 Health Check Feedback Form ↗️

📡 Detection checks​

Trigger CrowdSec's test scenarios​

Let's use CrowdSec's built-in dummy scenarios (HTTP and Linux) to safely verify your Security Engine detects threats, without risking accidental self-blocking.

🌐 HTTP detection test

We'll trigger the dummy scenario crowdsecurity/http-generic-test by accessing a probe path on your web server.

1️⃣ Access your service URL with this path: /crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl 

curl -I https://<your-service-url>/crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl

2️⃣ Confirm the alert has triggered for the scenario crowdsecurity/http-generic-test

sudo cscli alerts list -s crowdsecurity/http-generic-test
ss

Notes:

  • ⚠️ Important: Requests from private IP addresses won't trigger alerts (private IPs are whitelisted by default).
    • If testing from localhost or your internal network (192.168.x.x, 10.x.x.x, 172.16.x.x), the test will fail.
    • Solution: Test from an external device with a public IP address, or test via a browser from your phone using mobile data.
  • This scenario can be triggered again only after a 5-minutes delay.
🔐 SSH detection test

We'll trigger the dummy scenario crowdsecurity/ssh-generic-test by attempting an SSH login with a specific username.

1️⃣ Attempt SSH login using this username: crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl. 

ssh crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl@<your-server-ip>

2️⃣ Confirm the alert has triggered for the scenario crowdsecurity/ssh-generic-test

sudo cscli alerts list -s crowdsecurity/ssh-generic-test

Notes:

  • This scenario can only be triggered again after a 5-minutes delay.
🛡️ AppSec detection test - CrowdSec WAF

If you've enabled an AppSec-capable bouncer with CrowdSec WAF with the Virtual Patching collection, you can trigger the crowdsecurity/appsec-generic-test dummy scenario.
It would have triggered along with the HTTP detection test, but it is worth mentioning here as well.

We'll trigger the dummy scenario crowdsecurity/appsec-generic-test by accessing a probe path on your web server.

1️⃣ Access your service URL with this path: /crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl 

curl -I https://<your-service-url>/crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl

2️⃣ Confirm the alert has triggered for the scenario crowdsecurity/appsec-generic-test

sudo cscli alerts list -s crowdsecurity/appsec-generic-test

Notes:

  • This scenario can only be triggered again after a 1-minute delay.

Were all the tests successful ?​

Were all the tests related to your setup successful? 👍 If so, you can proceed to the next phase of the health check: Connectivity checks.

🛠️ If not, check the troubleshooting section below.

🐞 Detection Troubleshooting

No alert triggered? Let's find out why.

If you installed CrowdSec on the same host as the service you're protecting, it should have auto-detected it and installed the right collections of parsers and scenarios. However, if you're using custom log paths, unusual log formats, or running in Docker/Kubernetes, you might need to configure some things manually.

This section will help you pinpoint the issue and walk you through how to fix it.

📄 Are your logs being properly read and parsed?

CrowdSec needs to know what logs to read and how to interpret them.
This is handled by the acquisition configuration (log sources) and parsing (how to read them). Multiple log sources can be defined in the acquisition(s) configuration files and they support diverse datasources (files, syslog, etc.). For more details you can refer to the datasources documentation.

We'll look at the security engine metrics to see if logs are being read and if what's read is parsed correctly. We'll do that using the cscli metrics command:

sudo cscli metrics show acquisition parsers

Under Acquisition Metrics you should see:

  • The source name of the log files or streams that have been read and the number of lines read and parsed for each of them.
    • If you don't see any sources or some you have configured are missing, it means that the acquisition configuration is not properly set up.
    • A non zero number of "Lines parsed" is expected for each source, proving that the appropriate parser was found and used.

Under The Parsers Metrics you have the details of the parsers used.

🚨 If this check fails, don’t worry -- the results will point you to the right area to troubleshoot:

🐞 If this command fails entirely, go to the CrowdSec Service Troubleshooting section

🐞 If your acquisition sources don't appear, check the Acquisition Troubleshooting section

🐞 If parsing fails, check the Collection Troubleshooting section**

📥 Acquisition Troubleshooting -- Are your logs properly declared as datasources

CrowdSec needs to know where to read your logs. The configuration varies by deployment method:

The acquisition configuration is usually found in acquis.yaml or in files under acquis.d/ inside the CrowdSec config directory. On Debian-like OS it is typically located in /etc/crowdsec/.

To troubleshoot:

  • The detailed doc about the acquisition configuration can be found here.
  • Check your acquisition files exist and that the datasources are properly setup.
  • 💡 Hint:
  • Make sure that the type declared matches the parser expected to be used: nginx, apache, syslog, etc.
📦 Collection Troubleshooting -- Are the right parsers and scenarios installed?

CrowdSec, via its Hub ↗️ uses collections to package correct parsers and detection scenarios for your services.

On regular host installations, CrowdSec usually detects your services (like nginx or ssh) and installs the appropriate collections automatically.

🔍 To check what's currently installed:

sudo cscli collections list

You can also list individual parsers and scenarios with:

sudo cscli parsers list
sudo cscli scenarios list
  • Look for entries related to your service (e.g., nginx, apache, ssh).
  • If they're listed, the right collection is likely installed.

📥 Install missing collections:

  1. Visit the CrowdSec Hub ↗️ and search for a collection matching your service
  2. Install with: 
    sudo cscli collections install crowdsecurity/nginx
    sudo systemctl reload crowdsec

⚠️ Log format mismatch:

  • If your logs don't follow the expected format (e.g., they've been customized), CrowdSec might not parse them properly.
  • Check which log format the Hub parser expects:
    • Each parser on the Hub documents the expected log format. For example:
    • Compare your actual log format with the expected format to identify mismatches
  • For custom log formats:
    • Example: If you use a custom NGINX log format like log_format custom '$remote_addr - $request - $status';, you'll need a custom parser
    • Use the CrowdSec Playground ↗️ to test and develop your parsers interactively
    • The playground lets you test GROK patterns, parsers, and scenarios in real-time before deploying them
    • Full guide on creating parsers: CrowdSec Parser Documentation
⚙️ CrowdSec Service Troubleshooting -- is the CrowdSec service running?

Let's check if the CrowdSec service is active:

sudo systemctl status crowdsec
  • ☑️ You should see: "active (running)"

If the service is not running:

sudo systemctl start crowdsec
sudo systemctl enable crowdsec  # Ensure it starts on boot

Check logs for errors:

# Start by checking crowdsec logs
less /var/log/crowdsec.log

# Eventually check systemd journal logs
sudo journalctl -u crowdsec -n 50

Common issues:

  • Misconfiguration in /etc/crowdsec/config.yaml
  • Port conflicts (default: 8080 for LAPI, 6060 for metrics)
  • Insufficient permissions to access log files
  • Acquisition files format errors

🔌 CrowdSec Connectivity checks​

Check CAPI status​

Let's confirm that your Security Engine can communicate with the CrowdSec Central API (CAPI). This connection allows you to:

  • Receive Community Blocklists -- curated IPs flagged as malicious by the global CrowdSec network.
  • Receive additional Blocklists of your choice among the ones available to you.
  • Contribute back -- sharing detected Malicious IPs triggering installed scenarios.
🔌 CrowdSec Central API connectivity test

Check your CAPI connection status:

sudo cscli capi status

☑️ You should see: INFO You can successfully interact with Central API (CAPI)

Notes:

  • On a fresh install, credentials might need to be registered (see troubleshooting below).
  • The output also shows information about the connectivity config file path and enrollment status with CrowdSec Console.

Were all the tests successful ?​

Were all the tests related to your setup successful? 👍 If so, you can proceed to the next phase of the health check: Remediation Check

🛠️ If not, check the troubleshooting section below.

🐞 Connectivity Troubleshooting

If the CAPI status check fails, here are the most common issues and solutions:

Common issues:

  • Missing credentials: If online_api_credentials.yaml is missing: 
    sudo cscli capi register
    sudo systemctl reload crowdsec
  • Firewall blocking: Ensure outbound network access (API endpoints, blocklists, etc.). See Network Management for full requirements
  • DNS issues: Verify DNS resolution works: 
    nslookup api.crowdsec.net
  • Proxy configuration: If behind a proxy, configure in /etc/crowdsec/config.yaml

✋🏻 Remediation checks​

Validate Blocks or Captchas​

Now that detection and connectivity are working, let’s verify that your bouncers are correctly applying remediation on malicious IPs.

Prerequisite:
To apply remediation with CrowdSec, you’ll need a bouncer — available for firewalls, web servers, reverse proxies, CDNs, cloud WAFs, edge appliances, and more.

✋🏻 Bouncer Remediation test

This test involves manually creating a decision against a public IP of one of your devices for a very short period (1 minute).

BE CAREFUL -- Risk of Self-Lockout
This procedure will temporarily block your access to the services protected by your bouncer.
Make sure to properly follow the instructions to set the TTL to a low expiration time (1 minute). OR do it from a device with a different public IP address than the client you're using to setup CrowdSec.

1️⃣ Find your public IP: 

curl api.ipify.org

2️⃣ Add a ban decision for your IP (valid for 1 minute):

sudo cscli decisions add --ip <your-public-ip> --duration 1m --reason "CrowdSec remediation test"

⏳ Wait a few seconds to ensure the decision is processed by the bouncer.
3️⃣ Try accessing your service (e.g. website, API). from the same public IP address. ➡️ You should be blocked by the bouncer. returning a forbidden response (HTTP 403) or a captcha challenge.

4️⃣ Wait for 1 minute, then check the decisions list to see if the decision has been removed

Were all the tests successful ?​

If you were successfully blocked, congratulations! Your remediation setup is working correctly. 🎉

You might want to continue to the next recommended steps:

  • Enroll your Security Engine to the CrowdSec Console
  • Then subscribe to more blocklists to benefit from additional proactive prevention
🐞 Remediation Troubleshooting

Before diving into troubleshooting, remember that a remediation components (AKA bouncer) is a separate component that connects to the Security Engine and regularly pulls decisions (like bans or captchas) to apply them at its level (firewall, web server, etc.). If remediation isn’t working, it’s often due to issues in this communication loop.
You can find more information about bouncers in the Bouncers documentation. The full list of available bouncers is available on the CrowdSec Hub ↗️.

Is your Bouncer Installed and Connected to your Security engine

Check bouncers linked to your Security Engine:

sudo cscli bouncers list

You should see:

  • The bouncer name
  • A ✓ in the valid column indicating proper registration
  • A recent Last API pull timestamp

Common issues:

  • Bouncer not valid or not pulling: Check authentication in bouncer config file

  • Bouncer not listed: Register it:

    sudo cscli bouncers add my-bouncer-name

    Copy the token and add it to your bouncer's configuration, then restart the bouncer service.

  • Bouncer on different machine: Ensure it can reach the LAPI endpoint (default: http://crowdsec-server:8080)

  • Firewall blocking: Verify port 8080 is accessible from bouncer machine

💬 Get Help & Give Feedback​