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 four things: events, organization access, 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.

Organization access

Each rule can be used by any number of organizations. Rules are editable by any user with User role access to every organization associated with the rule, and can be read by any user with Viewer role access to at least one organization. By default, a rule will be triggered for the currently selected organization.

Setting organizational access on templates and channels only specifies who can view and edit, not which rules can use them. You can set up a rule for an organization with a template and/or channel whose access does not include that organization, as long as you have at least Viewer role access to one or more organizations in the template or channel’s organization access list.

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 fields 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.

Much like rules, channels can also be utilized by any number of organizations, and managed by any user with User role access to all associated organizations. Similarly, any user with Viewer role access to one or more organizations will be able to view the channel details only, and may not edit or create new channels.

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 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 type and configure organization access

• Provide a descriptive name for the rule. Something that quickly that tells you what the rule does.
• Choose an event you want to use as your trigger.
• You can browse the list of available predefined events. Use the left-hand categories to narrow down the list, or the search field 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 and configured organization access, click Next.

Step 3: Define the conditions

• 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 may also set the scope to a specific site or Explorer, and sometimes, depending on the event, minimum asset counts or task type.

Step 4: Choose an action, and optionally select a specific channel or template

• 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 by selecting the “Enable this rule” checkbox. 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 organizations the rule applies to, if the rule has been limited to specific organizations.
• When the rule was last triggered.
• Whether the rule resulted in an action being processed or not.
• When the rule was created and the username that created it.

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 has been 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.