Centralized allowlists (#745)

Author: blotus

crowdsec-docs/docs/configuration/crowdsec_configuration.md

@@ -912,6 +912,13 @@ This option will disable the registration of remote agents using `cscli lapi reg
 ##### `capi_whitelists_path`
 > string
 
+:::warning
+
+This option is deprecated.
+You should use [centralized allowlists](local_api/allowlists.md) instead.
+
+:::
+
 The path to whitelists file for community and 3rd party blocklists.
 Those IPs/CIDR whitelists apply on all the IPs received from community blocklist or 3rd party lists subscriptions.
 

crowdsec-docs/docs/local_api/allowlists.md

@@ -0,0 +1,113 @@
+---
+id: centralized_allowlists
+title: Allowlists
+sidebar_position: 7
+---
+
+# AllowLists
+
+The AllowLists feature in CrowdSec lets users manage IP-based allowlists at the LAPI level, affecting both local decisions and blocklist pulls. [Paying customers can also control AllowLists directly from the console for added convenience](/u/console/allowlists). This ensures greater flexibility in managing trusted IPs while maintaining CrowdSec’s robust security measures.
+
+
+The AllowLists affect local decision and blocklist pulls in different ways:
+
+| Area | Action | Real Time |
+|-------|------|------| 
+| Local alerts | Alert is dropped, action logged. | ✅ |
+| Blocklists | IP is removed before database insertion | ✅ |
+| WAF (AppSec) | Request not blocked, action logged. | Refreshed every minute |
+| cscli | Decision is blocked unless special flag is provided | ✅ |
+
+
+AllowLists are limited to IP/Range based rules. If you need rules that rely on log elements such as URL and so on, [Parser Whitelists](/log_processor/whitelist/introduction.md) or [Profile Rules](/local_api/profiles/format.md) might more relevant.
+
+
+### Creating an allowlist
+
+Allowlists creation is done with `cscli allowlists create`, for example: `cscli allowlists create my_allowlistd -d safe_ips`.
+
+The `-d` parameter is mandatory, it's a description for the allowlist for future reference:
+```bash
+$ cscli allowlists create my_allowlist --description "test allowlist"
+allowlist 'my_allowlist' created successfully
+```
+
+This command must be run on the LAPI.
+
+### Adding entries to an allowlist
+
+Adding new entries to an allowlist is done with `cscli allowlists add <allowlist_name> value_1 value_2 ...`.
+
+The allowlist must exist.
+
+By default, allowlist entries have no expiration, but you can specify one with the `-e` flag:
+
+```bash
+$ cscli allowlist add my_allowlist 1.2.3.4 -e 7d
+added 1 values to allowlist my_allowlist
+```
+
+Values can be either IPs or ranges.
+
+You can add an optional description for each entry with the `-d` flag:
+
+```bash
+$ cscli allowlists add my_allowlist 1.2.3.4 -e 7d -d "pentest IPs"
+added 1 values to allowlist my_allowlist
+```
+
+You cannot add the same values twice to an allowlist: if you want to edit an entry, you'll need to remove it first then add it again.
+
+This command must be run on the LAPI.
+
+
+### Removing entries from an allowlist
+
+Removing entries from an allowlist is done with `cscli allowlists remove <allowlist_name> value_1 value_2 ...`:
+```bash
+$ cscli allowlists remove my_allowlist 1.2.3.4
+removed 1 values from allowlist my_allowlist
+```
+
+This command must be run on the LAPI.
+
+
+### Viewing the content of an allowlist
+
+Allowlists can be inspected with `cscli allowlists inspect <allowlist_name>`:
+
+```bash
+$ cscli allowlist inspect my_allowlist
+
+──────────────────────────────────────────────
+ Allowlist: my_allowlist                      
+──────────────────────────────────────────────
+ Name                my_allowlist             
+ Description         test allowlist           
+ Created at          2025-03-06T13:14:42.957Z 
+ Updated at          2025-03-06T13:15:13.684Z 
+ Managed by Console  no                       
+──────────────────────────────────────────────
+
+──────────────────────────────────────────────────────────────────────────────────
+ Value    Comment              Expiration                Created at               
+──────────────────────────────────────────────────────────────────────────────────
+ 1.2.3.4  example description  2025-03-13T13:15:05.046Z  2025-03-06T13:14:42.957Z 
+ 5.4.3.2                       never                     2025-03-06T13:14:42.957Z 
+──────────────────────────────────────────────────────────────────────────────────
+```
+
+This command can be run on the LAPI or any log processor machine.
+
+### Deleting an allowlist
+
+Allowlists can be deleted with `cscli allowlists delete <allowlist_name>`:
+
+```bash
+$ cscli allowlists delete my_allowlist 
+allowlist 'my_allowlist' deleted successfully
+```
+
+The allowlist and all of its content will be deleted.
+
+This command must be run on the LAPI.

crowdsec-docs/docs/log_processor/whitelist/capi_based_whitelist.md

@@ -3,6 +3,13 @@ id: create_capi
 title: CAPI
 ---
 
+:::warning
+
+This option is deprecated.
+You should use [centralized allowlists](local_api/allowlists.md) instead.
+
+:::
+
 ## Whitelists from CAPI (Central API) community blocklist or third party blocklist
 
 From version 1.5.0 a user can specify a list of IP's or IP ranges to be whitelisted from a community blocklist or third party blocklist. You will have to specify a path to the file within `config.yaml` as by default there is no file specified.

crowdsec-docs/docs/log_processor/whitelist/introduction.md

@@ -12,6 +12,7 @@ Whitelists are special parsers that allow you to "discard" events, and can exist
     - Freebsd: `/usr/local/etc/crowdsec/parsers/s02-enrich/`
     - Windows: `c:/programdata/crowdsec/config/parsers/s02-enrich/`
 
+ - *LAPI AllowLists* : Centralized at the LAPI level, those allowlists allow to discard the decision and alert while still generating a log entry. They can be IP/Range (CIDR) based. See [LAPI AllowLists](/local_api/allowlists.md)
 
  - *PostOverflow whitelists* : Those are whitelists that are checked *after* the overflow happens. It is usually best for whitelisting process that can be expensive (such as performing reverse DNS on an IP address, or performing a `whois` of an IP address).
     - Linux: `/etc/crowdsec/postoverflows/s01-whitelist/`
@@ -20,7 +21,9 @@ Whitelists are special parsers that allow you to "discard" events, and can exist
 
 *Postoverflow whitelist folders do not exist by default so you **MUST** manually create them*
 
-The whitelist can be based on several criteria:
+**Parser Whitelists** and **PostOverflow Whitelists** offer more flexibility, but are harder to manage. If you  stick to IP-based whitelists, [**Centralized AllowLists**](/local_api/allowlists.md) is  the way to go.
+
+Otherwise, whitelist can be based on several criteria:
 
  - specific IP address : if the event/overflow IP is the same, event is whitelisted
  - IP ranges : if the event/overflow IP address belongs to this range, event is whitelisted

crowdsec-docs/sidebars.js

@@ -263,6 +263,7 @@ module.exports = {
                 "local_api/configuration",
                 "local_api/authentication",
                 "local_api/tls_auth",
+                "local_api/centralized_allowlists",
                 {
                     type: "link",
                     label: "Swagger",

crowdsec-docs/sidebarsUnversioned.js

@@ -219,6 +219,15 @@ module.exports = {
                 label: "Decisions Management 🏅"
             }],
         },
+        {
+            type: "category",
+            label: "Centralized Allowlists 🏅",
+            link: {
+                type: "doc",
+                id: "console/allowlists",
+            },
+            items: [],
+        },
         {
             type: "category",
             label : "Enterprise plan 🏅",