Playbooks V2: Detailed Walkthrough

Summary: An in-depth guide to the Automation Playbooks feature, including a walkthrough of creating a Playbook from scratch, as well as how to modify settings on existing Playbooks.

For an introduction to Playbooks and their use in the RiskSense Platform, visit our Overview article. This guide presents a detailed walkthrough of the Playbook structure and components and how to create your first Playbook and associated Rules.

In this section, the structure of Playbooks will be introduced, and you will be shown how all the various components are displayed and categorized.

Every Playbook contains the following properties visible on the main list view:

In the Playbooks view pictured above, an expandable Detail Pane provides further information on each Playbook, including detailed information on its creation, next scheduled run, enumerated actions taken during the last run, number of assets findings modified, and a history of past Playbook executions. Clicking anywhere on the card outside the name will invoke this detail pane.

Clicking on the name of a Playbook within the card will bring you to the Playbook Rules View, where all the individual actions contained within the Playbook are shown.

Every Rule contains the following properties visible on the main list view:

The Playbook Rules view also features an expandable Detail Pane to show further information on each Rule, including an accompanying description and edit history.

This section will walk through how to create a new Playbook and accompanying Rules from start to finish. To begin, first, navigate to Automate > Playbooks.

If your organization has existing Playbooks, they will be shown here. If this is your first time setting up a Playbook, you will be presented with a prompt to create a new Playbook.

You will then be taken to the Create New Playbook wizard, where you can enter the information for your new Playbook. You will need to provide the following information to set up your automation:

Now that you have specified the required information click the Save button to generate your Playbook. You will then be taken back to the Playbooks view, and your newly created automation will be visible.

Now that we have a container for our automation, it’s time to provide explicit actions that we want our Playbook to carry out. You will notice that in the Playbooks view, our newly created Playbook is currently Disabled. This means that it’s not turned on yet and that we can make changes to it and create Rules while it’s disabled. Once we’ve finished setting it up, we can Enable the Playbook to execute on schedule as normal. We’ll complete this step at the end.

The Rules within a Playbook are executed sequentially in order. For now, we will only be creating a single rule. As you start to build your own Playbooks, note that the order of the Rules will be taken into account and can be modified later.

Navigate to Automate > Playbooks > Playbook Rules by clicking on the name of our Sample Playbook 1 created previously. Currently, this Playbook contains no Rules, so we’ll click the prompt to create a new one and invoke the Create New Rule wizard.

There are three key steps in setting up a new Rule:

Each of these steps is explained in depth below.

In the first step, we will choose an action that we would like our Rule to execute. Along with the action itself, we will need to choose a subject to work with, usually either an asset or finding type. Then, the target of the action will be specified, depending on which action is chosen. For example, the “Apply Tag” action’s targets include a list of existing tags in your organization. In contrast, the “Add to Group” action’s targets include a list of groups across your networks.

The following table lists all actions that can be automated using the Playbooks system.

For this walkthrough, let us choose the “Apply Tag” action. We will choose Host Findings for our subject and a sample existing tag from our organization to apply.

Once we have specified all the required information for the action to take, we now want to determine which Host Findings we want our automation to apply the tags on. To do this, we will need to provide our Rule with a filter to identify the desired findings or assets.

The Playbooks system utilizes saved filters within the RiskSense platform. If you do not yet have any saved filters, a link is provided which opens a new tab to the relevant list view, where you can create a new filter.

Suppose we would like our automation filter to apply this sample tag to all Host Findings with a VRR of 10. First, we will navigate to the Host Findings view via the “Create Host Finding Filter” button and create the appropriate filter.

Now we’ll save this filter under the name “VRR 10 Sample Filter” and return to the Create Rule tab. Clicking the refresh button within the wizard now displays the newly created saved filter, and we can select it for use in the Rule.

Note that filters for both assets and findings of a single type may be selected to narrow down the Rule's scope. For instance, a filter for Hosts may be used in conjunction with one for Host Findings.

Now that the details of our Rule have all been specified, we can choose to have the automation system notify a specified set of users via email when the Rule executes. The subject and body of the email can be customized, and the option to include an operational summary of the Rule’s execution details, including actions completed and runtime, is provided as well. No sensitive information is transmitted in this summary.

At any point during the Rule creation process, the name and description of the Rule can be specified at the top of the wizard. Once all the required information has been populated, click the blue Submit button to save our created Rule. We now have a fully functional Playbook ready to execute!

In this section, we will discuss how to modify the settings and structure of your Playbooks.

To modify the settings of a Playbook, it must first be in the Disabled state. By default, a newly created Playbook will always be disabled. This means that its configurations have been set, but it will not yet execute any actions. To have the automation begin running according to the designated schedule, we will need to Enable the Playbook.

To enable a single Playbook, click on the three-dot options menu on the right edge of the Playbook card, and select “Enable.”

To enable multiple Playbooks at once, select the checkboxes next to each one in the list view and select the “Enable” option from the Actions drop-down menu in the top right.

The Status of a Playbook shows one of four states: Enabled, Disabled, Running, or Deferred. As discussed above, an Enabled Playbook is configured to run at its scheduled time, and a Disabled Playbook will not run and can be configured.

A Playbook in the Running state is currently executing its operations, and its state and properties cannot be modified until the run is complete.

A Deferred Playbook is queued for operations and will begin executing as soon as its turn in the queue arrives. Playbooks in this state can also not be modified.

As discussed above, the Rules of a Playbook will execute in the exact order seen in the Playbook Rules list view sequentially. If you wish to modify this order, first ensure that the Playbook is Disabled. Click on the name of the Playbook whose Rules you wish to reorder, and then select the “Change Order” option in the top-right of the view.

The Change Rules Order wizard will then be presented. In this window, Rules may be rearranged by dragging and dropping them within the list. Arrow buttons to the right of each card can also be used to change the order. Once your rules are in the desired order, click the Save button to apply the configuration to your Playbook.

To delete an individual Rule from a disabled Playbook, click on the three-dot options menu to the right of that Rule’s card in the Playbook Rules view, and select “Delete.” A confirmation dialogue will appear; click “Submit” to successfully delete the Rule from the Playbook.

To delete a disabled Playbook, click on the three-dot options menu on that Playbook’s card in the Playbooks view, and select “Delete.” A confirmation dialogue will appear; click “Submit” to successfully delete the Playbook.

A Playbook can be executed outside of its normal scheduled time by Manually Running it from the Playbooks view. Note that the Playbook must be enabled to do so, and it cannot be currently queued or running.

To initiate a Manual Run of a Playbook, click on the three-dot options menu on that Playbook’s card in the Playbooks view, and select “Manually Run.” A confirmation dialogue will appear; click “Submit” to start the manual playbook execution.

You can transfer the ownership of a playbook to any eligible owner.

Prerequisite - The Playbook must be in Disabled state.

Procedure

In the RiskSense platform, a Tag Owner or Manager can choose to Lock a Tag, preventing it from being applied or modified from its currently set assets and/or findings. Alternatively, the RiskSense system can create a Locked Connector Tag when an API connector is run. RiskSense manages these locked connector tags, and they are also prevented from being applied to or removed from assets and/or findings. Locked Tags cannot be utilized in Playbooks. To utilize the Apply/Unapply Tag automation action, a new tag will need to be created.

Occasionally when creating a new Rule for a Playbook, you may notice that additional filters are attached to the Rule following its creation. These filters are added by the system automatically, and they function as an optimization safeguard to ensure that all Rules are operating as efficiently as possible. No action is required for this to occur; the system will create these additional filters as needed.

When building a new Playbook: