Creating alert templates

Community Platform

With the Rules Engine, you can define rules that alert you on specific events, such as changes to scans, assets, and Explorers. To customize the alert messages, you can create custom templates to standardize and format alerts triggered from rules. With custom templates, you can include more context and data for your alerts.

Templates can output in HTML, JSON, and text for use in emails, internal notifications, or webhooks. You can customize the contents of these templates as needed.

Like rules and channels, templates can also be utilized by any number of organizations, and managed by any user with User role access to all associated organizations. Similarly, any user with Viewer role access to one or more organizations will be able to view the template details only, and may not edit or create new templates.

Template building basics

You can define the contents of an alert message using the Mustache templating language. As long as you know a little bit about how the Mustache syntax works, you can build custom HTML and JSON templates to reference and pull in runZero data.

• For Slack notifications, you can use Slack’s Block Kit and their interactive Block Kit Builder to construct a rich message in JSON format, and then use Mustache to insert the relevant data.

• For Microsoft Teams, you can use the Adaptive Cards format to build rich messages, and again insert data via Mustache.

Our templates have two fields for template data: subject and body. Both subject and body can be customized using the Mustache syntax.

Inserting a data in a template

A standard set of objects is passed to the {{template engine}}, you just have to indicate the fields from the objects you want to insert into your template. Use the Mustache template syntax, {{variable}}, to include alert values when a rule matches certain conditions.

For HTML and JSON templates, values inserted using {{ }} are automatically escaped according to the appropriate rules. To avoid escaping a particular value, use triple curly braces, like this: {{{task.name}}}.

For JSON templates, the special self variable {{.}} at the top level will output all available variables and their values as JSON.

Special rules for JSON

For JSON templates, variables are rendered differently depending on whether they are single values or multiple values:

• A string or number gets rendered to the raw value. A string will have any embedded quotes escaped, but it won’t be wrapped in quotes. This is so you can put multiple strings or numbers into a single JSON string in your template.

• An object or array gets rendered to the full JSON representation of the object or array. This is for convenience, so that you can dump arrays and objects to JSON without having to loop through values. However, it means that if you try to put an array value into a JSON string by surrounding it with quotes, the result won’t be valid JSON.

Consider the following template running on an asset with multiple IP addresses:

{
"addresses_1": {{addresses}}, 
"addresses_2": "{{#addresses}}{{.}} {{/addresses}}",
"addresses_3": "{{addresses}}"
}

Here’s the result:

{
"addresses_1": ["10.0.1.4","10.1.7.5"], 
"addresses_2": "10.0.1.4 10.1.7.5 ",
"addresses_3": "["10.0.1.4","10.1.7.5"]"
}

The addresses_1 substitution works as you might want — {{addresses}} is an array, so it gets replaced with a proper JSON array containing the addresses.

The second substitution also works. In that case, the template loops through each address in the array, and puts the values into a single string. The values don’t get put in quotes, but they will have any quotes inside them escaped.

The third substitution doesn’t work properly — the addresses get turned into a JSON array of strings, but that gets surrounded by the quotes, resulting in invalid JSON.

Inserting a value

To insert a value, put the variable name in double curly brackets, like this {{variablename}}.

The following example shows how to insert the console address:

The runZero Console is at {{console}}.

Inserting a value from an object

To insert a value from a specific object, separate the object name and field name with a dot, like this {{object.fieldname}}.

The following example shows how to insert the organization name:

The organization name is {{organization.name}}.

Inserting multiple values from an object

To insert multiple values from an object easily, use a section. You will need to start the section with {{#objectname}} and close it with a matching {{/objectname}} The following example shows how to insert the results from a scan that include total assets and number of assets changed:

Here are the results:
{{#scan}}
Scan found {{assets_total}} assets and changed {{assets_changed}} of them.
{{/scan}}

What happens if a field contains multiple values?

If a section refers to a field which contains multiple values, the template engine will loop through the values in the field, processing the section inside for each individual value.

The following example loops through all of the assets in report.new, and for each one, outputs its names and addresses fields. If there is nothing stored in report.new, the section between the tags will not be rendered.

{{#report.new}}
{{names}} {{addresses}}
{{/report.new}}

Note that within a loop, you can still refer to values from the outer object. If a named value isn’t found in the current loop object, the template engine will check the outer object. For example, this can be useful for referring to the {{console}} variable, which provides the root runZero console URL.

Using boolean values

You can use boolean values with the {{#field}}{{/field}} tags. If the value of the field is false, the section between the tags is not rendered.

For example:

{{#query.truncated}}
(Additional results were found but not included in this report)
{{/query.truncated}}

Objects and fields reference

To include runZero data and details in your alerts, you can build your template using the following objects and fields.

globals

event

The following fields are available in the event object:

task

For events triggered by a task, the following fields are available in the task object:

organization

The following fields are available in the organization object:

site

The following fields are available in the site object:

rule

The following fields are available in the rule object:

scan

For events triggered by a scan task, the following additional fields are available in a scan object:

explorer

For events triggered by a scan task, the following additional fields are available in an explorer object (runZero 2.1.8+):

search

For events triggered by a search query rule, the following additional fields are available in a search object:

report

For “scan completed” events, a report object contains the following results from the scan:

The limit on the number of objects passed to the template is 25 for email notifications, 10 for Webhook notifications.

asset (from a scan report)

Each asset returned as part of a scan report has the following fields:

query

For query events, the following data is provided in the query variable:

The limit on the number of assets passed to the template from a query is 25 for email notifications, 10 for Webhook notifications.

asset (from a query)

For assets returned from a query rule, the following fields are available:

service (from a query)

For services returned from a query rule, the following fields are available, some of which are taken from the associated asset:

wlan (wireless LAN, from a query)

For wireless lans (wlans) returned from a query rule, the following fields are available:

Example: Alert when scan completes

Let’s take an example of something you might want to get alerted on: completed scans. We can create a rule that emails us when a scan completes, and provides us with some details, such as the number of new, online, offline, and modified assets. We’ll build these details into our template.

Step 1. Create a template.

You can create a template from the Alerts page.

• Name the template something like Email the team when a scan completes.
• For the template type, choose HTML, since we want to use this template for emails.
• For the subject line, enter something that’s descriptive, like runZero scan {{scan.name}} completed at {{scan.end_time}}. You can use the Mustache syntax for the subject.

Step 2. Create the body message

Now, let’s create the email body. We want the email to tell us how many new, online, offline, and modified assets there are, as well as give us details on the new assets discovered.

The body looks like this:

<h1>{{site.name}}</h1>

<h2>Scan Results</h2>
{{#scan}}
<ul>
<li>{{assets_new}} new assets</li>
<li>{{assets_online}} online assets</li>
<li>{{assets_offline}} offline assets</li>
<li>{{assets_changed}} modified assets</li>
</ul>
{{/scan}}

<h2>New assets</h2>
<ul>
{{#report.new}}
<li>{{names}} {{addresses}} {{os}}</li>
{{/report.new}}
{{^report.new}}
<li>No new assets were discovered.</li>
{{/report.new}}
</ul>

<p><a href="{{task.url}}">View the scan results</a></p>

See that caret (^)? It represents inverted sections. These sections only render when the list is empty or the value is empty or false.

Step 3. Save the template and create a rule

The template is now available for you to choose when you create a rule.

Sample JSON templates

A JSON array of new assets found by a scan

[
  {{#report.new}}
    {
      "addresses": "{{addresses}}",
      "alive": "{{alive}}",
      "detected_by": "{{detected_by}}",
      "domains": "{{domains}}",
      "first_seen": "{{first_seen}}",
      "hw": "{{hw}}",
      "names": "{{names}}",
      "os": "{{os}}",
      "type": "{{type}}"
    },
  {{/report.new}}
  null
]

The trailing null in the array is so that the array is valid JSON, because JSON doesn’t allow trailing commas.

All available attributes

Output all available variables and their attributes as a JSON object:

{{.}}

Alternatively, you can build your own JSON array with all attributes:

{
  "event": {
    "action": "{{event.action}}",
    "created_at": "{{event.created_at}}",
    "id": "{{event.id}}",
    "source_name": "{{sevent.ource_name}}",
    "source_type": "{{event.source_type}}",
    "success": "{{event.success}}",
    "target_name": "{{event.target_name}}",
    "target_type": "{{tevent.arget_type}}"
  },
  "organization": {
    "name": "{{organization.name}}",
    "id": "{{organization.id}}"
  },
  "site": {
    "name": "{{site.name}}",
    "id": "{{site.id}}"
  },
  "report": {
    "truncated": "{{report.truncated}}",
    "changed": "{{report.changed}}",
    "new": "{{report.new}}",
    "offline": "{{report.offline}}",
    "online": "{{report.online}}"
  },
  "rule": {
    "action": "{{rule.action}}",
    "created_at": "{{rule.created_at}}",
    "created_by": "{{rule.created_by}}",
    "event": "{{rule.event}}",
    "id": "{{rule.id}}",
    "name": "{{rule.name}}",
    "updated_at": "{{rule.updated_at}}"
  },
  "scan": {
    "explorer_id": "{{scan.explorer_id}}",
    "assets_changed": "{{scan.assets_changed}}",
    "assets_ignored": "{{scan.assets_ignored}}",
    "assets_new": "{{scan.assets_new}}",
    "assets_offline": "{{assets_offline}}",
    "assets_online": "{{scan.assets_online}}",
    "assets_total": "{{scan.assets_total}}",
    "assets_unchanged": "{{scan.assets_unchanged}}",
    "assets_updated": "{{scan.assets_updated}}",
    "duration": "{{scan.duration}}",
    "end_time": "{{scan.end_time}}",
    "excludes": "{{scan.excludes}}",
    "id": "{{scan.id}}",
    "name": "{{scan.name}}",
    "rate": "{{scan.rate}}",
    "recv_bytes": "{{scan.recv_bytes}}",
    "recv_error": "{{scan.recv_error}}",
    "recv_packets": "{{scan.recv_packets}}",
    "scheduled_time": "{{scan.scheduled_time}}",
    "sent_bytes": "{{scan.sent_bytes}}",
    "sent_error": "{{scan.sent_error}}",
    "sent_packets": "{{scan.sent_packets}}",
    "start_time": "{{scan.start_time}}",
    "tags": "{{scan.tags}}",
    "targets": "{{scan.targets}}",
    "type": "{{scan.type}}"
  },
  "explorer": {
    "id": "{{explorer.id}}",
    "name": "{{explorer.name}}",
    "internal_ip": "{{explorer.internal_ip}}"
  },
  "search": {
    "url": "{{search.url}}",
    "found": "{{search.found}}",
    "comparator": "{{search.comparator}}",
    "value": "{{search.value}}"
  },
  "query": {
    "count": "{{query.count}}",
    "assets": "{{query.assets}}",
    "services": "{{query.services}}",
    "wlans": "{{query.wlans}}",
    "truncated": "{{query.truncated}}"
  }
}

Event attributes only

{
  "event": {{event}}
}

or

{
  "action": "{{event.action}}",
  "created_at": "{{event.created_at}}",
  "id": "{{event.id}}",
  "source_name": "{{sevent.ource_name}}",
  "source_type": "{{event.source_type}}",
  "success": "{{event.success}}",
  "target_name": "{{event.target_name}}",
  "target_type": "{{tevent.arget_type}}"
}

Organization attributes only

{
  "organization": {{organization}}
}

or

{
  "name": "{{organization.action}}",
  "id": "{{organization.id}}"
}

Site attributes only

{
  "site": {{site}}
}

or

{
  "name": "{{site.action}}",
  "id": "{{site.id}}"
}

Report attributes only

{
  "report": {{report}}
}

or

{
  "truncated": "{{report.truncated}}",
  "changed": "{{report.changed}}",
  "new": "{{report.new}}",
  "offline": "{{report.offline}}",
  "online": "{{report.online}}"
}

Rule attributes only

{
  "rule": {{rule}}
}

or

{
  "action": "{{rule.action}}",
  "created_at": "{{rule.created_at}}",
  "created_by": "{{rule.created_by}}",
  "event": "{{rule.event}}",
  "id": "{{rule.id}}",
  "name": "{{rule.name}}",
  "updated_at": "{{rule.updated_at}}"
}

Scan attributes only

{
  "scan": {{scan}}
}

or

{
  "explorer_id": "{{scan.explorer_id}}",
  "assets_changed": "{{scan.assets_changed}}",
  "assets_ignored": "{{scan.assets_ignored}}",
  "assets_new": "{{scan.assets_new}}",
  "assets_offline": "{{assets_offline}}",
  "assets_online": "{{scan.assets_online}}",
  "assets_total": "{{scan.assets_total}}",
  "assets_unchanged": "{{scan.assets_unchanged}}",
  "assets_updated": "{{scan.assets_updated}}",
  "duration": "{{scan.duration}}",
  "end_time": "{{scan.end_time}}",
  "excludes": "{{scan.excludes}}",
  "id": "{{scan.id}}",
  "name": "{{scan.name}}",
  "rate": "{{scan.rate}}",
  "recv_bytes": "{{scan.recv_bytes}}",
  "recv_error": "{{scan.recv_error}}",
  "recv_packets": "{{scan.recv_packets}}",
  "scheduled_time": "{{scan.scheduled_time}}",
  "sent_bytes": "{{scan.sent_bytes}}",
  "sent_error": "{{scan.sent_error}}",
  "sent_packets": "{{scan.sent_packets}}",
  "start_time": "{{scan.start_time}}",
  "tags": "{{scan.tags}}",
  "targets": "{{scan.targets}}",
  "type": "{{scan.type}}"
}

Explorer attributes only

{
  "explorer": {{explorer}}
}

or

{
  "id": "{{explorer.id}}",
  "name": "{{explorer.name}}",
  "internal_ip": "{{explorer.internal_ip}}"
}

Search attributes only

{
  "search": {{search}}
}

or

{
  "url": "{{search.url}}",
  "found": "{{search.found}}",
  "comparator": "{{search.comparator}}",
  "value": "{{search.value}}"
}

Query attributes only

{
  "query": {{query}}
}

or

{
  "count": "{{query.count}}",
  "assets": "{{query.assets}}",
  "services": "{{query.services}}",
  "wlans": "{{query.wlans}}",
  "truncated": "{{query.truncated}}"
}

Asset, service, or wireless query alert to SIEM or SOAR

{
  "organization": {
    "name": "{{organization.name}}",
    "id": "{{organization.id}}"
  },
  "site": {
    "name": "{{site.name}}",
    "id": "{{site.id}}"
  },
  "rule": {
    "action": "{{rule.action}}",
    "created_at": "{{rule.created_at}}",
    "created_by": "{{rule.created_by}}",
    "event": "{{rule.event}}",
    "id": "{{rule.id}}",
    "name": "{{rule.name}}",
    "updated_at": "{{rule.updated_at}}"
  },
  "search": {
    "url": "{{search.url}}",
    "found": "{{search.found}}",
    "comparator": "{{search.comparator}}",
    "value": "{{search.value}}"
  }
}

Asset, service, or wireless query alert to Slack

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": ":red_circle: *runZero Alert* - {{rule.name}}"
      }
    },
    {
      "type": "divider"
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Rule information*\n\n_Name_: {{rule.name}}\n_Type_: {{rule.event}}\n_Link_: https://console.runzero.com/alerts/rule/{{rule.id}}"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Match information*\n\n_Organization_: {{organization.name}}\n_Site_: {{site.name}}\n_Match count_: {{search.found}}\n_Search_: {{search.value}}\n_Link_: https://console.runzero.com/alerts/rule/{{search.url}}"
      }
    }
  ]
}

Asset, service, or wireless query alert to Microsoft Teams

{
  "type": "message",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.adaptive",
      "contentUrl": null,
      "content": {
        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
        "type": "AdaptiveCard",
        "version": "1.5",
        "body": [
          {
            "type": "TextBlock",
            "text": "runZero Alert - {{rule.name}}"
          },
          {
            "type": "TextBlock",
            "text": "**Rule information**\n\n_Name_: {{rule.name}}\n\n_Type_: {{rule.event}}\n\n_Link_: [Rule](https://console.runzero.com/alerts/rule/{{rule.id}})",
            "wrap": true
          },
          {
            "type": "TextBlock",
            "text": "**Match information**\n\n_Organization_: {{organization.name}}\n\n_Site_: {{site.name}}\n\n_Match count_: {{search.found}}\n\n_Search_: {{search.value}}\n\n_Link_: [Search](https://console.runzero.com/alerts/rule/{{search.url}})",
            "wrap": true,
            "spacing": "Medium"
          }
        ]
      }
    }
  ]
}

Data type accepted by each channel

When you create a rule, the channel you select must accept the data type used by the template. For example, if you want to send a Slack notification, the template must be in plain text or JSON.

Here are the data types accepted by each channel:

Managing templates

Go to Alerts > Templates. From this page, you can create, edit, and delete templates. Before deleting templates, make sure they are not in use by any rules. If you delete a template that is in use by a rule, the rule will revert to the default template.