Just Published! Threat Report: Exposing Malware in Linux-Based Multi-Cloud Environments | Download Now

Customizing Carbon Black Protection Platform Email Alert Templates

Customizing Carbon Black Protection Platform Email Alert Templates

Overview

The Cb Protection Platform can send email notifications to inform that an alert is triggered or that approval request has been responded to (if so configured).

These emails are predefined with a default installation but are also customizable to add customer-specific formatting and visuals for available data.

Template files

Templates are text files used to customize above mentioned email messages.

Distribution

Template files are distributed with a Bit9 Server installer in:

<install path>\Parity Server\Reporter\AlertTemplates

Each template consist of 3 files (header, HTML body and text body):

  • Header
    • Custom headers to be appended to an email message
    • Format of headers template part is:
      • Header1 = value1;Header2 = value2
    • Subject of an email is one of the email headers
    • Empty template is not allowed
  • HTML Body (used in case HTML email notification is requested)
    • Body of email message in HTML
    • This is used if notification email type specified is HTML or Auto
    • Format of HTML body template part is specified by HTML standards
    • Empty template is not allowed
  • Text Body (used in case TEXT email notification is requested)
    • Body of email message in plain text
    • This is used for email body in case text email is used
      • In case that HTML email type is requested and this field is not empty, it will be used as plain text representation for email clients that do not wish to receive HTML emails
    • Format of Text Body template part is not limited
    • Empty template is not allowed

A number of pre-defined templates are provided by default which are customized for corresponding types of alerts notifications. These templates are protected from modification unless /force switch is used.

Alert emails

Templates are selected in Console : Alert : Alert Details : ‘Mail template’ selector.  This provides the selection of individual templates for each Alert. Each alert type can have it's own email template specified.

There are different alert templates that are predefined:

  • Template for Approval - for Approval request and Justification alerts
  • Template for Certificate - for Certificate based alerts
  • Template for Elevated Privilege - for Local approval alert
  • Template for Event - for Event based alerts
  • Template for File - for File based alerts
  • Template for System Health - for System health based alerts
  • Default - for all other alerts

Template files for customizing alert notifications:

Reporter/AlertTemplates/Template for Alert.hdr

Reporter/AlertTemplates/Template for Alert.txt

Reporter/AlertTemplates/Template for Alert.html

Example from one of the header files:

SUBJECT=Bit9 Platform Alert on {$server_name}: {$alert_name} - {$alert_message}

Example from the body file (for Text):

------------------------------

{$alert_type}

------------------------------

{$alert_name}

Priority: {$priority}

{$triggered_summary}

Bit9 Platform Server: {$server_name}

Triggered On: {$triggered_date}

Created By: {$created_by}

Message: {$alert_message}

Tell me more:

Alert Details https://{$server_name}/alert-history.php?alertID={$alert_id}

{$tagline}

Approval response emails

There is just one template that is predefined:

  • Template for Response - sent to the requester email when Approval request is closed (if so configured)

Template files for customizing approval response notifications:

Reporter/AlertTemplates/Template for Response.hdr

Reporter/AlertTemplates/Template for Response.txt

Reporter/AlertTemplates/Template for Response.html

Header file:

SUBJECT=Bit9 Platform Approval Request Response on {$server_name} for {$approval_filename}: {$approval_resolution}

Body file (for Text):

------------------------------

Request Approval Response

------------------------------

Request for "{$approval_filename}" is {$approval_resolution}

Approval Response: {$approval_response}

Request Reason: {$approval_request_reason}

Requested By: {$approval_requestor}

Requested On: {$approval_request_date}

Bit9 Platform Server: {$server_name}

Template tags

Only the supported {$tags} will be replaced by the Reporter service when it processes an alert, others will be ignored (left as is).  If a {$tag} is supported but it’s value cannot be retrieved, it shall be replaced with the ‘N/A’ value.

The new style of <tags>, can additionally be used with 7.2.1+ (currently only in Event Alerts) to customize alert message, when configuring the Alert in the Bit9 Console.

List of supported template tags

Tag NameAlert Type Tag Can Be Used WithTag Value
{$server_name}All AlertsComputer name where Server is installed
{$alert_id}All AlertsAlert identifier
{$alerts_triggered_id}All AlertsTriggered alert instance identifier
{$priority}All AlertsPriority of the Alert itself
{$priority_color}All AlertsAlert priority color (for HTML)
{$alert_type}All AlertsAlert type name
{$alert_name}All AlertsAlert name
{$alert_message}All AlertsAlert message
{$created_by}All AlertsDate when alert was created
{$triggered_date}All AlertsDate when alert was triggered
{$triggered_summary}All AlertsSummary of triggered alert
{$tagline}All AlertsTagline used for branding purposes through database (shepherdConfigs param tagline)
{$host_id}Computer related alertsHost database identifier (used optionally for host detail links)
{$host_name}Elevated privilege alertHost name of computer that triggered the alert
{$hash}File related alertsHash of file that triggered the alert
{$file_name}File related alertsFile name of file that triggered the alert
{$antibody_id}File related alertsFile database identifier (used for file detail links)
{$file_state}File related alertsFile state of the file that triggered the alert
{$cert_it}Certificate alertsCertificate id that triggered the alert
{$cert_subject}Certificate alertsCertificate subject that triggered the alert
{$publisher}Certificate alertsCertificate publisher that triggered the alert
<Sha256>Event and Approval Request alertsSHA256 hash of the file that triggered the alert
<Md5>Event and Approval Request alertsMD5 hash of the file that triggered the alert
<Sha1>Event and Approval Request alertsSHA1 hash of the file that triggered the alert
<FileName>Event and Approval Request alertsFile name of the file that triggered the alert
<HostName>Event and Approval Request alertsHost name of the computer which triggered the alert
<UserName>Event and Approval Request alertsUser name that triggered the alert
<RootSha256>Event and Approval Request alertsSHA256 hash of the installer of the file that triggered the alert
<AntibodyId>Event and Approval Request alertsDatabase identifier of the file that triggered the alert
<HostId>Event and Approval Request alertsDatabase identifier of the computer that triggered the alert
<EventRuleName>Event alertsEvent rule that triggered the alert (if event rule is used)
<EventRuleDescription>Event alertsEvent rule description that triggered the alert (if event rule is used as criteria)
<EventSubtype>Event alertsEvent subtype that triggered the alert (if event is used as criteria)
<EventDescription>Event alertsEvent description that triggered the alert (if event is used as criteria)
<ApprovalRequestPriority>Approval Request alertsApproval request priority as submitted by the user
<ApprovalRequestReason>Approval Request alertsApproval request reason as submitted by the user
{$approval_filename}Approval ResponseApproval response file name
{$approval_resolution}Approval ResponseApproval response resolution as submitted by the administrator
{$approval_response}Approval ResponseApproval response comments as submitted by the administrator
{$approval_request_reason}Approval ResponseApproval request reason as submitted by the user
{$approval_requestor}Approval ResponseApproval requester
{$approval_request_date}Approval ResponseApproval request date
{$indicator_id}System health alertsHealth indicator id that triggered the alert

Adding/replacing templates

Active templates are stored in the Bit9 database. New templates can be added or removed from database using Reporter command line switches:

  • add_template /name=”template_name” /folder=”local_folder_path”
    • Adds a new template to the database
    • Template name is specified
    • A new template with a same name will overwrite an existing template
    • The three files need to be in the “folder” and have same name like template name, but with corresponding extensions:
      • “template_name.hdr”
      • “template_name.txt”
      • “template_name.html”
    • /name=”template_name” /header=”folder/headers.hdr” /html=”folder/html_part.html” /text=”folder/text_part.txt”
      • Each template file for a template can be specified separately, but not required (less common)
  • remove_template /name=”template_name”
    • The template with that name is removed from the database
    • In case an alert is using the specified template, it would go back to the default templates.
    • Default templates are protected from removal

These commands are typed in a command prompt from the Reporter folder. Note: Pleasure ensure you are running the CLI as "Run as Administrator" to ensure proper rights are being used.

ParityReporter add_template /name=”template_name” /folder=”folder” /header=”folder/header.hdr” /html=”folder/html_part.html” /text=”folder/text_part.txt”

ParityReporter remove_template /name=”template_name”

Download Default Templates

The default templates from version 7.2.3 (MD5: c44e76f2aa6701efd32ae279eed3bcaa) and 8.0.0 (MD5: 5d5f22742c375ff5d6491bf5ff84adbf) are attached to this document in zip files.  Minor differences could be expected between earlier major versions, but the functionality is preserved.

Labels (2)
Attachments
Was this article helpful? Yes No
100% helpful (1/1)
Article Information
Author:
Creation Date:
‎11-19-2015
Views:
6321
Contributors