From 9b694244c466daab8fec38f5c0bdabfb1e20fdcd Mon Sep 17 00:00:00 2001
From: Laurence Jones <laurence.jones@live.co.uk>
Date: Thu, 26 Dec 2024 13:19:23 +0000
Subject: [PATCH] enhancement: Add information about environment variables in
 the notificiations (#702)

* enhancement: Add information about environment variables in the notification plugins

* enhancement: concise information
---
 .../local_api/notification_plugins/intro.md   | 31 +++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/crowdsec-docs/docs/local_api/notification_plugins/intro.md b/crowdsec-docs/docs/local_api/notification_plugins/intro.md
index 5b8d42e9..0e9d29d7 100644
--- a/crowdsec-docs/docs/local_api/notification_plugins/intro.md
+++ b/crowdsec-docs/docs/local_api/notification_plugins/intro.md
@@ -27,6 +27,22 @@ CrowdSec rejects the plugins binaries if one of the following is true :
 
 It is possible to set configuration values based on environment variables.
 
+However, depending on which key is using the environment variable, the syntax is different.
+
+#### Format
+
+The `format` key is a string that uses the [go template](https://pkg.go.dev/text/template) syntax. To use an environment variable in the `format` key, you can use the `env` function provided by [sprig](https://masterminds.github.io/sprig/).
+
+```yaml
+format: |
+    Received {{ len . }} alerts
+    Environment variable value: {{env "ENV_VAR"}}
+```
+
+#### Other keys
+
+All other keys than `format` can use the typical `${ENV_VAR}` or `$ENV_VAR` syntax.
+
 For example, if you don't want to store your SMTP host password in the configuration file, you can do this:
 
 ```yaml
@@ -40,6 +56,21 @@ sender_email: email@gmail.com
 email_subject: "CrowdSec Notification"
 ```
 
+:::warning
+Please note that `cscli notifications inspect` command does not interpolate environment variables and will always show the raw value of the key.
+:::
+
+If you wish to use `cscli notifications test` command, you must provide the environment variables in the command line or within your shell environment.
+
+For example, if you have a `SMTP_PASSWORD` environment variable, you can test the `email_default` plugin with the following command:
+
+:::warning
+Some shells may hold this information in history, so please consult your shell documentation to ensure that the password or other sensitive data is not stored in clear text.
+:::
+
+```bash 
+SMTP_PASSWORD=your_password cscli notifications test email_default
+```
 
 ### Registering plugin to profile