From 0f7800e4dff513ee6752084c28003435209d5c50 Mon Sep 17 00:00:00 2001 From: Laurence Date: Wed, 11 Oct 2023 15:23:02 +0100 Subject: [PATCH 1/9] Add on_error and some example profiles --- .../docs/profiles/captcha_profile.md | 51 +++++++++++++++ crowdsec-docs/docs/profiles/cti_profile.md | 64 +++++++++++++++++++ crowdsec-docs/docs/profiles/format.md | 10 +++ crowdsec-docs/sidebars.js | 12 +++- 4 files changed, 136 insertions(+), 1 deletion(-) create mode 100644 crowdsec-docs/docs/profiles/captcha_profile.md create mode 100644 crowdsec-docs/docs/profiles/cti_profile.md diff --git a/crowdsec-docs/docs/profiles/captcha_profile.md b/crowdsec-docs/docs/profiles/captcha_profile.md new file mode 100644 index 00000000..f45d2668 --- /dev/null +++ b/crowdsec-docs/docs/profiles/captcha_profile.md @@ -0,0 +1,51 @@ +--- +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. + +```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 +``` + +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 +``` \ No newline at end of file diff --git a/crowdsec-docs/docs/profiles/cti_profile.md b/crowdsec-docs/docs/profiles/cti_profile.md new file mode 100644 index 00000000..49976a8d --- /dev/null +++ b/crowdsec-docs/docs/profiles/cti_profile.md @@ -0,0 +1,64 @@ +--- +id: cti_profile +title: CrowdSec CTI +sidebar_position: 2 +--- + +Here is an example of a profile that uses the CTI module to make decisions based on the background noise score of an IP address. + +:::info +You **MUST** configure the CTI beforehand, see [CTI helpers](/expr/cti_helpers.md). +::: + +```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 +``` + +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 + (144 * CrowdsecCTI(Alert.GetValue()).GetBackgroundNoiseScore()))" +## 240 minutes (4 hours) + 144 minutes (2 hours) per point of 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 +``` \ No newline at end of file diff --git a/crowdsec-docs/docs/profiles/format.md b/crowdsec-docs/docs/profiles/format.md index d6c445f6..dfdb0f7f 100644 --- a/crowdsec-docs/docs/profiles/format.md +++ b/crowdsec-docs/docs/profiles/format.md @@ -131,6 +131,16 @@ on_failure: 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. +### `on_error` + +```yaml +on_error: continue +``` + +If the filter expression generates an error, this would normally stop the alert from being processed to prevent a potential unwanted outcome. + +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/sidebars.js b/crowdsec-docs/sidebars.js index f55c53ec..5bf99ade 100644 --- a/crowdsec-docs/sidebars.js +++ b/crowdsec-docs/sidebars.js @@ -291,7 +291,17 @@ type: "doc", id: "profiles/intro", }, - items: ["profiles/format"], + items: [ + "profiles/format", + { + type: "category", + label: "Examples", + items: [ + "profiles/cti_profile", + "profiles/captcha_profile", + ], + } + ], }, { type: "category", From 4e3398010887c088fa778b27b8638e94a591e60a Mon Sep 17 00:00:00 2001 From: Laurence Date: Wed, 11 Oct 2023 15:33:21 +0100 Subject: [PATCH 2/9] Add on_error in CTI example so it easier to spot --- crowdsec-docs/docs/profiles/cti_profile.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/crowdsec-docs/docs/profiles/cti_profile.md b/crowdsec-docs/docs/profiles/cti_profile.md index 49976a8d..ccea7637 100644 --- a/crowdsec-docs/docs/profiles/cti_profile.md +++ b/crowdsec-docs/docs/profiles/cti_profile.md @@ -39,10 +39,11 @@ decisions: 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: From 2dec2ae9c06efc4e1f6dc3f297bc683d1733f02e Mon Sep 17 00:00:00 2001 From: Laurence Date: Wed, 11 Oct 2023 15:47:24 +0100 Subject: [PATCH 3/9] Mad lad updates --- crowdsec-docs/docs/profiles/captcha_profile.md | 6 ++++++ crowdsec-docs/docs/profiles/cti_profile.md | 5 +++-- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/crowdsec-docs/docs/profiles/captcha_profile.md b/crowdsec-docs/docs/profiles/captcha_profile.md index f45d2668..b528ce76 100644 --- a/crowdsec-docs/docs/profiles/captcha_profile.md +++ b/crowdsec-docs/docs/profiles/captcha_profile.md @@ -6,6 +6,10 @@ 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: @@ -26,6 +30,8 @@ decisions: 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: diff --git a/crowdsec-docs/docs/profiles/cti_profile.md b/crowdsec-docs/docs/profiles/cti_profile.md index ccea7637..69a448fe 100644 --- a/crowdsec-docs/docs/profiles/cti_profile.md +++ b/crowdsec-docs/docs/profiles/cti_profile.md @@ -1,7 +1,7 @@ --- id: cti_profile title: CrowdSec CTI -sidebar_position: 2 +sidebar_position: 1 --- Here is an example of a profile that uses the CTI module to make decisions based on the background noise score of an IP address. @@ -52,7 +52,8 @@ decisions: - type: ban duration: 12h duration_expr: "Sprintf('%dm', (240 + (144 * CrowdsecCTI(Alert.GetValue()).GetBackgroundNoiseScore()))" -## 240 minutes (4 hours) + 144 minutes (2 hours) per point of background noise score +## 240 minutes (4 hours) + 144 minutes per point of background noise score +## 144 = 24 * 60 / 10 on_success: break --- name: default_ip_remediation From e27f5ed42f452d2b076d48caa25012048fb81a90 Mon Sep 17 00:00:00 2001 From: Laurence Date: Wed, 11 Oct 2023 16:00:41 +0100 Subject: [PATCH 4/9] Mad lad update 2 --- crowdsec-docs/docs/profiles/cti_profile.md | 19 +++++++++++++++++++ crowdsec-docs/docs/profiles/format.md | 15 ++++++++++++--- 2 files changed, 31 insertions(+), 3 deletions(-) diff --git a/crowdsec-docs/docs/profiles/cti_profile.md b/crowdsec-docs/docs/profiles/cti_profile.md index 69a448fe..ddab95de 100644 --- a/crowdsec-docs/docs/profiles/cti_profile.md +++ b/crowdsec-docs/docs/profiles/cti_profile.md @@ -63,4 +63,23 @@ decisions: - type: ban duration: 4h on_success: break +``` + +Send a notification about a potential false positive to theHive 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 ``` \ No newline at end of file diff --git a/crowdsec-docs/docs/profiles/format.md b/crowdsec-docs/docs/profiles/format.md index dfdb0f7f..63ddcf5a 100644 --- a/crowdsec-docs/docs/profiles/format.md +++ b/crowdsec-docs/docs/profiles/format.md @@ -118,27 +118,36 @@ 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 +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` From 8b2c872dc458c0b0e026288a3a9c3b678806286d Mon Sep 17 00:00:00 2001 From: Laurence Date: Wed, 11 Oct 2023 16:04:33 +0100 Subject: [PATCH 5/9] Mad lad update 3 --- crowdsec-docs/docs/profiles/cti_profile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crowdsec-docs/docs/profiles/cti_profile.md b/crowdsec-docs/docs/profiles/cti_profile.md index ddab95de..087dc93b 100644 --- a/crowdsec-docs/docs/profiles/cti_profile.md +++ b/crowdsec-docs/docs/profiles/cti_profile.md @@ -65,7 +65,7 @@ decisions: on_success: break ``` -Send a notification about a potential false positive to theHive and break the alert evaluation: +Send a notification about a potential false positive and break the alert evaluation: ```yaml name: false_positive From 948234ef4155c1c4570f656f32bfa1b6c54def24 Mon Sep 17 00:00:00 2001 From: Laurence Date: Wed, 11 Oct 2023 16:12:38 +0100 Subject: [PATCH 6/9] Fix duration expr --- crowdsec-docs/docs/profiles/cti_profile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crowdsec-docs/docs/profiles/cti_profile.md b/crowdsec-docs/docs/profiles/cti_profile.md index 087dc93b..d8a2d246 100644 --- a/crowdsec-docs/docs/profiles/cti_profile.md +++ b/crowdsec-docs/docs/profiles/cti_profile.md @@ -51,7 +51,7 @@ filters: decisions: - type: ban duration: 12h -duration_expr: "Sprintf('%dm', (240 + (144 * CrowdsecCTI(Alert.GetValue()).GetBackgroundNoiseScore()))" +duration_expr: "Sprintf('%dm', (240 + (144 * CrowdsecCTI(Alert.GetValue()).GetBackgroundNoiseScore())))" ## 240 minutes (4 hours) + 144 minutes per point of background noise score ## 144 = 24 * 60 / 10 on_success: break From 155b3b9ec3451be2794e099937c7bdd6662a6f12 Mon Sep 17 00:00:00 2001 From: Laurence Date: Wed, 11 Oct 2023 16:23:03 +0100 Subject: [PATCH 7/9] Add pid profile --- crowdsec-docs/docs/profiles/cti_profile.md | 10 +++++++-- crowdsec-docs/docs/profiles/pid_profile.md | 25 ++++++++++++++++++++++ crowdsec-docs/sidebars.js | 1 + 3 files changed, 34 insertions(+), 2 deletions(-) create mode 100644 crowdsec-docs/docs/profiles/pid_profile.md diff --git a/crowdsec-docs/docs/profiles/cti_profile.md b/crowdsec-docs/docs/profiles/cti_profile.md index d8a2d246..56506ac4 100644 --- a/crowdsec-docs/docs/profiles/cti_profile.md +++ b/crowdsec-docs/docs/profiles/cti_profile.md @@ -4,12 +4,16 @@ title: CrowdSec CTI sidebar_position: 1 --- -Here is an example of a profile that uses the CTI module to make decisions based on the background noise score of an IP address. +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 @@ -65,7 +69,9 @@ decisions: on_success: break ``` -Send a notification about a potential false positive and break the alert evaluation: +### Potential False Triggers + +Send a notification about a potential false triggers and break the alert evaluation: ```yaml name: false_positive diff --git a/crowdsec-docs/docs/profiles/pid_profile.md b/crowdsec-docs/docs/profiles/pid_profile.md new file mode 100644 index 00000000..4e07c3be --- /dev/null +++ b/crowdsec-docs/docs/profiles/pid_profile.md @@ -0,0 +1,25 @@ +--- +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. + +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 +--- +``` \ No newline at end of file diff --git a/crowdsec-docs/sidebars.js b/crowdsec-docs/sidebars.js index 5bf99ade..6ec92e82 100644 --- a/crowdsec-docs/sidebars.js +++ b/crowdsec-docs/sidebars.js @@ -299,6 +299,7 @@ items: [ "profiles/cti_profile", "profiles/captcha_profile", + "profiles/pid_profile", ], } ], From 051305c19857b55bcb825f9c1935e24a455f963f Mon Sep 17 00:00:00 2001 From: Laurence Date: Wed, 11 Oct 2023 16:24:26 +0100 Subject: [PATCH 8/9] Add collections free promo ;) --- crowdsec-docs/docs/profiles/pid_profile.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/crowdsec-docs/docs/profiles/pid_profile.md b/crowdsec-docs/docs/profiles/pid_profile.md index 4e07c3be..eaa3a285 100644 --- a/crowdsec-docs/docs/profiles/pid_profile.md +++ b/crowdsec-docs/docs/profiles/pid_profile.md @@ -10,6 +10,10 @@ 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 From e9c1f7764a2f2e87d89be9bdddfa59582d2e5bb0 Mon Sep 17 00:00:00 2001 From: Laurence Date: Thu, 12 Oct 2023 09:30:35 +0100 Subject: [PATCH 9/9] Update scoring --- crowdsec-docs/docs/profiles/cti_profile.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/crowdsec-docs/docs/profiles/cti_profile.md b/crowdsec-docs/docs/profiles/cti_profile.md index 56506ac4..753cdff1 100644 --- a/crowdsec-docs/docs/profiles/cti_profile.md +++ b/crowdsec-docs/docs/profiles/cti_profile.md @@ -55,9 +55,9 @@ filters: decisions: - type: ban duration: 12h -duration_expr: "Sprintf('%dm', (240 + (144 * CrowdsecCTI(Alert.GetValue()).GetBackgroundNoiseScore())))" -## 240 minutes (4 hours) + 144 minutes per point of background noise score -## 144 = 24 * 60 / 10 +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 @@ -88,4 +88,4 @@ decisions: - type: ban duration: 4h on_success: break -``` \ No newline at end of file +```