Business rules

Introduction to business rules

Business rules are a general purpose tool for performing actions on datasets based on an event, e.g. setting an attribute's value or running a script. The goal of business rules is to automate as many tasks within the system as possible, saving time on repetitive maintenance and reducing human error.

Administration > Rules > Business Rules will take you to the Manage Business Rules page, which displays a list view of all existing business rules.

Table 1: List view contents

Columns Description
Title Title of the rule
Description Description of what the rule does
Order Order the rule is run in
Active Whether the rule is active. Inactive rules will not run and are effectively archived.
Created By Who created the rule
Last Updated When the rule was last updated

Create a new rule

Procedure

  1. Navigate to Administration > Rules > Business Rules
  2. Click the Create Rule button
  3. Fill in the following and click Create:

Table 2: New rule properties

Columns Description
Title Title of the rule. Title will be displayed wherever the rule appears in the UI.
Name Reference name for queries and scripts. The name can contain only letters, numbers, and underscores.
Description Description of the rule. The description will appear in the list view on the Manage Business Rules page. The search bar on the Manage Business Rules page searches the description field, so include phrases and keywords that will make the rule easy to search for later.
Data Model What data model the rule is run on. The data model selected will change options available in the When to Run and Actions sections of the form.
Order Determines when the rule runs relative to other rules with the same events and data model. If rules are not working as designed, check for interference from other rules on the same event.
Active Whether the rule is active. Inactive rules do not run and are effectively archived.
Events When the rule will run. Event times refer to changes to the objects in the data model (e.g. when a ticket is deleted). Event options are covered below.
Conditions Additional conditions for when the rule should run (e.g. when an attribute has a certain value). Conditions are covered below.
Actions Actions that will be performed when the business rule runs. Action options are covered below.
Accessible From Specifies whether this rule 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 run a business rule.

Table 3: Event options

Event Description
After Sync If no data model is selected, “after sync” is an available event. “After sync” rules will run after the selected data source is synced.
After Sync and Calculations If no data model is selected, “after sync and calculations” is an available event. “After sync and calculations” rules will run after the selected data source has been synced and its calculated attributes recalculated.
On Startup If no data model is selected, “on startup” is an available event. “On startup” rules will run after the application starts up after a reboot.
Before/After Delete Rule will run before or after any instance of the selected data model is deleted.
Before/After Update Rule will run before or after any instance of the selected data model is updated.
Before/After Insert Rule will run before or after any new instance of the selected data model is created.
Before/After Calculate Rule will run before or after any instance of the selected data model has calculated attributes recalculated.

Conditions

Conditions allow you specify additional requirements beyond an event that will determine whether a rule is run.

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.

Actions

Actions are what will be performed when the event and conditions are met. Actions run in the order in which they appear on the list of actions, and can be dragged and dropped to change their order.

Table 5: Action options

Action Description
Create/Update/Delete Creates/updates/deletes an object in an external system, e.g. ServiceNow
Set attribute value Sets an attribute on the rule's data model to a specified value
Run script Runs a Groovy script

Edit/delete a rule

Existing rules 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: Close vulnerabilities on decommissioned hosts

A host may be decommissioned while it still has vulnerabilities associated with it. Rather than letting the orphaned vulnerabilities sit in your Brinqa application forever, it's possible to close them using a business rule. This tutorial will cover how to create a business rule that moves vulnerabilities to closed status when their host's status is set to "retired".

This tutorial requires your host data model to have an attribute "Status" which is mapped to a data source that provides host status data (e.g. Rapid7 Nexpose).

Procedure

  1. Navigate to Administration > Rules > Business Rules
  2. Click the Create Rule button
  3. Enter "Retired Host Handler" for the Title
  4. (Optional) Enter a Description like "Closes all associated vulnerabilities when a host is retired."
  5. Select "Host" as the Data Model. Host is selected instead of vulnerability because the event that should run the rule occurs on host datasets.
  6. Enter "1" as the Order, unless other business rules on hosts take precendence.
  7. Select "After Update" for the Event. This will cause the rule to run after a host is updated.
  8. Set the Condition to "Status Equals to Retired", replacing "Retired" with whatever wording your scanner uses for deactivated hosts. This will cause the rule to run only after a host's status is updated specifically to that deactivated state.
  9. Click Add Action
  10. Select "Run script" as the Action. Because the rule references the host data model, vulnerability status must be set with a script rather than via the "Set attribute" action.
  11. Enter the following into the script field and click Create:
    def closed = "Closed"
    
    //Close all vulnerabilities
    current.vulnerabilities?.each { vuln ->
        if (vuln && vuln.status != closed) {
            vuln.status = closed
        }
    
    } 
    
  12. Using the Accessible from field, choose whether this rule should be available to all your Brinqa applications or only the application you are currently administrating.
  13. Click Create