Skip to main content
Version: v1.3.4

Troubleshooting Guide

How to list banned IPs

cscli decisions list

How to unban an IP

cscli decisions delete -i x.x.x.x

I want to prevent Crowdsec from banning a given IP

Inspired from the existing default whitelist for private IP addresses, you can craft your own (and drop it in /etc/crowdsec/parsers/s01-parse/mywhitelist.yaml) :

name: crowdsecurity/mywhitelists
description: "Whitelist events from private ipv4 addresses"
reason: "private ipv4/ipv6 ip/ranges"
- ""
- "::1"
- ""
- ""
- ""

While you don't need to modify these file with a simple installation, you need to edit them when you want to use CrowdSec in a multi machine setup.

  • For the CrowdSec Local API Server listen URL:

This information is stored in /etc/crowdsec/config.yaml in the api.server.listen_uri option.

More information here.

  • For the CrowdSec Agent client API:

The URL of the local API that the CrowdSec agent should communicate with is stored in /etc/crowdsec/local_api_credentials.yaml.

You can edit the url option according to your local API URL.

  • For the bouncers:

Each bouncer has its own configuration file, which is located in the /etc/crowdsec/bouncers/ folder.

They all have an api_url option to set the local API URL.

My bouncer doesn't start/work (common causes)

  1. Bouncer cannot connect to the local API
  • error message might look like:
level=error msg="auth-api: auth with api key failed return nil response, error: dial tcp connect: connection refused"
  • solution verify that the local API runs on the configured IP
  1. Bouncer cannot authenticate to the local API
  • error message might look like:
time="19-04-2022 15:43:07" level=error msg="API error: access forbidden"

My scenario is triggered with less logs than the scenario capacity

During the installation, the CrowdSec Wizard is ran, which detects the basic logs files to add in the acquisition configuration. If you re-run the script after the installation and you have common log files, they might be set up multiple times in your acquisition configuration. This means that CrowdSec will read each logs line as many time as you have the logs file configured in your acquisition configuration.

Scenario XXX keeps triggering, it's a false positive

To avoid a specific scenario that is bothering you, you have several options:

  • set it in simulation mode: you will see the alerts, but no decisions will be applied
  • purely remove the scenario: it will be completely disabled

I need to whitelist a specific event pattern

For example, I don't want to disable the simulation mode for a scenario nor remove it, but it triggers false positives when i access the admin panel of my website.

I can then whitelist the admin panel URLs and so keep the scenario:

name: crowdsecurity/my_whitelist
description: "Whitelist URL starting with '/admin' "
reason: "False positive on admin panel"
- "evt.Parsed.request startsWith '/admin'"

I receive few IPs in the community-blocklist

The community-blocklist that you receive is based on your installed scenarios, if they are neither tainted nor custom.

For example, if your crowdsecurity/ssh-bf scenario is tainted, you will not receive IPs concerning this scenario in the community-blocklist.

I want to set a custom/tainted scenario in simulation mode

If you want to set a custom/tainted scenario in simulation mode, you need to provide the scenario's filename instead of its name.

For example, i have a scenario called crowdsecurity/my-custom-scenario located in /etc/crowdsec/scenarios/my_custom_scenario.yaml.

To enable the simulation mode for this scenario, i need to run:

sudo cscli simulation enable my_custom_scenario.yaml

Why are XXX logs not parsed in cscli metrics ?

If you are facing logs that doesn't seem to be parsed correctly, please use cscli explain :

# cscli explain --log "May 16 07:50:30 sd-126005 sshd[10041]: Invalid user git from port 47738" --type syslog
line: May 16 07:50:30 sd-126005 sshd[10041]: Invalid user git from port 47738
├ s00-raw
| └ 🟢 crowdsecurity/syslog-logs (first_parser)
├ s01-parse
| ├ 🔴 crowdsecurity/iptables-logs
| ├ 🔴 crowdsecurity/mysql-logs
| ├ 🔴 crowdsecurity/nginx-logs
| └ 🟢 crowdsecurity/sshd-logs (+6 ~1)
├ s02-enrich
| ├ 🟢 crowdsecurity/dateparse-enrich (+2 ~1)
| ├ 🟢 crowdsecurity/geoip-enrich (+13)
| ├ 🔴 crowdsecurity/http-logs
| └ 🟢 crowdsecurity/whitelists (unchanged)
├-------- parser success 🟢
├ Scenarios
├ 🟢 crowdsecurity/ssh-bf
├ 🟢 crowdsecurity/ssh-bf_user-enum
├ 🟢 crowdsecurity/ssh-slow-bf
└ 🟢 crowdsecurity/ssh-slow-bf_user-enum

This command will allow you to see each parser behaviour.


Do not use cscli explain on big log files, as this command will buffer a lot of information in memory to achieve this. If you want to check crowdsec's behaviour on big log files, please see replay mode.

Is scenario XXX working on my logs ?

You can replay old logs with replay mode, which will allow you to see which scenarios would have been triggered. If no scenario seem to trigger, you can have a closer look at potential parsing errors with cscli explain.

I want to add collection XXX : how to add log files, and how to test if it works ?

When adding a collection to your setup, the hub will usually specify log files to add. Those lines need to be added in your acquisition file (/etc/crowdsec/acquis.yaml or /etc/crowdsec/acquis.d/myfile.yaml). After restart, cscli metrics will allow you to see if lines are read and/or parsed.