Using the rules engine
The Rules Engine automates monitoring, alerts, and workflow management. Use it to customize alerts for the events that matter most to your organization and to automate repetitive tasks. A rule defines the action to take when a set of conditions is met. Rules can alert your team to changes in Explorers, assets, scans, organizations, and sites, and they can tag assets or modify asset fields based on the results of a query.
Some ways to put the Rules Engine to work:
- Alert your team when new policy violations are identified.
- Modify asset fields when 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 organizations, sites, and users change.
Key concepts
Rules can help you stay on top of events as they happen and give you better visibility across your network, assets, and runZero deployment. A rule has four parts: an event, organization access, conditions, and an action. When the event happens and the conditions are met, runZero performs the configured action.
Events
Each rule begins with an event, which triggers it. An event can be based on a query or on a system-defined event. runZero has a library of system-defined events; the runZero events catalog lists them all. Choosing an event shows the conditions and actions available for it.
Organization access
A rule can serve any number of organizations. Any user with User role access to every organization associated with the rule can edit it, and any user with Viewer role access to at least one organization can read it. By default, a rule triggers for the currently selected organization.
Organization access on templates and channels only controls who can view and edit them, not which rules can use them. You can set up a rule for an organization with a template 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: the action runs only when the condition is met. You see only the conditions that apply to the event you chose. Conditions usually specify sites, organizations, and asset attributes for the event.
Actions
An action is what the rule does when the event occurs and every condition is met: send a notification to a channel, or modify an asset. Notifications need a channel and a template. Asset modifications can edit fields such as the OS vendor, OS product, OS version, hardware vendor, hardware product, hardware version, asset tags, and asset type.
Channels
A channel is how runZero tells you that an event occurred. You can create as many channels as you need, depending on who you want to reach and how. For example, a Slack channel might serve one team and an email list another.
Like rules, channels can serve any number of organizations. Any user with User role access to all associated organizations can manage a channel. Any user with Viewer role access to one or more organizations can view the channel details but can’t edit or create channels.
The message body uses default text from runZero and currently can’t be customized.
Create a rule
To create a rule, choose an event, define the conditions, and choose the 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
- Give the rule a descriptive name that tells you at a glance what it does.
- Choose the event you want as your trigger.
- Browse the list of predefined events. Use the left-hand categories to narrow the list, or the search field to filter by keyword.
- Choose ‘asset-query-results’ or ‘service-query-results’ to modify the fields of 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 selected.
- If you selected an asset or service query event, provide a query for the rule. The query runs against the site after the scan completes. Assets with data from non-runZero sources must be recent (seen in the last 30 days) to fall within the search, and runZero-scanned assets must be live.
- You can also scope the rule to a specific site or Explorer and, for some events, set minimum asset counts or a task type.
Step 4: Choose an action, and optionally select a specific channel or template
- An action sends a notification to the channel of your choice or modifies assets. For example, you can send an email when orphaned devices are found.
Step 5: Turn on and save the rule
- To activate the rule immediately, select the “Enable this rule” checkbox. Otherwise, save the rule and turn it on later.
- Save the rule when you’re done.
Choosing event types
Scan and asset event types can be noisy, but they are useful for tracking network changes over time. To 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 lists all rules. 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 it is limited to specific organizations.
- When the rule was last triggered.
- Whether the rule resulted in a processed action.
- When the rule was created and the username that created it.
A status of “skipped” means the rule’s preconditions weren’t met the last time it was processed, so no action was taken. A status of “processed” means its preconditions were met and its action was processed.
If processing a rule or sending a notification fails, the rule’s action status is set to “error”, and the error message appears as a tooltip on that status.
To build one of these rules step by step, follow the Alerting on asset and service changes playbook.