enhance: allowlist sweep and readability of FAQ (#1030)

Author: LaurenceJJones

crowdsec-docs/docs/appsec/troubleshooting.md

@@ -8,8 +8,8 @@ sidebar_position: 81
 ## Monitoring with `cscli`
 
 `cscli metrics` exposes basic metrics about the AppSec Component:
- - Number of requests processed and blocked by the component/data source
- - Number of triggers for each rule
+- Number of requests processed and blocked by the component/data source
+- Number of triggers for each rule
 
 ```
 Appsec Metrics:
@@ -43,8 +43,8 @@ Setting `log_level` to `debug` or `trace` in the acquisition config section or t
 
 
 When enabling debug at acquisition or AppSec config level:
- - load time debug will be enabled, such as information regarding the translation of the rule to `SecRule` format.
- - runtime debug will be enabled for all the rules loaded by the AppSec Component / AppSec config.
+- Load-time debug is enabled (for example, rule translation to `SecRule` format).
+- Runtime debug is enabled for all rules loaded by the AppSec Component/AppSec config.
 
 When enabling debug directly at the AppSec rule level, only runtime evaluation details for that rule are displayed, such as:
 
@@ -107,10 +107,10 @@ INFO[2023-12-06 14:58:19] loading acquisition file : ...
 
 ## Testing a given rule
 
-We can create a skeleton environment with:
- - acquisition config that is going to load your test AppSec config
- - appsec config to load the test rule
- - the test rule itself
+Create a minimal test environment with:
+- An acquisition config that loads your test AppSec config
+- An AppSec config that loads the test rule
+- The test rule itself
 
 > /etc/crowdsec/acquis.d/test_appsec.yaml 
 ```bash
@@ -170,13 +170,13 @@ time="2023-12-20 13:39:29" level=info msg="Appsec Runner ready to process event"
 
 ## Interacting with the AppSec Component
 
-To test that the AppSec Component is working correctly, you can send requests directly to it. A few things to know:
- - To query the AppSec Component, you need to have a valid remediation component API Key
- - The AppSec Component expects to receive some of the elements in specific headers
+To test that the AppSec Component is working, send requests directly to it. Keep in mind:
+- You need a valid remediation component API key
+- The AppSec Component expects specific values in headers
 
 
-We are going to test that the AppSec Component detects correctly CVE-2023-42793, which is part of the [virtual patching collection](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching), that should be installed for this to work (see `cscli appsec-rules list`).
-[This rule](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-rules/vpatch-CVE-2023-42793) is pretty straightforward and detects requests to an URI ending with `/rpc2`:
+This example tests detection for CVE-2023-42793, part of the [virtual patching collection](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching). Make sure the collection is installed (`cscli appsec-rules list`).
+[This rule](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-rules/vpatch-CVE-2023-42793) detects requests to a URI ending with `/rpc2`:
 
 > cat /etc/crowdsec/appsec-rules/vpatch-CVE-2023-42793.yaml
 ```yaml
@@ -204,13 +204,13 @@ labels:
    - cwe.CWE-288
 ```
 
-To be able to communicate with the AppSec Component, let's create a bouncer API Key:
+To communicate with the AppSec Component, create a bouncer API key:
 
 ```bash
 cscli bouncers add appsec_test -k this_is_a_bad_password
 ```
 
-We can now query our AppSec Component (we're assuming here that it runs on the default `127.0.0.1:7422`, see the `listen_addr` parameter of the acquisition config):
+You can now query the AppSec Component (assuming the default `127.0.0.1:7422`; see the `listen_addr` setting in your acquisition config):
 
 ```bash
 ▶ curl -X POST localhost:7422/ -i -H 'x-crowdsec-appsec-ip: 192.168.1.1' -H 'x-crowdsec-appsec-uri: /rpc2' -H 'x-crowdsec-appsec-host: google.com' -H 'x-crowdsec-appsec-verb: POST' -H 'x-crowdsec-appsec-api-key: this_is_a_bad_password'
@@ -222,15 +222,15 @@ Content-Type: text/plain; charset=utf-8
 {"action":"ban"}
 ```
 
-And we see the alert appearing in `crowdsec.log` :
+The alert should appear in `crowdsec.log`:
 
 ```
 ...
 INFO[2023-12-05 12:17:52] (test) alert : crowdsecurity/vpatch-CVE-2023-42793 by ip 192.168.1.1
 ...
 ```
 
-And in `cscli alerts list` : 
+And in `cscli alerts list`:
 
 ```
 ╭────┬────────────────┬─────────────────────────────────────┬─────────┬────┬───────────┬───────────────────────────────╮

crowdsec-docs/docs/local_api/allowlists.md

@@ -6,10 +6,16 @@ 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 feature in CrowdSec lets you manage IP-based allowlists at the LAPI level. It affects both local decisions and blocklist pulls, giving you more flexibility to trust specific IPs while keeping CrowdSec security controls in place.
 
+:::tip CrowdSec Premium: Centralized Console Management
 
-The AllowLists affect local decision and blocklist pulls in different ways:
+Premium users can manage AllowLists directly from the [CrowdSec Console](/u/console/allowlists), enabling centralized management across multiple Security Engines and Integrations. Console-managed allowlists require subscribing entities (Security Engines, Integrations, or Organizations) after creation.
+
+:::
+
+
+AllowLists affect local decisions and blocklist pulls in different ways:
 
 | Area | Action | Real Time |
 |-------|------|------| 
@@ -19,35 +25,35 @@ The AllowLists affect local decision and blocklist pulls in different ways:
 | 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.
+AllowLists are limited to IP/range-based rules. If you need rules based on log elements (such as URLs), [Parser Whitelists](/log_processor/whitelist/introduction.md) or [Profile Rules](/local_api/profiles/format.md) might be more relevant.
 
 
-### Creating an allowlist
+## Creating an allowlist
 
-Allowlists creation is done with `cscli allowlists create`, for example: `cscli allowlists create my_allowlistd -d safe_ips`.
+Create an allowlist with `cscli allowlists create`, for example: `cscli allowlists create my_allowlist -d safe_ips`.
 
-The `-d` parameter is mandatory, it's a description for the allowlist for future reference:
+The `-d` flag is mandatory. It sets a description 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 entries to an allowlist
 
-Adding new entries to an allowlist is done with `cscli allowlists add <allowlist_name> value_1 value_2 ...`.
+Add entries 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
+$ cscli allowlists add my_allowlist 1.2.3.4 -e 7d
 added 1 values to allowlist my_allowlist
 ```
 
-Values can be either IPs or ranges.
+Values can be IPs or ranges.
 
 You can add an optional description for each entry with the `-d` flag:
 
@@ -56,14 +62,14 @@ $ 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.
+You cannot add the same value twice to an allowlist. To edit an entry, 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
 
-Removing entries from an allowlist is done with `cscli allowlists remove <allowlist_name> value_1 value_2 ...`:
+Remove entries 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
@@ -72,12 +78,12 @@ removed 1 values from allowlist my_allowlist
 This command must be run on the LAPI.
 
 
-### Viewing the content of an allowlist
+## Viewing the contents of an allowlist
 
-Allowlists can be inspected with `cscli allowlists inspect <allowlist_name>`:
+Inspect an allowlist with `cscli allowlists inspect <allowlist_name>`:
 
 ```bash
-$ cscli allowlist inspect my_allowlist
+$ cscli allowlists inspect my_allowlist
 
 ──────────────────────────────────────────────
  Allowlist: my_allowlist                      
@@ -99,9 +105,9 @@ $ cscli allowlist inspect my_allowlist
 
 This command can be run on the LAPI or any log processor machine.
 
-### Deleting an allowlist
+## Deleting an allowlist
 
-Allowlists can be deleted with `cscli allowlists delete <allowlist_name>`:
+Delete an allowlist with `cscli allowlists delete <allowlist_name>`:
 
 ```bash
 $ cscli allowlists delete my_allowlist 

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

@@ -6,29 +6,29 @@ title: CAPI
 :::warning
 
 This option is deprecated.
-You should use [centralized allowlists](local_api/allowlists.md) instead.
+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.
+From version 1.5.0, you can define IPs or IP ranges to whitelist from the community blocklist or third-party blocklists. Set the whitelist file path in `config.yaml` (no default path is set).
 
 ```yaml
 api:
   server:
     capi_whitelists_path: <path_to_capi_whitelists_file>
 ```
 
-We recommend to use the following files for each OS:
+Recommended file paths:
 
 - Linux `/etc/crowdsec/capi-whitelists.yaml` 
 - Freebsd `/usr/local/etc/crowdsec/capi-whitelists.yaml` 
 - Windows `c:/programdata/crowdsec/config/capi-whitelists.yaml`
 
-*These files **DO NOT** exist and you **MUST** create them manually and configure the above settings*
+*These files **DO NOT** exist by default. You **MUST** create them manually and set the path above.*
 
-The following snippet should be used as a guide
+Example file content:
 
 ```yaml
 ips:
@@ -44,8 +44,8 @@ sudo systemctl reload crowdsec
 
 :::warning
 
-The whitelist only applies when crowdsec pulls the blocklist from CAPI. This means that any IPs already in your local database will not get whitelisted.
+The whitelist applies only when CrowdSec pulls blocklists from CAPI. IPs already in your local database are not retroactively whitelisted.
 
-You can either manually delete the decisions for the IPs you want to whitelist with `cscli decisions delete`, or delete all alerts and active decisions from the database with `cscli alerts delete --all` and restart crowdsec.
+You can either delete decisions for specific IPs with `cscli decisions delete`, or delete all alerts and active decisions with `cscli alerts delete --all` and then restart CrowdSec.
 
 :::

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

@@ -26,23 +26,23 @@ There are two main ways to create an expression-based whitelist:
 
 ### Path 1: Starting from an alert
 
-When you have a false positive alert, inspect it to extract event details and build a whitelist.
+When you have a false-positive alert, inspect it to extract event details and build a whitelist.
 
-#### Step 1: Identify the alert and extract its events
+#### Step 1: Identify the alert and extract events
 
 1. List recent alerts:
 
 ```bash
 sudo cscli alerts list
 ```
 
-2. Inspect the alert with event details:
+2. Inspect an alert with event details:
 
 ```bash
 sudo cscli alerts inspect <ALERT_ID> -d
 ```
 
-The `-d/--details` flag shows the events associated with the alert. From the output, note:
+The `-d/--details` flag shows events associated with the alert. From the output, note:
 
 - The **log type** (e.g., `nginx`, `apache2`, `sshd`, etc.)
 - Any helpful **meta** fields (http path, status, verb, user-agent, etc.)
@@ -152,13 +152,13 @@ In this example, the events section lists keys such as `http_path`, `http_status
 
 </details>
 
-#### Step 2: Extract a representative log line
+#### Step 2: Pick a representative log line
 
-From the alert details, pick one triggering log line. You will need the raw line for `cscli explain` in the next step.
+From the alert details, pick one triggering log line. You will use the raw line with `cscli explain` in the next step.
 
 #### Step 3: Use `cscli explain` to reveal parsed fields
 
-To write a safe whitelist, you need the exact field names and values CrowdSec has at parse/enrich time.
+To write a safe whitelist, use the exact field names and values available at parse/enrich time.
 
 Run `cscli explain` against the log line:
 
@@ -169,7 +169,7 @@ sudo cscli explain \
   -v
 ```
 
-`cscli explain -v` shows which parsers ran and what they populated in `evt.Parsed.*`, `evt.Meta.*`, and so on.
+`cscli explain -v` shows which parsers ran and what they populated in `evt.Parsed.*`, `evt.Meta.*`, and related fields.
 
 **What to look for** in the explain output:
 
@@ -186,7 +186,7 @@ When you already know the log line pattern you want to whitelist (e.g., health c
 
 #### Step 1: Use `cscli explain` to reveal parsed fields
 
-You can use [cscli explain](/cscli/cscli_explain.md) to generate output from a log line or a log file.
+Use [cscli explain](/cscli/cscli_explain.md) on a log line or a log file.
 
 For example, with a single log line:
 
@@ -284,7 +284,7 @@ line: 5.5.8.5 - - [04/Jan/2020:07:25:02 +0000] "GET /.well-known/acme-challenge/
 		└ 🟢 crowdsecurity/http-probing
 ```
 
-You can see what data is available from the `s01-parse` stage. Look for fields in `evt.Parsed.*` and `evt.Meta.*` that you can use in your whitelist expression.
+This output shows what data is available from the `s01-parse` stage. Look for fields in `evt.Parsed.*` and `evt.Meta.*` that you can use in your whitelist expression.
 
 </details>
 
@@ -324,7 +324,7 @@ whitelist:
 
 :::tip
 
-Keep whitelist expressions as narrow as possible (path + verb + maybe user-agent) to avoid hiding real attacks.
+Keep whitelist expressions as narrow as possible (path + verb + optional user-agent) to avoid hiding real attacks.
 
 :::