Introduction
Goal
CrowdSec supports notification plugins, meant to be able to push alerts to third party services for alerting or integration purposes. At the time of writing, plugins exists for slack, splunk, and a generic http push plugin (allowing to push to services such as elasticsearch).
Plugins are defined at LAPI level. Events get dispatched to said plugins via profile configuration.
Configuration
The default plugins are shipped with CrowdSec upon installation, and can trivially be enabled without further installation.
Refer directly to each plugin's dedicated documentation and keep in mind that plugins needs to be enabled/dispatched at the profile level via the dedicated notifications section (defaults to /etc/crowdsec/profiles.yaml).
Plugin binaries are present in config_paths.plugin_dir (defaults to /var/lib/crowdsec/plugins/ or /usr/lib64/crowdsec/plugins/ depending on your Linux distribution), and their individual configuration are present in config_paths.notification_dir (defaults to /etc/crowdsec/notifications/). Verify the paths in /etc/crowdsec/config.yaml before registering a plugin.
Important: CrowdSec rejects the plugins if one of the following is true :
- plugin is not owned by the root user and root group.
- plugin is world-writable.
Registering plugin to profile
After discovering the plugins, CrowdSec registers the plugins to the profiles. Here's a profile which sends alerts to plugin named slackreport.
name: default_ip_remediation
#debug: true
filters:
- Alert.Remediation == true && Alert.GetScope() == "Ip"
decisions:
- type: ban
duration: 4h
on_success: break
notifications:
- slackreport
Note: In this case CrowdSec will map the plugin slackreport to the plugin config which has name=slackreport. See next section for more details.
Notification plugin configuration:
Following are the fields CrowdSec main process can interpret.
type:
name:
format:
group_wait:
group_threshold:
max_retry:
timeout:
type :
Required. Type of plugin, eg "slack"
name :
Required. Name of this config eg "slackreport". This should match with registered name in profile.
format :
Required. go template, which is fed a list of Alert objects. The go templates provide additional directives provide by sprig . eg "Received {{.len}} alerts"
group_wait :
Optional. duration to wait collecting alerts before sending to this plugin, eg "30s"
group_threshold :
Optional. if alerts exceed this, then the plugin will be sent the message. eg "10"
max_retry :
Optional. the number of tries to attempt to send message to plugins in case of error.
timeout :
Optional. duration to wait for a response from the plugin before considering this attempt a failure. eg "10s"
You can define other plugin specific fields too. eg webhook field for a slack plugin.
Dispatching configuration:
CrowdSec main process feeds the configuration files to the plugins via gRPC. It determines where to send the config via the value of type field in config file.
Architecture and technical considerations
Architecture
Under the hood, the main CrowdSec process dispatches the plugins as gRPC services. This means that plugins can be written in any language.
Currently only notification plugins are supported. Whenever CrowdSec receives any alert and if this alert satisfies the owner profile, then the same alert will be dispatched to such plugin.
See the gRPC protocol for notification plugins.
Plugin Discovery
Plugins are discovered from the directories specified in /etc/crowdsec/config.yaml.
#/etc/crowdsec/config.yaml
.....
config_paths:
notification_dir: /etc/crowdsec/notifications/
plugin_dir: /var/lib/crowdsec/plugins/
.....
Plugin Process Owner
Due to security reasons, plugins are ideally ran with dropped priveleges. This is done by setting owner and group of the plugin process as some unprivileged user. This can be configured via setting the desired user and group in /etc/crowdsec/config.yaml.
#/etc/crowdsec/config.yaml
.....
plugin_config:
user: nobody
group: nogroup
.....
Alert object
You have access to the list of alerts that triggered the notification when writing the go-template in the format parameter.
An alert is defined as follow:
type Alert struct {
Capacity *int32 `json:"capacity"`
CreatedAt string `json:"created_at,omitempty"`
Decisions []*Decision `json:"decisions"`
Events []*Event `json:"events"`
EventsCount *int32 `json:"events_count"`
ID int64 `json:"id,omitempty"`
Labels []string `json:"labels"`
Leakspeed *string `json:"leakspeed"`
MachineID string `json:"machine_id,omitempty"`
Message *string `json:"message"`
Meta Meta `json:"meta,omitempty"`
Remediation bool `json:"remediation,omitempty"`
Scenario *string `json:"scenario"`
ScenarioHash *string `json:"scenario_hash"`
ScenarioVersion *string `json:"scenario_version"`
Simulated *bool `json:"simulated"`
Source *Source `json:"source"`
StartAt *string `json:"start_at"`
StopAt *string `json:"stop_at"`
}
Here is a full example of an Alert object list available in the go-template (this example was generated by a SSH bruteforce).
Note that this was generated using the toJson sprig function, so field names are a bit different from the actual names in the go object.
To use them in a go-template, you can check here to get the actual field names.
[
{
"capacity": 5,
"decisions": [
{
"duration": "4h",
"origin": "crowdsec",
"scenario": "crowdsecurity/ssh-bf",
"scope": "Ip",
"type": "ban",
"value": "35.188.49.176"
}
],
"events": [
{
"meta": [
{
"key": "ASNNumber",
"value": "15169"
},
{
"key": "ASNOrg",
"value": "Google LLC"
},
{
"key": "IsInEU",
"value": "false"
},
{
"key": "IsoCode",
"value": "US"
},
{
"key": "SourceRange",
"value": "35.184.0.0/13"
},
{
"key": "datasource_path",
"value": "ssh-bf.log"
},
{
"key": "datasource_type",
"value": "file"
},
{
"key": "log_type",
"value": "ssh_failed-auth"
},
{
"key": "machine",
"value": "sd-126005"
},
{
"key": "service",
"value": "ssh"
},
{
"key": "source_ip",
"value": "35.188.49.176"
},
{
"key": "target_user",
"value": "pascal"
},
{
"key": "timestamp",
"value": "2022-02-12T14:10:21Z"
}
],
"timestamp": "2022-02-12T14:10:23Z"
},
{
"meta": [
{
"key": "ASNNumber",
"value": "15169"
},
{
"key": "ASNOrg",
"value": "Google LLC"
},
{
"key": "IsInEU",
"value": "false"
},
{
"key": "IsoCode",
"value": "US"
},
{
"key": "SourceRange",
"value": "35.184.0.0/13"
},
{
"key": "datasource_path",
"value": "ssh-bf.log"
},
{
"key": "datasource_type",
"value": "file"
},
{
"key": "log_type",
"value": "ssh_failed-auth"
},
{
"key": "machine",
"value": "sd-126005"
},
{
"key": "service",
"value": "ssh"
},
{
"key": "source_ip",
"value": "35.188.49.176"
},
{
"key": "target_user",
"value": "pascal1"
},
{
"key": "timestamp",
"value": "2022-02-12T14:10:21Z"
}
],
"timestamp": "2022-02-12T14:10:23Z"
},
{
"meta": [
{
"key": "ASNNumber",
"value": "15169"
},
{
"key": "ASNOrg",
"value": "Google LLC"
},
{
"key": "IsInEU",
"value": "false"
},
{
"key": "IsoCode",
"value": "US"
},
{
"key": "SourceRange",
"value": "35.184.0.0/13"
},
{
"key": "datasource_path",
"value": "ssh-bf.log"
},
{
"key": "datasource_type",
"value": "file"
},
{
"key": "log_type",
"value": "ssh_failed-auth"
},
{
"key": "machine",
"value": "sd-126005"
},
{
"key": "service",
"value": "ssh"
},
{
"key": "source_ip",
"value": "35.188.49.176"
},
{
"key": "target_user",
"value": "pascal2"
},
{
"key": "timestamp",
"value": "2022-02-12T14:10:22Z"
}
],
"timestamp": "2022-02-12T14:10:23Z"
},
{
"meta": [
{
"key": "ASNNumber",
"value": "15169"
},
{
"key": "ASNOrg",
"value": "Google LLC"
},
{
"key": "IsInEU",
"value": "false"
},
{
"key": "IsoCode",
"value": "US"
},
{
"key": "SourceRange",
"value": "35.184.0.0/13"
},
{
"key": "datasource_path",
"value": "ssh-bf.log"
},
{
"key": "datasource_type",
"value": "file"
},
{
"key": "log_type",
"value": "ssh_failed-auth"
},
{
"key": "machine",
"value": "sd-126005"
},
{
"key": "service",
"value": "ssh"
},
{
"key": "source_ip",
"value": "35.188.49.176"
},
{
"key": "target_user",
"value": "pascal3"
},
{
"key": "timestamp",
"value": "2022-02-12T14:10:22Z"
}
],
"timestamp": "2022-02-12T14:10:23Z"
},
{
"meta": [
{
"key": "ASNNumber",
"value": "15169"
},
{
"key": "ASNOrg",
"value": "Google LLC"
},
{
"key": "IsInEU",
"value": "false"
},
{
"key": "IsoCode",
"value": "US"
},
{
"key": "SourceRange",
"value": "35.184.0.0/13"
},
{
"key": "datasource_path",
"value": "ssh-bf.log"
},
{
"key": "datasource_type",
"value": "file"
},
{
"key": "log_type",
"value": "ssh_failed-auth"
},
{
"key": "machine",
"value": "sd-126005"
},
{
"key": "service",
"value": "ssh"
},
{
"key": "source_ip",
"value": "35.188.49.176"
},
{
"key": "target_user",
"value": "pascal4"
},
{
"key": "timestamp",
"value": "2022-02-12T14:10:23Z"
}
],
"timestamp": "2022-02-12T14:10:23Z"
},
{
"meta": [
{
"key": "ASNNumber",
"value": "15169"
},
{
"key": "ASNOrg",
"value": "Google LLC"
},
{
"key": "IsInEU",
"value": "false"
},
{
"key": "IsoCode",
"value": "US"
},
{
"key": "SourceRange",
"value": "35.184.0.0/13"
},
{
"key": "datasource_path",
"value": "ssh-bf.log"
},
{
"key": "datasource_type",
"value": "file"
},
{
"key": "log_type",
"value": "ssh_failed-auth"
},
{
"key": "machine",
"value": "sd-126005"
},
{
"key": "service",
"value": "ssh"
},
{
"key": "source_ip",
"value": "35.188.49.176"
},
{
"key": "target_user",
"value": "pascal5"
},
{
"key": "timestamp",
"value": "2022-02-12T14:10:23Z"
}
],
"timestamp": "2022-02-12T14:10:23Z"
}
],
"events_count": 6,
"labels": null,
"leakspeed": "10s",
"machine_id": "4e1c7990a4af460a9c622d2c80a856334U2v5NbKX14uQKFa",
"message": "Ip 35.188.49.176 performed 'crowdsecurity/ssh-bf' (6 events over 2s) at 2022-02-12 14:10:23 +0000 UTC",
"remediation": true,
"scenario": "crowdsecurity/ssh-bf",
"scenario_hash": "4441dcff07020f6690d998b7101e642359ba405c2abb83565bbbdcee36de280f",
"scenario_version": "0.1",
"simulated": false,
"source": {
"as_name": "Google LLC",
"as_number": "15169",
"cn": "US",
"ip": "35.188.49.176",
"latitude": 37.4192,
"longitude": -122.0574,
"range": "35.184.0.0/13",
"scope": "Ip",
"value": "35.188.49.176"
},
"start_at": "2022-02-12T14:10:21Z",
"stop_at": "2022-02-12T14:10:23Z"
}
]
Usage examples
Convert the whole list to JSON format:
{{ .|toJson }}
Extract all the decisions in the alerts list
{{ range . }}
{{ range .Decisions }}
{{ .Value }} has performed {{.Scenario}} and has received "{{.Type}}" for {{.Duration}}
{{ end }}
{{ end }}
Extract the meta associated with the alerts
{{ range .}}
{{.Source.Value}} has performed {{.Scenario}} (meta : {{range .Events}} {{range .Meta}} {{.Key}} : {{.Value}} | {{end}} -- {{ end }})
{{ end }}
Teams webhook
{
"$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.0",
"body": [
{{range .}}
{{ $decisions_len := len .Decisions }}
{
"type": "TextBlock",
"text": "Attack start: {{.StartAt}}"
},
{
"type": "TextBlock",
"text": "Attack End: {{.StopAt}}"
},
{{ range $index, $element := .Decisions }}
{
"type": "TextBlock",
"text": "{{$element.Value}} performed {{$element.Scenario}} and got a {{$element.Duration}} {{$element.Type}}"
}
{{ if lt $index (sub $decisions_len 1) }}
,
{{ end }}
{{ end }}
{{end}}
]
}
