Add on_error and some example profiles (#460)

* Add on_error and some example profiles * Add on_error in CTI example so it easier to spot * Mad lad updates * Mad lad update 2 * Mad lad update 3 * Fix duration expr * Add pid profile * Add collections free promo ;) * Update scoring
crowdsecurity · Oct 16, 2023 · 9d27ee2 · 9d27ee2
1 parent f250beb
commit 9d27ee2
Show file tree

Hide file tree

Showing 5 changed files with 210 additions and 3 deletions.
diff --git a/crowdsec-docs/docs/profiles/captcha_profile.md b/crowdsec-docs/docs/profiles/captcha_profile.md
@@ -0,0 +1,57 @@
+---
+id: captcha_profile
+title: Captcha
+sidebar_position: 2
+---
+
+Here is an example of a profile that provides users with a captcha challenge when they trigger a HTTP scenario.
+
+:::info
+You **MUST** have configured a remediation component that supports captcha challenges, see [Remediation](/bouncers/intro.md).
+:::
+
+```yaml
+name: captcha_remediation
+filters:
+  - Alert.Remediation == true && Alert.GetScope() == "Ip" && Alert.GetScenario() contains "http"
+## Any scenario with http in its name will trigger a captcha challenge
+decisions:
+ - type: captcha
+   duration: 4h
+on_success: break
+---
+name: default_ip_remediation
+filters:
+ - Alert.Remediation == true && Alert.GetScope() == "Ip"
+decisions:
+ - type: ban
+   duration: 4h
+#duration_expr: "Sprintf('%dh', (GetDecisionsCount(Alert.GetValue()) + 1) * 4)"
+on_success: break
+```
+
+The key piece of profile to point out is the `on_success` directive. It is set to `break` to ensure that the alert will not be evaluated by other profiles so the offender will only get a captcha decision.
+
+However, you may want to provide a limit to captcha challenges within a period of time to a given IP address because they may ignore your captcha challenges and still cause load on your server.
+
+You can use the `GetDecisionsCount` or `GetDecisionsSinceCount` helper to achieve this:
+
+```yaml
+name: captcha_remediation
+filters:
+  - Alert.Remediation == true && Alert.GetScope() == "Ip" && Alert.GetScenario() contains "http" && GetDecisionsSinceCount(Alert.GetValue(), "24h") <= 3
+## Same as above but only 3 captcha decision per 24 hours before ban
+decisions:
+ - type: captcha
+   duration: 4h
+on_success: break
+---
+name: default_ip_remediation
+filters:
+ - Alert.Remediation == true && Alert.GetScope() == "Ip"
+decisions:
+ - type: ban
+   duration: 4h
+#duration_expr: "Sprintf('%dh', (GetDecisionsCount(Alert.GetValue()) + 1) * 4)"
+on_success: break
+```
diff --git a/crowdsec-docs/docs/profiles/cti_profile.md b/crowdsec-docs/docs/profiles/cti_profile.md
@@ -0,0 +1,91 @@
+---
+id: cti_profile
+title: CrowdSec CTI
+sidebar_position: 1
+---
+
+Here is an example of a profile that uses the CTI module.
+
+:::info
+You **MUST** configure the CTI beforehand, see [CTI helpers](/expr/cti_helpers.md).
+:::
+
+### Background Noise Score
+
+Background noise score can be used to inform you if the ip address is noisy or not. You can use this information to make the decision more or less aggressive.
+
+```yaml
+name: high_bn_score
+on_error: continue
+filters:
+ - Alert.Remediation == true && Alert.GetScope() == "Ip" && CrowdsecCTI(Alert.GetValue()).GetBackgroundNoiseScore() > 6 && !CrowdsecCTI(Alert.GetValue()).IsFalsePositive()
+decisions:
+ - type: ban
+   duration: 24h
+on_success: break
+---
+name: mid_bn_score
+on_error: continue
+filters:
+ - Alert.Remediation == true && Alert.GetScope() == "Ip" && CrowdsecCTI(Alert.GetValue()).GetBackgroundNoiseScore() >= 3 && !CrowdsecCTI(Alert.GetValue()).IsFalsePositive()
+decisions:
+ - type: ban
+   duration: 12h
+on_success: break
+---
+name: default_ip_remediation
+filters:
+ - Alert.Remediation == true && Alert.GetScope() == "Ip"
+decisions:
+ - type: ban
+   duration: 4h
+#duration_expr: "Sprintf('%dh', (GetDecisionsCount(Alert.GetValue()) + 1) * 4)"
+on_success: break
+```
+
+A key piece of profile to point out is the `on_error` directive. It is set to `continue` to ensure that the alert will continue to be evaluated even if your API key is rate limited.
+
+You could also use the background noise within the `duration_expr` to make the ban duration proportional to the background noise score:
+
+```yaml
+name: bn_score
+on_error: continue
+filters:
+ - Alert.Remediation == true && Alert.GetScope() == "Ip" && CrowdsecCTI(Alert.GetValue()).GetBackgroundNoiseScore() > 0 && !CrowdsecCTI(Alert.GetValue()).IsFalsePositive()
+decisions:
+ - type: ban
+   duration: 12h
+duration_expr: "Sprintf('%dm', (240 + (120 * CrowdsecCTI(Alert.GetValue()).GetBackgroundNoiseScore())))"
+## 240 minutes (4 hours) + 120 minutes per point of background noise score
+## 120 = 20 * 60 / 10 (Max Background Noise Score)
+on_success: break
+---
+name: default_ip_remediation
+filters:
+ - Alert.Remediation == true && Alert.GetScope() == "Ip"
+decisions:
+ - type: ban
+   duration: 4h
+on_success: break
+```
+
+### Potential False Triggers
+
+Send a notification about a potential false triggers and break the alert evaluation:
+
+```yaml
+name: false_positive
+filters:
+ - Alert.Remediation == true && Alert.GetScope() == "Ip" && CrowdsecCTI(Alert.GetValue()).IsFalsePositive()
+notifications:
+    - http_hive
+on_success: break
+---
+name: default_ip_remediation
+filters:
+ - Alert.Remediation == true && Alert.GetScope() == "Ip"
+decisions:
+ - type: ban
+   duration: 4h
+on_success: break
+```
diff --git a/crowdsec-docs/docs/profiles/format.md b/crowdsec-docs/docs/profiles/format.md
@@ -118,19 +118,38 @@ It relies on [expr helpers](/expr/intro.md).
 ### `on_success`
 
 ```yaml
-on_success: break
+on_success: continue|break
 ```
 
 If the profile applies and `on_success` is set to `break`, decisions processing will stop here and it won't evaluate against following profiles.
 
+- `continue` will apply the profile even if the filter expression generates an error. (DEFAULT)
+- `break` will stop the processing of the alert if the filter expression generates an error.
 ### `on_failure`
 
 ```yaml
-on_failure: break
+on_failure: continue|break
 ```
 
 If the profile didn't apply and `on_failure` is set to `break`, decisions processing will stop here and it won't evaluate against following profiles.
 
+- `continue` will continue to the next profile if the filter expression generates an error. (DEFAULT)
+- `break` will stop the processing of the alert if the filter expression generates an error. 
+### `on_error`
+
+```yaml
+on_error: continue|break|apply|ignore
+```
+
+If the filter expression generates an error, this would normally stop the alert from being processed to prevent a potential unwanted outcome.
+
+- `break` will stop the processing of the alert if the filter expression generates an error. (DEFAULT)
+- `continue` will continue to the next profile if the filter expression generates an error.
+- `apply` will apply the profile even if the filter expression generates an error.
+- `ignore` will ignore the error and continue to the next profile.
+
+However, there may be some expressions that do generate expected errors for example, when using the [CTI helpers](/expr/cti_helpers.md) it may throw a rate limit error.
+
 ### `notifications`
 
 ```yaml

diff --git a/crowdsec-docs/docs/profiles/pid_profile.md b/crowdsec-docs/docs/profiles/pid_profile.md
@@ -0,0 +1,29 @@
+---
+id: pid_profile
+title: PID
+sidebar_position: 1
+---
+
+:::info
+We use PID to refer to a process ID based events.
+:::
+
+We provide collection for host based indicators of compromise (IOCs) that can be used to detect malicious activity on your hosts.
+
+Collections:
+  - [Auditd](https://hub.crowdsec.net/author/crowdsecurity/collections/auditd)
+  - [Laurel](https://hub.crowdsec.net/author/crowdsecurity/configurations/laurel-logs)
+
+Currently we cannot remediate these alerts, however, we can send you a notification when we detect them.
+
+```yaml
+name: pid_alert
+filters:
+ - Alert.GetScope() == "pid"
+decisions: []
+notifications:
+  - slack_default
+## Please edit the above line to match your notification name
+on_success: break
+---
+```
diff --git a/crowdsec-docs/sidebars.js b/crowdsec-docs/sidebars.js
@@ -291,7 +291,18 @@
                 type: "doc",
                 id: "profiles/intro",
             },
-            items: ["profiles/format"],
+            items: [
+                "profiles/format",
+                {
+                    type: "category",
+                    label: "Examples",
+                    items: [
+                        "profiles/cti_profile",
+                        "profiles/captcha_profile",
+                        "profiles/pid_profile",
+                    ],
+                }
+            ],
         },
         {
             type: "category",