Centralized allowlists

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 🏅",

crowdsec-docs/unversioned/console/allowlists.mdx

@@ -0,0 +1,40 @@
+# Centralized allowlists
+
+> 🌟 Premium feature
+
+Centralized allowlists is a powerful feature that allows you to manage allowlists across all your security engines and integrations from a single location. For free, you can still use [allowlist](next/local_api/centralized_allowlists) locally.
+
+## How do allowlists work?
+
+Allowlists are a list of IP addresses or IP ranges that you trust and want to bypass your security rules. When an IP address is in the allowlist, it will not be blocked by your security engine. This is useful when you have services that you know are safe and don't want to be blocked. When integrations are subscribed to allowlists, we will remove the allowlisted IP addresses from the list before sending them to the integration.
+
+
+## Getting started
+
+Proceed to the `Blocklist` tab located on the top menu bar. From there, you can select the Allowlists sub-menu
+
+![](/img/console/allowlists/allowlists-menu.png)
+
+The first step is to create an allowlist. Click on the "Add an Allowlist" button and fill out the form with the details of the allowlist.
+
+![](/img/console/allowlists/allowlists-create.png)
+
+Congratulations! You have created your first allowlist. You can now see it in the list of allowlists with some basic information like the number of items (IP addresses, IP ranges) in the allowlist, the number of subscribers, and the date it was created. You can delete or click on the allowlist to view it more closely.
+
+![](/img/console/allowlists/allowlists-list.png)
+
+
+## Add IPs or IP ranges to an allowlist
+
+To add IPs or IP ranges to an allowlist, click on the allowlist to which you want to add items. You will be redirected to the allowlist details page. Click on the "Add IP" button and fill in the form with the IP or IP range details you want to add. You can add multiple items by writing one by line in the corresponding field. 
+The description field in the form is mandatory and will help you identify the item later.
+Expiration allows you to set a date when the item will be automatically removed from the allowlist. This is useful when allowing an IP for a limited time. We suggest predefined expiration times like 1 week, 30 days... but you can also define your expiration date.
+
+![](/img/console/allowlists/allowlists-add-items.png)
+
+
+## Subscribe to an allowlist
+
+Click on the "Subscribe" button and select the integration for which you want to subscribe to the allowlist. You can subscribe to multiple integrations, security engines, or the whole organization to the same allowlist. At the top of the subscription windows, you can choose between the different types of subscriptions and then select the subscribers you want to add.
+
+![](/img/console/allowlists/allowlists-subscription.png)