Skip to content

Commit d7dc38a

Browse files
enhance: Add allowlists to post installation whitelist section
1 parent 4eeeb0d commit d7dc38a

File tree

1 file changed

+79
-5
lines changed
  • crowdsec-docs/unversioned/getting_started/post_installation

1 file changed

+79
-5
lines changed

crowdsec-docs/unversioned/getting_started/post_installation/whitelists.mdx

Lines changed: 79 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,10 @@ We use "event" as a term to describe a log line that is currently being processe
2121

2222
## Whitelist Types
2323

24-
There are two different types of whitelists in CrowdSec:
24+
There are three different types of whitelists in CrowdSec:
2525
- Parser (at enrich stage)
2626
- Postoverflow
27+
- AllowLists
2728

2829
Its important to note where these whitelists are applied in the pipeline, as this will affect the behavior and the context of the whitelists.
2930

@@ -51,11 +52,30 @@ typically these files are located in the following locations depending on your O
5152

5253
*Postoverflow whitelist folders do not exist by default so you **MUST** manually create them*
5354

55+
### AllowLists
56+
57+
:::info
58+
Allowlist were added in version `1.6.8` please ensure you are on this version to follow these Steps
59+
:::
60+
61+
AllowLists are a new feature that lets you centrally manage whitelisted IP addresses and CIDR ranges using `cscli`. This is the preferred method for allowlisting, as AllowLists are integrated with all major components of CrowdSec, including:
62+
63+
- AppSec component
64+
- `cscli`
65+
- Scenario overflows
66+
- Console Blocklists
67+
68+
5469
### Which one should I use?
5570

56-
If you know which IP or event pattern you want to whitelist (for example a URI), then you should use a Parser whitelist. If you want to do a more complex whitelist, such as a DNS/rDNS lookup, then you should use the Postoverflow Whitelist.
71+
If you already know the IP address or CIDR range you want to whitelist, use the `cscli` AllowLists feature. This ensures the IP is excluded across all CrowdSec components.
72+
73+
If you're looking to whitelist based on a specific event pattern (such as a URI), use a **Parser whitelist**. For more advanced logic—like DNS or reverse DNS lookups—use a **Postoverflow whitelist**.
5774

58-
In short, enricher whitelists are applied to **every** event (log line), whereas postoverflow whitelists are only applied to **triggered** scenarios.
75+
To summarize:
76+
- Use **AllowLists** for IP and CIDR ranges.
77+
- **Enricher whitelists** apply to **every** event (each log line).
78+
- **Postoverflow whitelists** apply only to **triggered** scenarios.
5979

6080
## Should I create a whitelist?
6181

@@ -85,6 +105,62 @@ The example location shown is for Linux, you will need to adjust the path based
85105

86106
### Static IP address
87107

108+
#### AllowLists
109+
110+
You can create a new AllowList using `cscli`:
111+
112+
```bash
113+
cscli allowlist create my_allowlist -d 'created from the docs'
114+
```
115+
116+
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.
117+
118+
To add entries to the AllowList, provide the name and the value you want to allow:
119+
120+
Single IP:
121+
122+
```bash
123+
cscli allowlist add my_allowlist 192.168.1.1
124+
```
125+
126+
CIDR range:
127+
128+
```bash
129+
cscli allowlist add my_allowlist 192.168.1.0/24
130+
```
131+
132+
A key benefit of using AllowLists is that changes take effect immediately—no need to restart CrowdSec.
133+
134+
To view the contents of an AllowList, run:
135+
136+
```bash
137+
cscli allowlist inspect my_allowlist
138+
```
139+
140+
Example output:
141+
142+
```
143+
──────────────────────────────────────────────
144+
Allowlist: my_allowlist
145+
──────────────────────────────────────────────
146+
Name my_allowlist
147+
Description created from the docs
148+
Created at 2025-05-13T14:10:12.668Z
149+
Updated at 2025-05-13T14:12:30.177Z
150+
Managed by Console no
151+
──────────────────────────────────────────────
152+
153+
───────────────────────────────────────────────────────────────
154+
Value Comment Expiration Created at
155+
───────────────────────────────────────────────────────────────
156+
192.168.1.0/24 never 2025-05-13T14:10:12.668Z
157+
───────────────────────────────────────────────────────────────
158+
```
159+
160+
You can see the full list of `allowlist` command via `cscli` [here](/docs/next/cscli/cscli_allowlists).
161+
162+
#### Enricher file
163+
88164
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:
89165

90166
```yaml title="/etc/crowdsec/parsers/s02-enrich/01-my-whitelist.yaml"
@@ -102,8 +178,6 @@ Once you have created the file you will need to restart the CrowdSec service for
102178
sudo systemctl restart crowdsec
103179
```
104180

105-
### IP Range
106-
107181
If you want to whitelist a range of IP addresses, for example `192.168.1.0/24` you can create a file in the Enricher folder with the following content:
108182

109183
```yaml title="/etc/crowdsec/parsers/s02-enrich/01-my-whitelist.yaml"

0 commit comments

Comments
 (0)