Skip to main content
Version: Next

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 writting, plugins exists for slack, splunk, and a generic http push plugin (allowing to push to services such as elasticsearch).

Events get dispatched to said plugins via profile configuration.

Configuration#

The default plugins are shipped with crowdsec uppon 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.md).

Plugin binaries are present in config_paths.plugin_dir (defaults to /var/lib/crowdsec/plugins/), and their individual configuration are present in config_paths.notification_dir (defaults to /etc/crowdsec/notifications/)

Important: CrowdSec rejects the plugins if one of the following is true :

  1. plugin is not owned by the root user and root group.
  2. 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: truefilters: - Alert.Remediation == true && Alert.GetScope() == "Ip"decisions: - type: ban   duration: 4hon_success: breaknotifications: - 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, 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": "127.0.0.1"      }    ],    "events": [      {        "meta": [          {            "key": "target_user",            "value": "test0"          },          {            "key": "service",            "value": "ssh"          },          {            "key": "source_ip",            "value": "127.0.0.1"          },          {            "key": "IsInEU",            "value": "false"          },          {            "key": "ASNNumber",            "value": "0"          },          {            "key": "datasource_path",            "value": "/var/log/auth.log"          },          {            "key": "datasource_type",            "value": "file"          },          {            "key": "log_type",            "value": "ssh_failed-auth"          }        ],        "timestamp": "2021-09-17T15:16:45Z"      },      {        "meta": [          {            "key": "source_ip",            "value": "127.0.0.1"          },          {            "key": "IsInEU",            "value": "false"          },          {            "key": "ASNNumber",            "value": "0"          },          {            "key": "datasource_path",            "value": "/var/log/auth.log"          },          {            "key": "datasource_type",            "value": "file"          },          {            "key": "log_type",            "value": "ssh_failed-auth"          },          {            "key": "target_user",            "value": "test1"          },          {            "key": "service",            "value": "ssh"          }        ],        "timestamp": "2021-09-17T15:16:45Z"      },      {        "meta": [          {            "key": "service",            "value": "ssh"          },          {            "key": "source_ip",            "value": "127.0.0.1"          },          {            "key": "IsInEU",            "value": "false"          },          {            "key": "ASNNumber",            "value": "0"          },          {            "key": "datasource_path",            "value": "/var/log/auth.log"          },          {            "key": "datasource_type",            "value": "file"          },          {            "key": "log_type",            "value": "ssh_failed-auth"          },          {            "key": "target_user",            "value": "test2"          }        ],        "timestamp": "2021-09-17T15:16:45Z"      },      {        "meta": [          {            "key": "IsInEU",            "value": "false"          },          {            "key": "ASNNumber",            "value": "0"          },          {            "key": "datasource_path",            "value": "/var/log/auth.log"          },          {            "key": "datasource_type",            "value": "file"          },          {            "key": "log_type",            "value": "ssh_failed-auth"          },          {            "key": "target_user",            "value": "test3"          },          {            "key": "service",            "value": "ssh"          },          {            "key": "source_ip",            "value": "127.0.0.1"          }        ],        "timestamp": "2021-09-17T15:16:45Z"      },      {        "meta": [          {            "key": "IsInEU",            "value": "false"          },          {            "key": "ASNNumber",            "value": "0"          },          {            "key": "datasource_path",            "value": "/var/log/auth.log"          },          {            "key": "datasource_type",            "value": "file"          },          {            "key": "log_type",            "value": "ssh_failed-auth"          },          {            "key": "target_user",            "value": "test4"          },          {            "key": "service",            "value": "ssh"          },          {            "key": "source_ip",            "value": "127.0.0.1"          }        ],        "timestamp": "2021-09-17T15:16:45Z"      },      {        "meta": [          {            "key": "service",            "value": "ssh"          },          {            "key": "source_ip",            "value": "127.0.0.1"          },          {            "key": "IsInEU",            "value": "false"          },          {            "key": "ASNNumber",            "value": "0"          },          {            "key": "datasource_path",            "value": "/var/log/auth.log"          },          {            "key": "datasource_type",            "value": "file"          },          {            "key": "log_type",            "value": "ssh_failed-auth"          },          {            "key": "target_user",            "value": "test5"          }        ],        "timestamp": "2021-09-17T15:16:45Z"      }    ],    "events_count": 6,    "labels": null,    "leakspeed": "10s",    "message": "Ip 127.0.0.1 performed crowdsecurity/ssh-bf (6 events over 1.724382ms) at 2021-09-17 15:16:45.546369168 +0200 CEST m=+6.938040226",    "remediation": true,    "scenario": "crowdsecurity/ssh-bf",    "scenario_hash": "4441dcff07020f6690d998b7101e642359ba405c2abb83565bbbdcee36de280f",    "scenario_version": "0.1",    "simulated": false,    "source": {      "ip": "127.0.0.1",      "scope": "Ip",      "value": "127.0.0.1"    },    "start_at": "2021-09-17T15:16:45.544645047+02:00",    "stop_at": "2021-09-17T15:16:45.546369459+02:00"  }]

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}}    ] }