Skip to main content
Version: v1.2

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

warning

The default profile will not forward manual decisions (cscli decisions add -i x.x.x.x) to the notification plugins. You may want to create notification-only profiles.

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).

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: 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.

Creating notification-only profile

As manual decisions come up with their own decisions (user can specify duration etc.), they are not getting through the profile nor notifications. If you want to add notification for manual IP decisions for exemple, adding this to your profile would work :

---
name: notify_only
#debug: true
filters:
- Alert.Remediation == false && Alert.GetScope() == "Ip"
notifications:
- slack_default # Set the webhook in /etc/crowdsec/notifications/slack.yaml before enabling this.
on_success: break

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