Whitelists

Whitelists tell CrowdSec to ignore certain events or IP addresses. This is useful if you have a static IP you trust, or a service that could generate false triggers (for example, a site that loads many thumbnails, images, or fonts).

By default, CrowdSec whitelists private LAN IP addresses via this parser. You can add additional IPs or events.

This guide covers how to create whitelists and apply them to your CrowdSec instance.

We cannot cover every use case. For advanced scenarios, see the detailed whitelist documentation.

An "event" is a log line being processed by CrowdSec, or an "overflow" from a scenario.

Whitelist Types

There are three whitelist types in CrowdSec:

• Parser (at enrich stage)
• Postoverflow
• AllowLists

It is important to know where these are applied in the pipeline, as it affects behavior and context.

Parser

Parser-based whitelists are applied while the event is being enriched. They prevent the log line from reaching the scenario stage, which saves resources.

Typically these files are located here, depending on your OS:

• Linux: /etc/crowdsec/parsers/s02-enrich/
• Freebsd: /usr/local/etc/crowdsec/parsers/s02-enrich/
• Windows: c:/programdata/crowdsec/config/parsers/s02-enrich/

Postoverflow

Postoverflow whitelists are applied after a scenario triggers. Use this stage for expensive checks, such as DNS lookups.

A whitelist is "expensive" if it requires a network call or lookup that could slow event processing.

Typically these files are located here, depending on your OS:

• Linux: /etc/crowdsec/postoverflows/s01-whitelist/
• Freebsd: /usr/local/etc/crowdsec/postoverflows/s01-whitelist/
• Windows: c:/programdata/crowdsec/config/postoverflows/s01-whitelist/

Postoverflow whitelist folders do not exist by default, so you must create them manually.

AllowLists

AllowLists were added in version 1.6.8. Ensure you are on this version to follow these steps.

AllowLists let you centrally manage whitelisted IP addresses and CIDR ranges using cscli. This is the preferred method because AllowLists integrate with major components, including:

• AppSec component
• cscli
• Scenario overflows
• Console Blocklists

Which one should I use?

If you already know the IP or CIDR range to whitelist, use cscli AllowLists. This excludes the IP across all CrowdSec components.

If you need to whitelist a specific event pattern (such as a URI), use a Parser whitelist. For advanced logic like DNS or reverse DNS lookups, use a Postoverflow whitelist.

To summarize:

• Use AllowLists for IP and CIDR ranges.
• Enricher whitelists apply to every event (each log line).
• Postoverflow whitelists apply only to triggered scenarios.

Should I create a whitelist?

When configuring CrowdSec for the first time, you may want to create a whitelist for the following reasons:

• You have a static IP address that you want to ensure is never banned.
• You have a service that could generate a lot of false triggers.

An example is a web application that loads many resources such as thumbnails, images, or fonts.

If you are unsure if you need a whitelist, you can monitor the logs and see if there are any false positives that you want to prevent.

If a decision is made against your IP and you use remediation components like iptables or nftables, you may be blocked from all services on that server.

In our enterprise offering, Decision Management lets you manage decisions via the Console.

Creating your first whitelist

Depending on your criteria, you may want to create a whitelist for a specific IP address, a range of IP addresses, or a specific event pattern.

We provide examples for each scenario.

The example location shown is for Linux. Adjust the path based on your OS as noted above.

Static IP address

AllowLists

You can create a new AllowList using cscli:

cscli allowlist create my_allowlist -d 'created from the docs'

This command creates an empty AllowList named my_allowlist. You can then add IP addresses and CIDR ranges to it. There's no need to specify the type—AllowLists support both. The -d flag lets you add a description, which is useful when managing multiple AllowLists to help identify their purpose.

To add entries to the AllowList, provide the name and the value you want to allow:

Single IP:

cscli allowlist add my_allowlist 192.168.1.1

CIDR range:

cscli allowlist add my_allowlist 192.168.1.0/24

A key benefit of using AllowLists is that changes take effect immediately—no need to restart CrowdSec.

To view the contents of an AllowList, run:

cscli allowlist inspect my_allowlist

Example output:

──────────────────────────────────────────────
 Allowlist: my_allowlist
──────────────────────────────────────────────
 Name                my_allowlist
 Description         created from the docs
 Created at          2025-05-13T14:10:12.668Z
 Updated at          2025-05-13T14:12:30.177Z
 Managed by Console  no
──────────────────────────────────────────────

───────────────────────────────────────────────────────────────
 Value           Comment  Expiration  Created at
───────────────────────────────────────────────────────────────
 192.168.1.0/24           never       2025-05-13T14:10:12.668Z
───────────────────────────────────────────────────────────────

You can see the full list of allowlist command via cscli here.

Enricher file

If you want to whitelist a specific IP address for example 192.168.1.1, you can create a file in the Enricher folder with the following content:

/etc/crowdsec/parsers/s02-enrich/01-my-whitelist.yaml

name: my/whitelist ## Must be unique
description: "Whitelist events from my IP"
whitelist:
  reason: "My IP"
  ip: 
    - "192.168.1.1"

Once you have created the file you will need to restart the CrowdSec service for the changes to take effect.

Restart CrowdSec

sudo systemctl restart crowdsec

If you want to whitelist a range of IP addresses, for example 192.168.1.0/24, create a file in the Enricher folder with the following content:

/etc/crowdsec/parsers/s02-enrich/01-my-whitelist.yaml

name: my/whitelist ## Must be unqiue
description: "Whitelist events from my IP range"
whitelist:
  reason: "My IP range"
  cidr: 
    - "192.168.1.0/24"

Once you have created the file you will need to restart the CrowdSec service for the changes to take effect.

Restart CrowdSec

sudo systemctl restart crowdsec

Expression pattern

If you want to whitelist a specific event pattern, for example http log line that is a healthcheck so typically a GET request to /health you can create a file in the Enricher folder with the following content:

/etc/crowdsec/parsers/s02-enrich/01-my-whitelist.yaml

name: my/whitelist ## Must be unqiue
description: "Whitelist events with GET /health"
filter: "evt.Meta.service == 'http' && evt.Meta.log_type in ['http_access-log', 'http_error-log']"
whitelist:
  reason: "GET /health"
  expression: 
    - "evt.Meta.http_verb == 'GET' && evt.Meta.http_path == '/health'"

This will discard any event that has a http_verb of GET and a http_path of /health no matter the origin.

Once you have created the file you will need to restart the CrowdSec service for the changes to take effect.

Restart CrowdSec

sudo systemctl restart crowdsec

Expression whitelists are very powerful and can be used to whitelist based on any field in the event. You can find a more detailed version of the expression guide here which will showcase how you can find which fields are available to you based on the log line you are processing.

Dynamic IP address

If you want to whitelist an IP address that is not static, you need to use a external DDNS service to resolve the IP address and then use the Postoverflow whitelist to whitelist the resolved IP address.

This is a postoverflow whitelist as it requires a network call to resolve the IP address.

/etc/crowdsec/postoverflows/s01-whitelist/01-my-whitelist.yaml

name: my/whitelist ## Must be unqiue
description: "Whitelist events from my dynamic IP"
whitelist:
  reason: "My dynamic IP"
  expression:
      - evt.Overflow.Alert.Source.IP in LookupHost("foo.com")

Please read the LookupHost function documentation before altering the current example.

Testing your whitelist

Once you have created your whitelist, you can test it by running a log line through the parser and checking the output.

In the example we using Nginx logs, you will need to adjust the testing to point towards your log file.

Test an IP/Range whitelist

grep 192.168.1.1 /var/log/nginx/access.log | tail -n 1 | sudo cscli explain -f- --type nginx

Test an Expression whitelist

grep /health /var/log/nginx/access.log | tail -n 1 | sudo cscli explain -f- --type nginx

Example Output

line: 192.168.1.1 - - [05/Sep/2024:18:07:25 +0000] "GET /health? HTTP/2.0" 200 42 "-" "curl/7.68.0"
├ s00-raw
|       └ 🟢 crowdsecurity/non-syslog (+5 ~8)
├ s01-parse
|       └ 🟢 crowdsecurity/nginx-logs (+23 ~2)
├ s02-enrich
|       ├ 🟢 crowdsecurity/dateparse-enrich (+2 ~2)
|       ├ 🟢 crowdsecurity/geoip-enrich (+13)
|       ├ 🟢 crowdsecurity/http-logs (+8 ~1)
|       └ 🟢 my/whitelist (~2 [whitelisted])
└-------- parser success, ignored by whitelist (<Reason will vary here>) 🟢

Currently postoverflows are not supported by cscli explain so you will need to check the logs to see if the whitelist is working.

Example logs line you will see:

Example logs

time="07-07-2020 17:11:09" level=info msg="Ban for 192.168.1.1 whitelisted, reason [My dynamic IP]" id=cold-sunset name=my/whitelist stage=s01

Whitelisted but there still a decision?

Whitelisting an IP address or event will prevent the events from triggering new decisions, however, any existing decisions will still be applied.

You must manually remove the decisions by running:

Remove decisions

sudo cscli decisions delete --ip 192.168.1.1

Next steps

If you are still looking for examples on how to create a whitelist, you can find more detailed documentation here.

If you have created your first whitelist, tested it and happy to continue then click here.