refactor(alertsenders/mail): Move template rendering to sender

HTML templates are more likely to exclusively be used
by the mail sender. For this purpose, a new config flag
is defined that determines if the alert is sent with
HTML template or plain text. Alert structure is augmented
with labels and description fields to make it compatible
with the same fields available in the filter config.

Author: rabbitstack

configs/fibratus.yml

@@ -56,6 +56,9 @@ alertsenders:
     # Specifies the email body content type
     #content-type: text/html
 
+    # Indicates if the alert is rendered with HTML template
+    #use-template: true
+
   # Slack sender transports the alerts to the Slack workspace.
   slack:
     # Enables/disables Slack alert sender

pkg/alertsender/alert.go

@@ -86,6 +86,12 @@ type Alert struct {
 	Text string
 	// Tags contains a sequence of tags for categorizing the alerts.
 	Tags []string
+	// Labels is an arbitrary collection of key-value pairs.
+	Labels map[string]string
+	// Description represents a longer explanation of the alert. It is
+	// typically a description of adversary tactics, techniques or any
+	// information valuable to the analyst.
+	Description string
 	// Severity determines the severity of this alert.
 	Severity Severity
 	// Events contains a list of events that trigger the alert.

pkg/alertsender/mail/config.go

@@ -29,6 +29,7 @@ const (
 	to          = "alertsenders.mail.to"
 	enabled     = "alertsenders.mail.enabled"
 	contentType = "alertsenders.mail.content-type"
+	useTemplate = "alertsenders.mail.use-template"
 )
 
 // Config contains the configuration for the mail alert sender.
@@ -37,7 +38,7 @@ type Config struct {
 	Host string `mapstructure:"host"`
 	// Port is the port of the SMTP server.
 	Port int `mapstructure:"port"`
-	// User specifies the user name when authenticating to the SMTP server.
+	// User specifies the username when authenticating to the SMTP server.
 	User string `mapstructure:"user"`
 	// Pass specifies the password when authenticating to the SMTP server.
 	Pass string `mapstructure:"password"`
@@ -49,6 +50,9 @@ type Config struct {
 	Enabled bool `mapstructure:"enabled"`
 	// ContentType represents the email body content type.
 	ContentType string `mapstructure:"content-type"`
+	// UseTemplate indicates if the alert is rendered with HTML template.
+	// If set to false, the plain text email is sent instead.
+	UseTemplate bool `mapstructure:"use-template"`
 }
 
 // AddFlags registers persistent flags.
@@ -61,4 +65,5 @@ func AddFlags(flags *pflag.FlagSet) {
 	flags.StringSlice(to, []string{}, "Specifies all the recipients that'll receive the alert")
 	flags.Bool(enabled, false, "Indicates whether mail alert sender is enabled")
 	flags.String(contentType, "text/html", "Represents the email body content type")
+	flags.Bool(useTemplate, true, "Indicates if the alert is rendered with HTML template")
 }

pkg/alertsender/mail/mail.go

@@ -48,18 +48,34 @@ func (s mail) Send(alert alertsender.Alert) error {
 		return err
 	}
 	defer sender.Close()
-	return gomail.Send(sender, s.composeMessage(s.c.From, s.c.To, alert))
+	msg, err := s.composeMessage(s.c.From, s.c.To, alert)
+	if err != nil {
+		return err
+	}
+	return gomail.Send(sender, msg)
 }
 
 func (s mail) Type() alertsender.Type { return alertsender.Mail }
 func (s mail) Shutdown() error        { return nil }
 func (s mail) SupportsMarkdown() bool { return true }
 
-func (s mail) composeMessage(from string, to []string, alert alertsender.Alert) *gomail.Message {
+func (s mail) composeMessage(from string, to []string, alert alertsender.Alert) (*gomail.Message, error) {
 	msg := gomail.NewMessage()
 	msg.SetHeader("From", from)
 	msg.SetHeader("To", to...)
 	msg.SetHeader("Subject", alert.Title)
-	msg.SetBody(s.c.ContentType, alert.Text)
-	return msg
+
+	body := alert.Text
+
+	var err error
+	if s.c.UseTemplate {
+		body, err = renderHTMLTemplate(alert)
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	msg.SetBody(s.c.ContentType, body)
+
+	return msg, nil
 }

pkg/alertsender/renderer/renderer.go renamed to pkg/alertsender/mail/renderer.go

@@ -16,36 +16,34 @@
  * limitations under the License.
  */
 
-package renderer
+package mail
 
 import (
 	"bytes"
 	"github.com/Masterminds/sprig/v3"
 	"github.com/rabbitstack/fibratus/pkg/alertsender"
-	"github.com/rabbitstack/fibratus/pkg/config"
 	"github.com/rabbitstack/fibratus/pkg/util/hostname"
 	"github.com/rabbitstack/fibratus/pkg/util/version"
 	"text/template"
 	"time"
 )
 
-// RenderHTMLRuleAlert produces HTML template for rule alerts. This function generates
-// inlined CSS to maximize the compatibility between email clients when the alert is
-// transported via email sender or other senders that may render HTML content.
-func RenderHTMLRuleAlert(ctx *config.ActionContext, alert alertsender.Alert) (string, error) {
+// renderHTMLTemplate produces HTML template for the alert.
+// This function generates inlined CSS to maximize the compatibility
+// across email clients.
+func renderHTMLTemplate(alert alertsender.Alert) (string, error) {
 	data := struct {
-		*config.ActionContext
 		Alert       alertsender.Alert
 		TriggeredAt time.Time
 		Hostname    string
 		Version     string
 	}{
-		ctx,
 		alert,
 		time.Now(),
 		hostname.Get(),
 		version.Get(),
 	}
+
 	_ = data.Alert.MDToHTML()
 	funcmap := sprig.TxtFuncMap()
 
@@ -56,7 +54,7 @@ func RenderHTMLRuleAlert(ctx *config.ActionContext, alert alertsender.Alert) (st
 		}
 		return false
 	}
-	tmpl, err := template.New("rule-alert").Funcs(funcmap).Parse(ruleAlertHTMLTemplate)
+	tmpl, err := template.New("alert").Funcs(funcmap).Parse(htmlTemplate)
 	if err != nil {
 		return "", err
 	}

pkg/alertsender/renderer/renderer_test.go renamed to pkg/alertsender/mail/renderer_test.go

@@ -16,12 +16,11 @@
  * limitations under the License.
  */
 
-package renderer
+package mail
 
 import (
 	"github.com/antchfx/htmlquery"
 	"github.com/rabbitstack/fibratus/pkg/alertsender"
-	"github.com/rabbitstack/fibratus/pkg/config"
 	htypes "github.com/rabbitstack/fibratus/pkg/handle/types"
 	"github.com/rabbitstack/fibratus/pkg/kevent"
 	"github.com/rabbitstack/fibratus/pkg/kevent/kparams"
@@ -37,17 +36,19 @@ import (
 	"time"
 )
 
-func TestHTMLFormatterRuleAlert(t *testing.T) {
-	out, err := RenderHTMLRuleAlert(&config.ActionContext{
-		Filter: &config.FilterConfig{
-			Labels: map[string]string{
-				"tactic.name":       "Credential Access",
-				"tactic.ref":        "https://attack.mitre.org/tactics/TA0006/",
-				"technique.name":    "Credentials from Password Stores",
-				"technique.ref":     "https://attack.mitre.org/techniques/T1555/",
-				"subtechnique.name": "Windows Credential Manager",
-				"subtechnique.ref":  "https://attack.mitre.org/techniques/T1555/004/",
-			},
+func TestRenderHTMLTemplate(t *testing.T) {
+	out, err := renderHTMLTemplate(alertsender.Alert{
+		Title:       "Suspicious access to Windows Vault files",
+		Text:        "`cmd.exe` attempted to access Windows Vault files which was considered as a suspicious activity",
+		Severity:    alertsender.Critical,
+		Description: "Identifies attempts from adversaries to acquire credentials from Vault files",
+		Labels: map[string]string{
+			"tactic.name":       "Credential Access",
+			"tactic.ref":        "https://attack.mitre.org/tactics/TA0006/",
+			"technique.name":    "Credentials from Password Stores",
+			"technique.ref":     "https://attack.mitre.org/techniques/T1555/",
+			"subtechnique.name": "Windows Credential Manager",
+			"subtechnique.ref":  "https://attack.mitre.org/techniques/T1555/004/",
 		},
 		Events: []*kevent.Kevent{
 			{
@@ -240,11 +241,8 @@ func TestHTMLFormatterRuleAlert(t *testing.T) {
 				},
 			},
 		},
-	},
-		alertsender.Alert{
-			Title:    "Suspicious access to Windows Vault files",
-			Text:     "`cmd.exe` attempted to access Windows Vault files which was considered as a suspicious activity",
-			Severity: alertsender.Critical})
+	})
+
 	require.NoError(t, err)
 	doc, err := htmlquery.Parse(strings.NewReader(out))
 	require.NoError(t, err)

pkg/alertsender/renderer/template.go renamed to pkg/alertsender/mail/template.go

@@ -16,9 +16,9 @@
  * limitations under the License.
  */
 
-package renderer
+package mail
 
-var ruleAlertHTMLTemplate = `
+var htmlTemplate = `
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
@@ -75,28 +75,26 @@ var ruleAlertHTMLTemplate = `
                   {{ $text := (regexReplaceAll "<code>" .Alert.Text "<code style='border-radius: 5px; color: #404243; font-size: .8rem; margin: 0 2px; padding: 3px 5px; line-height: 1.7rem; white-space: pre-wrap; font-weight: 600; font-family: Consolas, Roboto, monaco, monospace; background-color: #e1e3e4;'>") }}
                   <p style="font-size: .8rem; margin: 0 0 4px 0px; padding: 3px 0px; white-space: pre-wrap; line-height: 1.5em;">{{ regexReplaceAll "\\s+" $text " " }}</p>
                   {{- end }}
-                  {{ if hasKey .Filter.Labels "tactic.name" }}
-                  <div class="tag" style="display: inline-block; border-radius: 5px; color: #404243; font-size: .8rem; margin: 2px 2px; padding: 3px 5px; white-space: pre-wrap; font-weight: 600; background-color: #bad1fb;"><a style="text-decoration: none; color: inherit;" href="{{ index .Filter.Labels "tactic.ref"}}">{{ index .Filter.Labels "tactic.name"}}</a></div>
+                  {{ if hasKey .Alert.Labels "tactic.name" }}
+                  <div class="tag" style="display: inline-block; border-radius: 5px; color: #404243; font-size: .8rem; margin: 2px 2px; padding: 3px 5px; white-space: pre-wrap; font-weight: 600; background-color: #bad1fb;"><a style="text-decoration: none; color: inherit;" href="{{ index .Alert.Labels "tactic.ref"}}">{{ index .Alert.Labels "tactic.name"}}</a></div>
                   {{ end }}
-                  {{ if hasKey .Filter.Labels "technique.name" }}
-                  <div class="tag" style="display: inline-block; border-radius: 5px; color: #404243; font-size: .8rem; margin: 2px 2px; padding: 3px 5px; white-space: pre-wrap; font-weight: 600; background-color: #84cad7;"><a style="text-decoration: none; color: inherit;" href="{{ index .Filter.Labels "technique.ref"}}">{{ index .Filter.Labels "technique.name"}}</a></div>
+                  {{ if hasKey .Alert.Labels "technique.name" }}
+                  <div class="tag" style="display: inline-block; border-radius: 5px; color: #404243; font-size: .8rem; margin: 2px 2px; padding: 3px 5px; white-space: pre-wrap; font-weight: 600; background-color: #84cad7;"><a style="text-decoration: none; color: inherit;" href="{{ index .Alert.Labels "technique.ref"}}">{{ index .Alert.Labels "technique.name"}}</a></div>
                   {{ end }}
-                  {{ if hasKey .Filter.Labels "subtechnique.name" }}
-                  <div class="tag" style="display: inline-block; border-radius: 5px; color: #404243; font-size: .8rem; margin: 2px 2px; padding: 3px 5px; white-space: pre-wrap; font-weight: 600; background-color: #fcbcba;"><a style="text-decoration: none; color: inherit;" href="{{ index .Filter.Labels "subtechnique.ref"}}">{{ index .Filter.Labels "subtechnique.name"}}</a></div>
+                  {{ if hasKey .Alert.Labels "subtechnique.name" }}
+                  <div class="tag" style="display: inline-block; border-radius: 5px; color: #404243; font-size: .8rem; margin: 2px 2px; padding: 3px 5px; white-space: pre-wrap; font-weight: 600; background-color: #fcbcba;"><a style="text-decoration: none; color: inherit;" href="{{ index .Alert.Labels "subtechnique.ref"}}">{{ index .Alert.Labels "subtechnique.name"}}</a></div>
                   {{ end }}
                 </td>
               </tr>
+             {{- if .Alert.Description }}
               <tr>
                 <td style="padding: 5px 0px 0px 15px;">
                   <p style="background: #efefef; display: inline-block; border-radius: 5px; font-size: .8rem; margin: 4px 4px 25px 0px; padding: 3px 5px; white-space: pre-wrap; line-height: 1.5em;">
-                     {{- if .Filter -}}
-                     {{- .Filter.Description | trimSuffix "." }}
-                     {{- else }}
-                     {{- .Group.Description | trimSuffix "." }}
-                     {{- end -}}
+                     {{- .Alert.Description | trimSuffix "." }}
                   </p>
                 </td>
               </tr>
+			 {{ end }}
             </table>
           </td>
         </tr>
@@ -109,7 +107,7 @@ var ruleAlertHTMLTemplate = `
                   <h1 style="font-weight: bold; margin-bottom: 22px; margin-top: 0px; font-size: 16px;">
                     Security events involved in this incident
                   </h1>
-                  {{- range $i, $evt := .Events }}
+                  {{- range $i, $evt := .Alert.Events }}
                   {{ with $evt }}
                   <table style="width: 100%; margin: 0; padding: 35px 0; border-collapse: collapse;" width="100%" cellpadding="0" cellspacing="0">
                     <tr>

pkg/config/schema_windows.go

@@ -52,7 +52,8 @@ var schema = `
 								"password": 	{"type": "string"},
 								"from": 		{"type": "string"},
 								"to": 			{"type": "array", "items": {"type": "string", "format": "email"}},
-								"content-type": {"type": "string"}
+								"content-type": {"type": "string"},
+								"use-template": {"type": "boolean"}
 							},
 							"if": {
 								"properties": {"enabled": { "const": true }}

pkg/filter/action/emit.go

@@ -21,7 +21,6 @@ package action
 import (
 	"fmt"
 	"github.com/rabbitstack/fibratus/pkg/alertsender"
-	"github.com/rabbitstack/fibratus/pkg/alertsender/renderer"
 	"github.com/rabbitstack/fibratus/pkg/config"
 	"github.com/rabbitstack/fibratus/pkg/util/markdown"
 	log "github.com/sirupsen/logrus"
@@ -49,25 +48,22 @@ func Emit(ctx *config.ActionContext, title string, text string, severity string,
 			tags,
 			alertsender.ParseSeverityFromString(severity),
 		)
+
 		alert.ID = ctx.Filter.ID
 		alert.Events = ctx.Events
+		alert.Labels = ctx.Filter.Labels
+		alert.Description = ctx.Filter.Description
 
-		// strip markdown
+		// strip markdown if not supported by the sender
 		if !sender.SupportsMarkdown() {
 			alert.Text = markdown.Strip(alert.Text)
 		}
-		// produce HTML rule alert text for email sender
-		if sender.Type() == alertsender.Mail {
-			var err error
-			alert.Text, err = renderer.RenderHTMLRuleAlert(ctx, alert)
-			if err != nil {
-				return err
-			}
-		}
+
 		err := sender.Send(alert)
 		if err != nil {
 			return fmt.Errorf("unable to emit alert from rule via [%s] sender: %v", sender.Type(), err)
 		}
 	}
+
 	return nil
 }