Notifications
Introduction to notifications¶
Administrators can create email notifications to announce events and send status reports automatically.
Notifications are populated with data using generic variables that pull in the correct data at the time the notification is produced. For example, the variable ${host.riskScore} will display the current risk score of the host generating the notification. Variables eliminate the need for users to manually enter the most current data into notifications.
Administration > Notifications > Notifications will take you to the Manage Notifications page, which displays a list view of all existing notifications.
Table 1: List view contents
Columns | Description |
---|---|
Title | Title of notification |
Description | Description of notification |
Order | Order notification will run in when multiple notifications are scheduled for the same event |
Created Date | Date the notification was created |
Last Updated | Date the notification was last updated |
Create a new notification¶
- Navigate to Administration > Notifications > Notifications
- Click Create Notification
- Fill in the following and click Create:
Table 2: New notification properties
Field | Description |
---|---|
Title | Title of the notification. The title will be displayed wherever the notification appears in the UI. |
Description | Description of the notification. Description is displayed on the notification list view and can be searched from the list view search bar. |
Data Model | Data model to draw data from. The data model selected will change the variables available while building the notification. |
Events | Events that will cause the notification to be sent. No events need to be chosen if a schedule for the notification is created. Events will be covered below. |
Conditions | Additional conditions for when the notification should be sent. E.g. when a new vulnerability is created only if that vulnerability has a risk score equal to 10. Conditions will be covered below. |
Users | Specific users who should receive the notification. |
Roles | Roles that should receive the notification. |
Attributes | Makes the recipient a user reference attribute (e.g. host owner). |
Email Addresses | Email addresses to receive the notification. This field should be used to send notifications to people who are not users within the system. |
Send a single email for all recipients | Sends a single group email rather than an individual email to each listed recipient. |
Email Template | Selects a mail template. Mail templates can be created on the Mail Templates page. |
Subject | Subject line for emails created by this notification. Variables can be copied into the subject field, allowing for more informative subjects like “Weekly status report for ${host.name}” where ${host.name} is replaced by the particular host name. |
Select Data Model | Enters variables into the notifications that pull current data from the specified data model when the notification is sent. E.g. ${host.riskScore} would pull in the current risk score for the host generating the notification. |
Select Notification Script | Enters a variable that represents a script created in the notificiation scripts section. Script must reference the same data model as the notification. |
HTML Message | HTML structured version of this notification. The WYSIWYG editor will create HTML tags for on the back end (visible if you click the “Switch to advanced editor” button) or enter your own tags manually in the advanced editor. |
Plain Text Message | Plain text version of this notification. If a message is entered both in the HTML and text boxes, email clients that require plain text will receive the plain text version, while others will receive the HTML version. |
Accessible from | Specifies whether this notification will be available to all Brinqa applications or only the application you are currently administrating. |
Events¶
The events field allows you to specify an event that will generate a notification.
Table 3: Event options
Event | Description |
---|---|
After Sync | If no data model is selected, “after sync” is an available event. “After sync” notifications will generate after the specified data source and data mapping(s) are synced. |
After Sync and Calculations | If no data model is selected, “after sync and calculations” is an available event. “After sync and calculations” notifications will generate after the specified data source and data mapping(s) are synced and their calculated attributes recalculated. |
On Startup | If no data model is selected, “on startup” is an available event. “On startup” notifications will generate after the application starts up. |
Before/After Delete | Notification will generate before or after any instance of the selected data model is deleted. |
Before/After Update | Notification will generate before or after any instance of the selected data model is updated. |
Before/After Insert | Notification will generate before or after any new instance of the selected data model is created. |
Before/After Calculate | Notification will generate before or after any instance of the selected data model has calculated attribute recalculated. |
Conditions¶
Conditions allow you specify additional requirements beyond an event that will determine whether a notification is generated.
Table 4. Condition interface
Element | Description |
---|---|
Add AND Clause | Specifies conditions that must be met. (E.g. owner is Dave) |
Add OR Clause | Specifies an alternate set of conditions that could be met. (E.g. owner is Dave OR owner is Marg) |
Reset Filters | Clears all the filter options. |
Attribute | Attribute referenced for the condition. (E.g. owner) |
Operator | Operator for the specified value. (E.g. greater than, equal to, is not, contains) |
Value | Value the operator compares the data to. (E.g. a specific name or host) |
AND | Adds an additional AND condition to the associated section. |
OR | Adds an OR between two different conditions within a clause (e.g. owner is Marg and status is New OR Active). These ORs must share the same attribute. E.g. Status is Active OR New, but not Status is Active OR Priority is Critical. |
Edit or delete a notification¶
Existing notifications can be edited or deleted by clicking the Actions button that appears to the right on mouseover of the entry on the list view.
TUTORIAL: Notification for new critical vulnerability on a critical host¶
This notification sends an email when a new high risk vulnerability is found on a critical host and gives information about that vulnerability.
- Navigate to Administration > Notifications > Notifications
- Click Create Notification
- Enter "New Critical Vulnerability on a Critical Host" as the Title
- Select "Vulnerability" as the Data Model
- Select "After Insert" as the Event. This tells the system to send the notification when the vulnerability is first created.
- Create two conditions: [Host Equals to <critical host's IP address>] AND [Risk Rating Equals to High OR Risk Rating Equals to Critical].
- Select "Risk Analyst" in the Attributes field of the "Who Will Receive" section. This will send the notification to all risk analysts.
- Enter "New critical vulnerability on ${host.name}" as the Subject of the notification
- Enter the following in the HTML Message field:
A new high risk vulnerability has been found on the following critical host: ${vulnerability.host.name}.<br> This host is associated with ${vulnerability.host.business_service}.<br><br> Title: ${vulnerability.title}<br> Diagnosis: ${vulnerability.diagnosis}
- Click Create
TUTORIAL: Weekly host report card¶
This notification sends a "report card" to a host owner every week detailing the health of their host. The report card includes the host's current risk rating, the number of vulnerabilities on it, and what its top ten vulnerabilities are.
1) Create a "vulnerability count" attribute on the Host data model.¶
One piece of data the host report card should contain is a count of how many vulnerabilities are currently on the host. To get this data, we need to create a new calculated attribute on the host data model that totals the number of vulnerabilities on the host.
- Navigate to Administration > Data Management > Data Models
- Open the Host data model
- Click Create Attribute
- Enter "Vulnerability Count" as the Title
- Select "Calculated" as the Type
- Enter
current?.vulnerabilities?.size()?: 0
as the Calculation. This tells the system to look for the current total of vulnerabilities on this host. - Select "Number" for Return Type
- Check "Active" under Options
- Click Create
- Click Update. It's important to remember this step, since this saves the change just made to the data model.
2) Create a script to return the top ten highest risk vulnerabilities on a host.¶
This script will return the top ten highest risk vulnerabilities on a host and structure them in a table. Once the script is created, it can be referenced in the notification we create.
- Navigate to Administration > Notifications > Notification Scripts
- Click Create Notification Script
- Enter "Top Host Vulnerabilities" as the Title
- Select "Host" as the Data Model
- Enter the following in the Script field and click Create:
// Start table tag
template.write "<table>"
// Write the table headers
template.write "<thead>"
template.write "<tr>"
def headers = ["Title", "CVE", "Type", "Diagnosis", "CVSS Base Score", "Severity", "Risk Rating"]
def attributes = ["title", "cveId", "type", "diagnosis", "cvssBaseScore", "severity", "riskRating"]
headers.each { header ->
template.write "<td><p><strong><span>${header}</span></strong></p></td>"
}
}
template.write "</tr>"
template.write "</thead>"
// Write a table row for the top 10 vulnerability associated with this host sorted by risk score
def all_vulnerabilities = current.vulnerabilities
def top_ten_vulnerabilities = all_vulnerabilities ? all_vulnerabilities.sort { -it.riskScore }[0..(all_vulnerabilities.size() > 10 ? 9 : all_vulnerabilities.size()] : []
top_ten_vulnerabilities?.eachWithIndex { vulnerability, idx ->
template.write "<tr>"
attributes.each { attribute ->
template.write "<td><p>${vulnerability."${attribute}"}</p></td>"
}
template.write "</tr>"
}
// End table tag
template.write "</table>"
3) Create the notification.¶
- Navigate to Administration > Notifications > Notifications
- Click Create Notification
- Enter "Host Report Card" as the Title
- Select "Host" as the Data Model
- Leave the Events section blank. Instead of sending this notification based on an event, we will schedule it to send every week using the separate scheduling module.
- Select "Owner" in the Attributes field of the "Who Will Receive" section. This will send the notification to the host's owner.
- Enter "Weekly report card for ${host.name}" as the Subject of the notification
- Enter the following in the HTML Message field:
The risk rating for your host ${host.ipAddress} is: ${host.riskRating}. This host currently has ${host.vulnerability_count} vulnerabilites. The top 10 vulnerabilities on this host are:<br> ${script__top_host_vulnerabilities}
- Click Create
4) Create the weekly schedule for the notification.¶
- Navigate to Administration > Notifications > Schedules
- Click Create Scheduled Notification
- Enter "Weekly Host Report Card" as the Title
- Select "Host Report Card" as the Notification
- Select "Weekly" for the Run field
- Select "Friday" for the Day field
- Enter "8:00:00 AM" for the Time field
- Click Create