Using the rules engine

Community Platform

The Rules Engine is an automation framework for monitoring, alerts, and workflow management. You can use the Rules Engine to customize alerts for the events that matter most to your organization and automate repetitive tasks. At the heart of the Rule Engine are rules. A rule defines the action that is taken based on a set of conditions. You can create rules to proactively alert your team when there are changes to things like Explorers, assets, scans, organizations, and sites. You can also automate tagging and modification of asset fields based on the results of a query.

Some ways you can use the Rules Engine to help automate your workflow:

• Alert your team when new policy violations are identified.
• Modify asset fields when the assets match specific criteria.
• Bulk tag assets that match a specific query.
• Get a Slack notification when a query returns new results.
• Monitor when an Explorer goes offline in the runZero console.
• Know when there are changes to organizations, sites, and users.

Key concepts

Rules can help you stay on top of events as they happen and get better visibility across your network, assets, and your runZero deployment. To build a rule, you need to define three things: events, conditions, and actions. A rule determines that when a specific event happens, and certain conditions are met, the system will automatically perform the configured action.

Events

Each rule begins with an event. The event sets off the trigger and puts your rule into motion. An event can be based on a query or a system-defined event. runZero offers a library of system-defined events you can use to create your rules. Choosing any of these events will show the conditions and actions available.

Conditions

A condition narrows the scope of your rule. Unless the condition is met, the rule will not execute the action. You will only see conditions that apply for the event you have chosen. Generally, conditions specify sites, organizations, and asset attributes for the event.

Actions

An action executes your rule, if the event occurs, and the conditions meet all the criteria. An action can be a notification to a channel or it can be a modification to an asset. What you will need to configure depends on the action type. For notifications, you’ll need to specify the notification channel and template. For asset modification, you can edit field like the OS vendor, OS product, OS version, hardware vendor, hardware product, hardware version, asset tags, and asset type.

Channels

A channel provides a way for you to communicate when a specific event has occurred. You can create multiple channels to support different types of communication needs. For example, you may want to create a Slack channel for one team, and an email list for another. It depends on what communication channels you prefer, and who you are trying to reach.

The body of the message uses default text from runZero. Customizations for messaging is currently unavailable.

Create a rule

Rules set the criteria for actions to to take place. To create a rule, you need to choose an event, define the conditions, and choose a resulting action.

Step 1: Open the Rules Engine

• From the Alerts menu, select the Rules submenu.
• Click Create Rule to open the editor.

Step 2: Choose an event

• Choose an event you want to use as your trigger.
• You can browse the list of available predefined events. Use the search to quickly filter by keyword.
• Choosing ‘asset-query-results’ or ‘service-query-results’ will allow you to modify the fields for the resulting assets.
• After you’ve chosen an event, click Configure rule.

Step 3: Define the conditions

• Provide a descriptive name for the rule. Something that quickly that tells you what the rule does.
• The conditions you can configure depend on the event you have selected.
• If you have an asset or service based query selected, you’ll need to provide a query for the rule. This query will run against the site after the scan completes. Note that assets with data from non-runZero sources must be recent (seen in the last 30 days) to be included in the scope of the search, and runZero-scanned assets must be live.
• You will also need to set the scope to an organization and site, and sometimes, depending on the event, minimum asset counts.

Step 4: Choose an action

• Actions can execute a notification to the channel of your choice or modify assets. For example, you can choose to send notifications via email when orphaned devices are found.

Step 5: Turn on and save the rule

• Turn the rule on if you want to activate it immediately. Otherwise, you can save the rule and turn it on later.
• Save the rule when you’re done.

Keep in mind

Using scan and asset event types can be noisy, but they are useful for tracking network changes over time. To help you focus on the events that matter most, track assets that go offline, assets that come back online, and newly discovered assets.

Monitoring the status of rules

The rules submenu of the Alerts page displays a list of all rules that have been created. For each rule, you can see:

• Whether the rule is enabled.
• The event that triggers processing of the rule.
• The organization the rule applies to, if the rule has been limited to a specific organization.
• When the rule was last triggered.
• Whether the rule resulted in an action being processed or not.

A status of “skipped” means that last time the rule was processed, its preconditions weren’t met, so no action was taken. A status of “processed” means that the rule’s preconditions were met, and its action was processed.

If there is an error processing a rule or sending a notification, the action status of the rule will be set to “error”. The error message can be seen as a tooltip on the error status.