Skip to content

Commit 064518d

Browse files
LaurenceJJonesLaurenceJJones
authored
enhance: add new testing section and refactor the structure (#630)
1 parent 30b5144 commit 064518d

12 files changed

Lines changed: 660 additions & 186 deletions

File tree

‎crowdsec-docs/docs/notification_plugins/elasticsearch.md‎

Lines changed: 65 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,20 @@ id: elastic
33
title: Elasticsearch
44
---
55

6-
Elasticsearch can be integrated with CrowdSec by using the HTTP plugin. Enable it by following these [instructions](/notification_plugins/http.md) .
6+
CrowdSec can forward Alerts to Elasticsearch using the HTTP plugin. This guide will show you how to configure the plugin to send alerts to your Elasticsearch instance.
7+
8+
## Configuring the plugin
9+
10+
By default the configuration for HTTP plugin is located at these default location per OS:
11+
12+
- **Linux** `/etc/crowdsec/notifications/http.yaml`
13+
- **FreeBSD** `/usr/local/etc/crowdsec/notifications/http.yaml`
14+
- **Windows** `C:\ProgramData\CrowdSec\config\notifications\http.yaml`
715

816
Then replace the `url` and the `format` of the plugin's config so that it posts the events to your Elasticsearch instance.
917

18+
### Base configuration
19+
1020
An example configuration:
1121

1222
```yaml
@@ -29,7 +39,7 @@ headers:
2939
```
3040
3141
32-
## Authentication
42+
### Authentication
3343
3444
If you have enabled security on your elasticsearch cluster, you will have to add a custom `Authorization` header to be able to insert the events.
3545

@@ -61,7 +71,7 @@ headers:
6171
```
6272

6373

64-
## Self-Signed certificate
74+
### Self-Signed certificate
6575

6676
If your elasticsearch cluster uses a self-signed certificate, you must set `skip_tls_verification` to `true` in your configuration:
6777
```yaml
@@ -84,7 +94,7 @@ headers:
8494
8595
```
8696

87-
## Potential mapping issues
97+
### Potential mapping issues
8898

8999
If you are facing errors because mapper complains about field types inference, ie:
90100

@@ -355,6 +365,57 @@ headers:
355365
Authorization: "Basic [redacted]"
356366
```
357367

368+
## Testing the plugin
369+
370+
Before enabling the plugin it is best to test the configuration so the configuration is validated and you can see the output of the plugin.
371+
372+
```bash
373+
cscli notifications test http_default
374+
```
375+
376+
:::note
377+
If you have changed the `name` property in the configuration file, you should replace `http_default` with the new name.
378+
:::
379+
380+
## Enabling the plugin
381+
382+
In your profiles you will need to uncomment the `notifications` key and the `http_default` plugin list item.
383+
384+
```
385+
#notifications:
386+
# - http_default
387+
```
388+
389+
:::note
390+
If you have changed the `name` property in the configuration file, you should replace `http_default` with the new name.
391+
:::
392+
393+
:::warning
394+
Ensure your YAML is properly formatted the `notifications` key should be at the top level of the profile.
395+
:::
396+
397+
<details>
398+
399+
<summary>Example profile with http plugin enabled</summary>
400+
401+
```yaml
402+
name: default_ip_remediation
403+
#debug: true
404+
filters:
405+
- Alert.Remediation == true && Alert.GetScope() == "Ip"
406+
decisions:
407+
- type: ban
408+
duration: 4h
409+
#duration_expr: Sprintf('%dh', (GetDecisionsCount(Alert.GetValue()) + 1) * 4)
410+
#highlight-next-line
411+
notifications:
412+
#highlight-next-line
413+
- http_default
414+
on_success: break
415+
```
416+
417+
</details>
418+
358419
## Final Steps:
359420

360421
Let's restart crowdsec

‎crowdsec-docs/docs/notification_plugins/email.md‎

Lines changed: 75 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,27 +3,19 @@ id: email
33
title: Email Plugin
44
---
55

6-
The Email plugin is shipped by default with CrowdSec. This guide shows how to enable it.
6+
The Email plugin is shipped by default with CrowdSec. The following guide shows how to configure, test and enable it.
77

8-
## Enabling the plugin:
8+
## Configuring the plugin
99

10-
In the profile configuration (by default `/etc/crowdsec/profiles.yaml`) , uncomment the section:
10+
By default the configuration for Email plugin is located at these default location per OS:
1111

12-
```
13-
#notifications:
14-
# - email_default
15-
```
16-
17-
Every alert that passes the profile's filter will be dispatched to the `email_default` plugin.
12+
- **Linux** `/etc/crowdsec/notifications/email.yaml`
13+
- **FreeBSD** `/usr/local/etc/crowdsec/notifications/email.yaml`
14+
- **Windows** `C:\ProgramData\CrowdSec\config\notifications\email.yaml`
1815

19-
## Configuring the plugin:
16+
### Base configuration
2017

21-
The default configuration for the email plugin is located at `/etc/crowdsec/notifications/email.yaml`.
22-
You need to provide the credentials for the SMTP server here.
23-
24-
### Example configuration for Gmail
25-
26-
Here's an example configuration that sends alerts to `receiver@gmail.com`:
18+
Here is the base configuration for the Email plugin:
2719

2820
```yaml
2921
type: email # Don't change
@@ -84,12 +76,77 @@ encryption_type: "ssltls"
8476

8577
The `format` configuration directive is a [go template](https://pkg.go.dev/text/template), which receives a list of [Alert](https://pkg.go.dev/github.com/crowdsecurity/crowdsec@master/pkg/models#Alert) objects.
8678

79+
Typical port and TLS/SSL settings
80+
81+
| Port | Encryption Type |
82+
|------|-----------------|
83+
| 25 | none |
84+
| 465 | ssltls |
85+
| 587 | starttls |
86+
87+
:::warning
88+
Port 25 should be avoided at all costs as it is commonly blocked by ISPs and email providers and is insecure as it sends in plain text.
89+
:::
90+
91+
:::info
92+
Port settings above are common, but may vary depending on your email provider. Please refer to your email provider's documentation for the correct settings.
93+
:::
94+
95+
## Testing the plugin
96+
97+
Before enabling the plugin it is best to test the configuration so the configuration is validated and you can see the output of the plugin.
98+
99+
```bash
100+
cscli notifications test email_default
101+
```
102+
103+
:::note
104+
If you have changed the `name` property in the configuration file, you should replace `email_default` with the new name.
105+
:::
106+
107+
## Enabling the plugin
108+
109+
In your profiles you will need to uncomment the `notifications` key and the `email_default` plugin list item.
110+
111+
```
112+
#notifications:
113+
# - email_default
114+
```
115+
116+
:::note
117+
If you have changed the `name` property in the configuration file, you should replace `email_default` with the new name.
118+
:::
119+
120+
:::warning
121+
Ensure your YAML is properly formatted the `notifications` key should be at the top level of the profile.
122+
:::
123+
124+
<details>
125+
126+
<summary>Example profile with email plugin enabled</summary>
127+
128+
```yaml
129+
name: default_ip_remediation
130+
#debug: true
131+
filters:
132+
- Alert.Remediation == true && Alert.GetScope() == "Ip"
133+
decisions:
134+
- type: ban
135+
duration: 4h
136+
#duration_expr: Sprintf('%dh', (GetDecisionsCount(Alert.GetValue()) + 1) * 4)
137+
#highlight-next-line
138+
notifications:
139+
#highlight-next-line
140+
- email_default
141+
on_success: break
142+
```
143+
144+
</details>
145+
87146
## Final Steps:
88147
89148
Restart CrowdSec with the following command:
90149
91150
```bash
92151
sudo systemctl restart crowdsec
93152
```
94-
95-
To verify if the plugin is functioning correctly, you can trigger scenarios using tools like wapiti, nikto etc.

‎crowdsec-docs/docs/notification_plugins/file.md‎

Lines changed: 61 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -3,26 +3,19 @@ id: file
33
title: File Plugin
44
---
55

6-
The File plugin is by default shipped with your CrowdSec installation. The following guide shows how to enable it.
6+
The File plugin is by default shipped with your CrowdSec installation and allows you to write Alerts to an external file that can be monitored by external applications. The following guide shows how to configure, test and enable it.
77

8-
## Enabling the plugin:
8+
## Configuring the plugin
99

10-
In your profile file (by default `/etc/crowdsec/profiles.yaml`) , uncomment the section
10+
By default the configuration for Email plugin is located at these default location per OS:
1111

12-
```
13-
#notifications:
14-
# - file_default
15-
```
16-
17-
Every alert which would pass the profile's filter would be dispatched to `file_default` plugin.
12+
- **Linux** `/etc/crowdsec/notifications/file.yaml`
13+
- **FreeBSD** `/usr/local/etc/crowdsec/notifications/file.yaml`
14+
- **Windows** `C:\ProgramData\CrowdSec\config\notifications\file.yaml`
1815

19-
## Configuring the plugin:
16+
### Base configuration
2017

21-
By default the configuration for File plugin is located at `/etc/crowdsec/notifications/file.yaml`.
22-
23-
### Adding the plugin configuration
24-
25-
Example config which writes a ndjson file to `/tmp/crowdsec_alerts.json`.
18+
Example config which writes Alerts to a file using NDJson (**N**ewline **D**elimiter **J**ava**S**cript **O**bject **N**otation) format to `/tmp/crowdsec_alerts.json`.
2619

2720
```yaml
2821
# Don't change this
@@ -56,9 +49,9 @@ rotate:
5649
Some SIEM agents may not support some top level keys we define in the default ndjson format. Please make sure to adjust the format to match your SIEM agent's requirements.
5750
:::
5851

59-
## SIEM Integration
52+
### SIEM Integration
6053

61-
### Filebeat
54+
#### Filebeat
6255

6356
Filebeat has a set of reserved top level keys and should not be used in the ndjson format. The following format can be used to be compatible with Filebeat:
6457

@@ -69,12 +62,61 @@ format: |
6962
{{ end -}}
7063
```
7164

65+
## Testing the plugin
66+
67+
Before enabling the plugin it is best to test the configuration so the configuration is validated and you can see the output of the plugin.
68+
69+
```bash
70+
cscli notifications test file_default
71+
```
72+
73+
:::note
74+
If you have changed the `name` property in the configuration file, you should replace `file_default` with the new name.
75+
:::
76+
77+
## Enabling the plugin
78+
79+
In your profiles you will need to uncomment the `notifications` key and the `file_default` plugin list item.
80+
81+
```
82+
#notifications:
83+
# - file_default
84+
```
85+
86+
:::note
87+
If you have changed the `name` property in the configuration file, you should replace `file_default` with the new name.
88+
:::
89+
90+
:::warning
91+
Ensure your YAML is properly formatted the `notifications` key should be at the top level of the profile.
92+
:::
93+
94+
<details>
95+
96+
<summary>Example profile with file plugin enabled</summary>
97+
98+
```yaml
99+
name: default_ip_remediation
100+
#debug: true
101+
filters:
102+
- Alert.Remediation == true && Alert.GetScope() == "Ip"
103+
decisions:
104+
- type: ban
105+
duration: 4h
106+
#duration_expr: Sprintf('%dh', (GetDecisionsCount(Alert.GetValue()) + 1) * 4)
107+
#highlight-next-line
108+
notifications:
109+
#highlight-next-line
110+
- file_default
111+
on_success: break
112+
```
113+
114+
</details>
115+
72116
## Final Steps:
73117

74118
Let's restart crowdsec
75119

76120
```bash
77121
sudo systemctl restart crowdsec
78122
```
79-
80-
You can verify whether the plugin is properly working by triggering scenarios using tools like wapiti, nikto etc.

0 commit comments

Comments
 (0)