Merge pull request #522 from crowdsecurity/revamp_alert_context_guide

revamp alert context user guide

crowdsec-docs/unversioned/user_guides/alert_context.md

@@ -4,41 +4,32 @@ title: Contextualize Alerts
 sidebar_position: 10
 ---
 
-# Alert Contextualization
+## Introduction
 
-While CrowdSec doesn't store any logs after processing it, it can be useful to get some context about why an alert has been triggered (source machine, targeted FQDN ...).
+CrowdSec doesn't store raw log information once it has finished processing them. However, you can send additional data within an alert with a feature we call **alert context**:
 
-The context configuration is part of the CrowdSec Hub and each collection should come with a context configuration file.
+![Alert Context Example](/img/alert_context.png)
 
-The only thing to do if you want to see the context in the console is to enable the `context` option in your CrowdSec Local API [see below](#send-alert-context-to-crowdsec-console).
+Whilst some collections already include a context configuration, you must enable the `context` option within your security engine console configuration.
 
-You can get context values from:
+This can be achieved by running:
 
-- Part of a parsed log line (with `evt.Parsed`)
-- Meta values set by parsers (with `evt.Meta`)
-- Hardcoded strings in the context configuration (with `"my_value"`)
-- More generally, anything available in `evt` (eg, `evt.Unmarshaled` with some parsers)
-- From expr helpers (all expr helpers are available in the context, allowing for example `CrowdsecCTI(evt.Meta.source_ip).GetMaliciousnessScore()`)
-
-More information [here](/docs/next/cscli/cscli_contexts) for managing the context from the Hub with `cscli`.
+```bash
+sudo cscli console enable context
+```
 
-## Send alert context to CrowdSec Console
+## Check current config
 
-> This command has to be run on the CrowdSec Local API
+:::info
 
-To send the context with the alert to the CrowdSec Console, you need to enable the feature on the CrowdSec Local API server:
+These commands have to be run on the CrowdSec Local API
 
-```bash
-$ sudo cscli console enable context
-INFO[12-12-2022 08:21:29 PM] context set to true
-INFO[12-12-2022 08:21:29 PM] [context] have been enabled
-INFO[12-12-2022 08:21:29 PM] Run 'sudo systemctl reload crowdsec' for the new configuration to be effective.
-```
+:::
 
 You can view the current status of your console options with:
 
 ```bash
-sudo cscli console status
+$ sudo cscli console status
 ╭────────────────────┬───────────┬───────────────────────────────────────────────────╮
 │ Option Name        │ Activated │ Description                                       │
 ├────────────────────┼───────────┼───────────────────────────────────────────────────┤
@@ -50,6 +41,32 @@ sudo cscli console status
 ╰────────────────────┴───────────┴───────────────────────────────────────────────────╯
 ```
 
+You can enable alert context with:
+
+```bash
+sudo cscli console enable context
+```
+
+You can as well inspect and control the enabled alert context configuration:
+
+```bash
+$ sudo cscli lapi context status
+method:
+- evt.Meta.http_verb
+status:
+- evt.Meta.http_status
+target_uri:
+- evt.Meta.http_path
+target_user:
+- evt.Meta.target_user
+user_agent:
+- evt.Meta.http_user_agent
+```
+
+:::note
+The context configuration can as well be found in `/etc/crowdsec/contexts/` as yaml files.
+:::
+
 ## Vizualise alert context
 
 The alert context will be display when inspecting an alert:
@@ -87,17 +104,86 @@ $ sudo cscli alerts inspect 7
 
 And we can see that the `target_fqdn` and the `user_agent` are now displayed in the context of the alert.
 
-## Detect possible values for context
+## Adding custom alert context
+
+You can get context values from:
+
+- Part of a parsed log line (with `evt.Parsed`)
+- Meta values set by parsers (with `evt.Meta`)
+- Hardcoded strings in the context configuration (with `"my_value"`)
+- More generally, anything available in `evt` (eg, `evt.Unmarshaled` with some parsers)
+- From expr helpers (all expr helpers are available in the context, allowing for example `CrowdsecCTI(evt.Meta.source_ip).GetMaliciousnessScore()`)
+
+You can add your custom alert context by adding a yaml file in `/etc/crowdsec/contexts/` :
+
+```bash
+cat > /etc/crowdsec/contexts/example.yaml << EOF
+context:
+  example_value:
+  - '"something"'
+  http_extra_status:
+  - evt.Meta.http_status
+EOF
+```
+
+Let's now trigger a http scenario by trying to exploit a well known vulnerability:
+
+```bash
+$ curl 'target.com/%2E%2E/%2E%2E'
+```
+
+In `crowdsec.log`, we're seeing our alert:
+
+```bash
+time="2024-01-24T18:08:34+01:00" level=info msg="Ip x.x.x.x performed 'crowdsecurity/http-cve-2021-41773' (1 events over 336ns) at 2024-01-24 17:08:34.026228434 +0000 UTC"
+```
+
+It as well appears when we're inspecting our alert:
+
+```bash
+$ cscli  alerts list
+╭──────┬────────────────────┬────────────────────────────────────────────┬─────────┬─────────────────────────────────────────────────────────┬───────────┬─────────────────────────────────────────╮
+│  ID  │       value        │                   reason                   │ country │                           as                            │ decisions │               created_at                │
+├──────┼────────────────────┼────────────────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────┼───────────┼─────────────────────────────────────────┤
+│ 6545 │ Ip:xxx.xx.xx.xx    │ crowdsecurity/http-cve-2021-41773          │ FR      │ 5410 Bouygues Telecom SA                                │ ban:1     │ 2024-01-24 17:08:34.026228866 +0000 UTC │
+...
+$  cscli  alerts inspect -d 6545
+...
+ - Context  :
+╭───────────────────┬────────────────╮
+│        Key        │     Value      │
+├───────────────────┼────────────────┤
+│ example_value     │ something      │
+│ http_extra_status │ 400            │
+│ method            │ HEAD           │
+│ status            │ 400            │
+│ target_uri        │ /%2E%2E/%2E%2E │
+│ user_agent        │ -              │
+╰───────────────────┴────────────────╯
+...
+```
+
+And in the console:
+
+![Alert Context Example](/img/alert_context_custom.png)
+
+
+More information [here](/docs/next/cscli/cscli_contexts) for managing the context from the Hub with `cscli`.
+
+## Automagically detect possible alert context
 
 It is possible to detect all the possible fields that a given parser can output (or all the installed parsers with `--all` flag):
 
 ```bash
 $ sudo cscli lapi context detect crowdsecurity/nginx-logs
 Acquisition :
+
   - evt.Line.Module
   - evt.Line.Raw
   - evt.Line.Src
+
 crowdsecurity/nginx-logs :
+
   - evt.Meta.http_path
   - evt.Meta.http_status
   - evt.Meta.http_user_agent
@@ -130,28 +216,11 @@ crowdsecurity/nginx-logs :
   - evt.StrTime
 ```
 
-## Add manual context to alerts
-
-> This command has to be run on the CrowdSec Engine
-
-You can choose the fields that you want to add to the context of your alerts with `cscli`:
-
-```bash
-sudo cscli lapi context add --key target_fqdn --value evt.Meta.target_fqdn
-sudo cscli lapi context add --key user_agent --value evt.Parsed.http_user_agent
-```
+## Delete a context
 
-It is not mandatory to specify the key. If you don't specify it, it will be guessed from the value field.
-For example, running this command:
+Delete the yaml file containing your custom alert context, and reload crowdsec.
 
 ```bash
-sudo cscli lapi context add --value evt.Meta.target_fqdn
+rm /etc/crowdsec/contexts/example.yaml
+systemctl restart crowdsec
 ```
-
-Will add the context with the key `target_fqdn`.
-
-## Delete a context
-
-It is not possible to delete the context added manually or in a context item with `cscli`.
-
-The context added manually will be stored in `/etc/crowdsec/console/context.yaml`, so if you want to remove a context added manually, you can edit directly this configuration file.