Alert Templates

Capsule8 was designed to let users decide which data they need to best serve their workflows. As such, we support custom formatting of Alerts through Alert Templates. Alerts may be translated to a UTF-8 string via a Go template instead of the default JSON format.

Alert Templates are strings set in either the template field of the individual outputs listed in the outputs section of the Alert Dispatcher or at the top level under alert_output which will apply the template to any output that does not have a template set. This allows an operator to set a global Alert Template that can optionally be overridden for a given output.

This guide will cover basic usage as well as some common scenarios. See the Go template documentation for a complete overview.

Alert Template Examples

To create an Alert Template, first select the names of the Alert fields you wish to include in your Alert output. See the Alert Template Schema for a complete reference of all the available fields. Alert fields are selected using the Go template {{.FieldName}} syntax. The syntax is similar to Mustache templates, but the Go template language is much more powerful. For example, to log the name of an Alert’s Policy Name, Thread Group ID, and Program Name you could do the following:

template: '{{.StrategyName}} - {{.ProcessInfo.Tgid}} {{.ProcessInfo.Program.Path}}'

This will produce an Alert that looks like the following string:

WGET - Blacklist 6620 /usr/bin/wget

This template selected the nested TGID value from the Alert’s ProcessInfo struct. Note that everything except the template parameters was passed through as plain text. This allowed us to add a hyphen between the Policy Name and the rest of the log statement for clarity. Taking this one step further, we could even format the Alert as JSON:

template: '{"policy_name":"{{.StrategyName}}","process_tgid":"{{.ProcessInfo.Tgid}}"}'

This would produce the following JSON string:

{"policy_name":"Blacklist wget","process_tgid":"22144"}

Should you need to wrap the full Alert JSON in another JSON object for compatibility with another system, a helper function called AlertJSON is provided. This example creates a new JSON object with an id field, a timestamp field, and the full Alert payload assigned to a field called payload:

template: '{"id":"{{.UUID}}","timestamp":"{{.Timestamp}}","payload":{{AlertJSON .}}}'

Note that you should always test the output of new templates before deploying to ensure that the formatting of your output is what you expect! This is especially important for formats like JSON that are intended to be parsed by another system. This example was intentionally compacted onto one line to avoid introducing multi-line output which is not compatible by default with most logging systems.

Overall, Alert Templates are a powerful and flexible way to extend the Alert format to better integrate into your existing workflows. When combined with the Alert Webhook feature, this is a powerful way to easily integrate Capsule8 with other systems. When the sensor starts, any templates that are set are compiled and silently tested with a test Alert which allows the sensor to verify not only that the templates are syntactically correct but also that they can successfully be applied to an Alert without error. No output is generated from this process.

Functions In Alert Templates

Alert Templating expose several functions that can make formatting easier.

AlertJSON

Outputs the entire alert json. This can be useful for wrapping the alert json when other systems have a required input format IE. Console Web Hooks, Splunk ect.

To use the function:

template: '{"uuid": "{{.UUID}}", "data": {{AlertJSON}}}'

This will generate the expected output of:

{"uuid": "2fb9e1fd-cd9b-4dbc-adca-70c29446f808", "data": {"timestamp":"2020-07-29T19:35:57.440109088Z","scope":"Process","priority":"Low","confidence":"Max","comments":"Alerts when an command is executed by a valid system user via SSH.","alert_labels":{},"notifications":[{"timestamp":"2020-07-29T19:35:57.440109088Z",
....
,"name":"Shell Command Executed","categories":["C8.Abnormal Activity.System Activity","MITRE.Execution.Command-Line Interface","MITRE.Execution.User Execution","MITRE.Initial Access.Valid Accounts"]}}

 template: |
   {{.UUID}} .Timestamp {{.Timestamp}}
   {{.UUID}} RFC3339Date .Timestamp {{RFC3339Date .Timestamp}}
   {{.UUID}} RFC3339NanoDate .Timestamp {{RFC3339NanoDate .Timestamp}}
   {{.UUID}} ToSeconds .Timestamp {{ToSeconds .Timestamp}}

 Which will output:

9dae63f9-110f-40d0-9dfe-ebac85b9433f .Timestamp 1596053056936135157
9dae63f9-110f-40d0-9dfe-ebac85b9433f RFC3339Date .Timestamp 2020-07-29T20:04:16Z
9dae63f9-110f-40d0-9dfe-ebac85b9433f RFC3339NanoDate .Timestamp 2020-07-29T20:04:16.936135157Z
9dae63f9-110f-40d0-9dfe-ebac85b9433f ToSeconds .Timestamp 1596053056

Alert Template Errors

If the template value is not a syntactically valid template, it is treated as a fatal error and will prevent the Capsule8 Sensor from starting. Included in the output is a line number, e.g. template:1, to indicate the error is on the first line.

root@peterm:~# ./capsule8-sensor
Capsule8 Sensor version 1.1.0+563aff9-dirty (Build: )
INFO[0000] fetching metadata
INFO[0000] fetched metadata
INFO[0001] Starting Embedded Analytics 
FATA[0001] Unable to start analytics: template: error: template: template:1: unexpected"}" in operand

If the template is syntactically valid but an invalid Alert field is specified, this will result in a non-fatal error on Alerts.

For example, if you had the following template with the Path field misspelled as Pathx like:

template: |
{{.StrategyName}} {{.ProcessInfo.Tgid}} {{.ProcessInfo.Program.Pathx}}

you would get the following error:

ERRO[0005] template: template:1:53: executing "template" at <.ProcessInfo.Program...>: can't evaluate field Pathx in type *processtree.ProgramInfo

To resolve this, you will need to update the template and restart the Capsule8 Sensor.