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 Name | Alert Type Tag Can Be Used With | Tag Value |
|---|---|---|
| {$server_name} | All Alerts | Computer name where Server is installed |
| {$alert_id} | All Alerts | Alert identifier |
| {$alerts_triggered_id} | All Alerts | Triggered alert instance identifier |
| {$priority} | All Alerts | Priority of the Alert itself |
| {$priority_color} | All Alerts | Alert priority color (for HTML) |
| {$alert_type} | All Alerts | Alert type name |
| {$alert_name} | All Alerts | Alert name |
| {$alert_message} | All Alerts | Alert message |
| {$created_by} | All Alerts | Date when alert was created |
| {$triggered_date} | All Alerts | Date when alert was triggered |
| {$triggered_summary} | All Alerts | Summary of triggered alert |
| {$tagline} | All Alerts | Tagline used for branding purposes through database (shepherdConfigs param tagline) |
| {$host_id} | Computer related alerts | Host database identifier (used optionally for host detail links) |
| {$host_name} | Elevated privilege alert | Host name of computer that triggered the alert |
| {$hash} | File related alerts | Hash of file that triggered the alert |
| {$file_name} | File related alerts | File name of file that triggered the alert |
| {$antibody_id} | File related alerts | File database identifier (used for file detail links) |
| {$file_state} | File related alerts | File state of the file that triggered the alert |
| {$cert_it} | Certificate alerts | Certificate id that triggered the alert |
| {$cert_subject} | Certificate alerts | Certificate subject that triggered the alert |
| {$publisher} | Certificate alerts | Certificate publisher that triggered the alert |
| <Sha256> | Event and Approval Request alerts | SHA256 hash of the file that triggered the alert |
| <Md5> | Event and Approval Request alerts | MD5 hash of the file that triggered the alert |
| <Sha1> | Event and Approval Request alerts | SHA1 hash of the file that triggered the alert |
| <FileName> | Event and Approval Request alerts | File name of the file that triggered the alert |
| <HostName> | Event and Approval Request alerts | Host name of the computer which triggered the alert |
| <UserName> | Event and Approval Request alerts | User name that triggered the alert |
| <RootSha256> | Event and Approval Request alerts | SHA256 hash of the installer of the file that triggered the alert |
| <AntibodyId> | Event and Approval Request alerts | Database identifier of the file that triggered the alert |
| <HostId> | Event and Approval Request alerts | Database identifier of the computer that triggered the alert |
| <EventRuleName> | Event alerts | Event rule that triggered the alert (if event rule is used) |
| <EventRuleDescription> | Event alerts | Event rule description that triggered the alert (if event rule is used as criteria) |
| <EventSubtype> | Event alerts | Event subtype that triggered the alert (if event is used as criteria) |
| <EventDescription> | Event alerts | Event description that triggered the alert (if event is used as criteria) |
| <ApprovalRequestPriority> | Approval Request alerts | Approval request priority as submitted by the user |
| <ApprovalRequestReason> | Approval Request alerts | Approval request reason as submitted by the user |
| {$approval_filename} | Approval Response | Approval response file name |
| {$approval_resolution} | Approval Response | Approval response resolution as submitted by the administrator |
| {$approval_response} | Approval Response | Approval response comments as submitted by the administrator |
| {$approval_request_reason} | Approval Response | Approval request reason as submitted by the user |
| {$approval_requestor} | Approval Response | Approval requester |
| {$approval_request_date} | Approval Response | Approval request date |
| {$indicator_id} | System health alerts | Health 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.
