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

  1. Navigate to Administration > Notifications > Notifications
  2. Click Create Notification
  3. 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.

  1. Navigate to Administration > Notifications > Notifications
  2. Click Create Notification
  3. Enter "New Critical Vulnerability on a Critical Host" as the Title
  4. Select "Vulnerability" as the Data Model
  5. Select "After Insert" as the Event. This tells the system to send the notification when the vulnerability is first created.
  6. Create two conditions: [Host Equals to <critical host's IP address>] AND [Risk Rating Equals to High OR Risk Rating Equals to Critical].
  7. Select "Risk Analyst" in the Attributes field of the "Who Will Receive" section. This will send the notification to all risk analysts.
  8. Enter "New critical vulnerability on ${host.name}" as the Subject of the notification
  9. 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}
    
  10. 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.

  1. Navigate to Administration > Data Management > Data Models
  2. Open the Host data model
  3. Click Create Attribute
  4. Enter "Vulnerability Count" as the Title
  5. Select "Calculated" as the Type
  6. Enter current?.vulnerabilities?.size()?: 0 as the Calculation. This tells the system to look for the current total of vulnerabilities on this host.
  7. Select "Number" for Return Type
  8. Check "Active" under Options
  9. Click Create
  10. 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.

  1. Navigate to Administration > Notifications > Notification Scripts
  2. Click Create Notification Script
  3. Enter "Top Host Vulnerabilities" as the Title
  4. Select "Host" as the Data Model
  5. 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.

  1. Navigate to Administration > Notifications > Notifications
  2. Click Create Notification
  3. Enter "Host Report Card" as the Title
  4. Select "Host" as the Data Model
  5. 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.
  6. Select "Owner" in the Attributes field of the "Who Will Receive" section. This will send the notification to the host's owner.
  7. Enter "Weekly report card for ${host.name}" as the Subject of the notification
  8. 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}
    
  9. Click Create

4) Create the weekly schedule for the notification.

  1. Navigate to Administration > Notifications > Schedules
  2. Click Create Scheduled Notification
  3. Enter "Weekly Host Report Card" as the Title
  4. Select "Host Report Card" as the Notification
  5. Select "Weekly" for the Run field
  6. Select "Friday" for the Day field
  7. Enter "8:00:00 AM" for the Time field
  8. Click Create