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

📡 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 | grep crowdsecurity/http-generic-test

Notes:

  • Requests from private IP addresses won't trigger alerts (private IPs are whitelisted by default).
    • You can also test via a browser if easier, especially from another device.
  • 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 | grep 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, 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 | grep 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. This is handled by the acquisition configuration, 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 in the 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.
  • On Docker, Kubernetes, or custom setups, you may need to install them manually.

🔍 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, like:
  1. Follow the installation instructions on the collection’s page, including any required acquisition setup.

⚠️ Log format mismatch​

  • If your logs don’t follow the expected format (e.g., they’ve been customized), CrowdSec might not parse them properly.
  • You can find more information on how to create your own parsers in the CrowdSec 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, you can start it manually: 

sudo systemctl start crowdsec

  • 💡 make sure it will be up after restart, activate the service

If the service fails to start, you can check the logs for more information: For linux systems, the logs are typically located in /var/log/crowdsec.log. 

less /var/log/crowdsec.log

If you got an error trying to run the cscli or trying to start crowdsec. Common reasons the service might fail:

  • Misconfiguration in the config.yaml file.
    • Port conflicts with other services. By default, CrowdSec uses port 8080 for the Local API (LAPI) and port 6060 for the Local API metrics.
    • The port configuration can be setup in config.yaml file or by setting the environment variables depending on your implementation
  • Insufficient permissions to access the log files or directories.
  • Acquisition files format errors.

Other more low level reasons might be:

  • cscli doesn't exist in your $PATH hence can't be called from anywhere.
  • You might not have sudo permissions to run the command or privileges on the config.yaml file used when running cscli or crowdsec.

🔌 CrowdSec Connectivity checks​

Is your Security Engine receiving community blocklists?​

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

The most direct way to verify connectivity is to see if your instance has already received decisions from the Community Blocklist.

1️⃣ List decisions coming from CAPI 

sudo cscli decisions list --origin CAPI

☑️ If you see decisions, you're connected and receiving threat intel.

Notes:

  • On a fresh install, it might take a few minutes before any decisions appear.
  • Restarting the CrowdSec service will force it to perform a first pull.

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

Let’s verify your CAPI connection step-by-step.

Check CAPI status: 

sudo cscli capi status

Should show:

  • INFO You can successfully interact with Central API (CAPI)
  • Along with information about the connectivity config file path and if your Security engine is enrolled in CrowdSec console.

Common issues include:

  • Missing online_api_credentials.yaml in your CrowdSec config directory
    • If they don't exist, you can create them by running the command: 
      sudo cscli capi register
  • Firewall rules blocking outbound connections to the CrowdSec Central API (api.crowdsec.net)
  • DNS resolution issues.
  • Proxy server configuration.
  • Connectivity issues within Docker containers.

✋🏻 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).

danger

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 tick in the valid column indicating that the bouncer is properly registered and connected to your Security Engine.

  • a recent Last API pull datasources

  • If your bouncer is not valid or not pulling it might be an issue with the bouncer configuration authentication in its configuration file.

  • If you don't see your bouncer listed, you should add it

  • You can try to re-register your bouncer with the command: 

    sudo cscli bouncers add

    • Copy the provided token and paste it in your bouncer configuration file.
    • Then restart the bouncer service.

  • If your bouncer is on a different machine, ensure it can reach the Security Engine Local API.

  • If you are using a bouncer in a container, ensure that the container can reach the Security Engine Local API.

💬 Your feedback is important!​

Help us improve this health check guide!
Give us feedback via this form: 📝 Health Check Feedback Form ↗️

📨 Open an issue on GitHub ↗️ or
🗣️ Join the conversation on Discord ↗️

CrowdSec ConsoleCrowdSec Console