Playbooks

A playbook is a predefined set of actions and conditional statements that run in an automated workflow to respond to a certain event or incident type. Playbooks can allow your organization's teams to respond to an incident in a consistent, focused, and repeatable fashion.

Playbooks can be configured to execute automatically without user intervention, acting on information from the incident, or can be executed in interactive mode, where user input is required to authorize predefined actions.

To run a playbook, add it to an automation. For places in Sumo Logic where you can use add playbooks to automations, see Where you can run automations.

note

By default, the actions limit is set to 200 per hour to prevent abuse of system resources or runaway processes. For more information, see Actions limit.

View playbooks

The following procedure describes how to view playbooks already installed in your environment. To add more playbooks, create a playbook, or install a playbook from App Central.

1. In the main Sumo Logic menu, select Automation.
   The list of playbooks displays.
   
2. Select a playbook to see the elements in the workflow.
   
3. Click the elements in the playbook to see their details. For example, click actions (the boxes in the flow) to see the integration resources that provide the actions.
   

Create a new playbook

Before you create your own playbook, first view playbooks to make sure there isn't one already that does what you want to accomplish, and also check to see if you can install a playbook from App Central that does what you need.

tip

The following procedure provides a brief introduction to how to create a playbook. For detailed examples of how to create playbooks, see the Cloud SIEM automation examples.

1. In the main Sumo Logic menu, select Automation.
   Previously-created playbooks display.
2. Click the + button to the left of Playbook.
   
3. A new configuration box will be displayed. Name your new playbook.
   
4. Select the incident Type. (For example, for Cloud SIEM automations, select CSE. For playbooks run from inside another playbook, you can select another incident type to associate with it, for example, Denial of Service, Malware, Phishing, and so on.)
5. Enter a Description of the playbook to help others understand how to use it.
6. Click Create. The new playbook appears in the list of available playbooks.
7. To configure the new playbook, select it from the list and click the Edit button at the bottom of the screen.
   
8. The Start node displays a + icon and an Edit icon. Click the Edit icon.
   
   The Edit node dialog appears.
   
9. Click the dropdown arrow on Add one or more params as a playbook input and select the kind of trigger that will execute the playbook:
   • Insight. An Insight from an automation in Cloud SIEM.
   • Entity. An Entity from an automation in Cloud SIEM.
   • Alert. An alert from an automated playbook in a monitor.
   • Parse from json. A payload from a parent playbook. (You can also select this option if you want to pass a custom payload from an alert.)
   • Leave blank if the trigger will be a Cloud SOAR incident or triage.
     
10. When you select one of these options, standard parameters for the trigger type are displayed. (If you select Parse from json, a box appears for you to enter the JSON payload.) Click the Remove icon to remove any parameters you don't want passed into the playbook, and if you want to add more parameters, click Add New Param at the bottom of the dialog.
11. Click Update. The playbook will display a black screen with a Start node and an End node. These nodes dictate the beginning and the end of the playbook's automation sequence. You can drag and drop them anywhere on the screen to allow you space to add multiple nodes between them.
12. To add the first node in the playbook, click the + on the Start node. The Add node page is displayed.
    

See Add nodes to a playbook for next steps.

Add nodes to a playbook

You can add nodes to a playbook when you either create a new playbook, or edit an existing playbook. To add a node to a playbook, hover your mouse over an existing node, such as the Start node, and click on the + button that appears on the node. A node is a step in a playbook. Nodes run in the order they are placed in a playbook. When all nodes run without error, the playbook is considered to have executed successfully.

See the following sections to learn how to add the following node types:

• Action. Automatically take specific actions such as enriching data or taking containment steps.
• Condition. Use conditional statements to define what actions should be taken in response to previous inputs.
• Playbook. Call other playbooks in response to conditional statements.
• Task. Assign a task to an individual.
• User Choice. Pause playbook execution until a user selects an option.
• Filter. Filter results from the preceding action.

Add an action node to a playbook

An action node in a playbook runs an operation. You can string actions together in the playbook to perform a workflow.

tip

For examples of adding actions to playbooks, see the Cloud SIEM automation examples.

info

Before you can add action nodes to a playbook, you must configure the connection for each integration resource that actions originate from.

1. Either create a new playbook as described above, or edit an existing playbook.
2. Hover your mouse over an existing node, such as the Start node, and click on the + button that appears.
   
   
3. The Add node page displays.
   
4. Select Action. The action node configuration screen displays.
   
5. Give a Node name that identifies the action being taken.
6. Select Manual execution if the node will require manual intervention to run. For example, an analyst may need to add information before executing the node.
7. Select the Integration to supply the action for the node.
8. Select the Type of action:
   • Containment. Performs some sort of response or remediation action, such as resetting a user's password or blocking a domain on your firewall.
   • Custom. Performs an action defined in a custom action YAML file. For an example of a custom action created for Cloud SIEM, see Advanced example: Configure a custom integration.
   • Enrichment. Enriches data with additional information, such as adding information about a known malicious IP address.
   • Notification. Sends a notification, for example, an email or a post in a messaging service.
   • Scheduled. Runs an action on a schedule once the playbook starts. For example, the action regularly checks a condition, and once the condition is met, the next playbook actions are executed.
   note

   The Type drop-down menu shows only the action types available in the selected integration.

9. Select the Action from the drop-down list. The dialog updates to show the integration resource that the action originates from, along with additional fields you must fill out to configure how you would like the action to be performed.
   
10. Fill out the fields with the specific information required by the action. For more information about the action, you can view the integration that provides the action.
11. Once you have entered all the information requested, click Create. The action node is added to the playbook.
12. Repeat the steps to add other action nodes.
13. Add condition nodes if desired.
14. When you are done configuring your playbook, click Save at the bottom of the window.
    
15. When you are ready to allow the playbook to be used in automations, click the Publish button at the bottom of the playbook window.
    

Add a condition node to a playbook

Define a conditional statement to be met before the next node can be executed.

tip

For examples of adding conditions to playbooks, see the Cloud SIEM automation examples.

1. Either create a new playbook as described above, or edit an existing playbook.
2. Hover your mouse over an existing node and click on the + button that appears.
   
   
3. The Add node dialog displays.
   
4. Select Condition. The condition node configuration dialog displays.
   
5. Click Create. The empty condition appears on the playbook.
6. Draw a line from a previous action node to the new condition node. This is required to allow the condition to evaluate the output values from the previous action.
7. Now that you've linked the condition to an action, hover the mouse over the condition node and click the edit button on the node to configure the condition settings.
   
8. The condition node configuration dialog displays again. Under Condition1, click Select a value.
   
9. Click Get Value and select from the drop-down menu whether the value will evaluate to true (bool), false (bool), or empty.
   
10. Under Get value from a previous action, select the value to feed into the condition. The example shows Get Devices and Playbook inputs that came from the previous action. (The condition must be linked by a line to the previous action node to receive outputs from the action.) Click the options from the previous action and select which output type (for example, hashes, IP addresses, domains) to evaluate and add it to the condition.
11. The selected output type will be displayed under Condition 1. Select which condition you would like for the output results to meet from the inequality operators below and click Select a value to define the condition.
12. Now that Condition 1 is defined, you can choose to filter your results further by selecting an AND/OR operator to define another condition.
13. Click Update.
14. When you create a new condition, you need to define what happens when the results meet one of your criteria. Draw lines to nodes to define the flow for success, failure, or other condition options.

Add a task node to a playbook

Define a task to assign to an individual, such as a security analyst.

1. Either create a new playbook as described above, or edit an existing playbook.
2. Hover your mouse over an existing node and click on the + button that appears.
   
3. The Add node dialog displays.
   
4. Select Task. The task node configuration dialog displays.
   
5. Give the node a Title that will display in the playbook.
6. Type a Description of the task the owner will perform.
   If desired, you can click the variable icon and click in the resulting box to display a list of variables you can add to the description.
7. For Authorizer, select the user assigning the task.
8. For Owner, select the user assigned the task.
9. In Due date, enter the number of days from the time when the action is run before the task is due.
10. Select mandatory if the task must be performed in order for the playbook to continue.
11. In Actual effort, enter the number of days expected to complete the task. (The owner will subsequently record the actual number of days spent on the effort.)
12. In Progress, select percent toward completion, for example, 10%, 20%, and so on. (The owner will subsequently record their progress.)
13. Select the Priority (Low, Normal, Important, or Urgent).
14. Click Create.

Following is an example of a task node in a running playbook. Click the Task node to view more about its status. Status information opens in a box to the left. In the following example of an action whose status is Waiting Owner, an Action Task appears in the box that describes user interaction required to complete the task.

If a user has an action marked as Waiting Owner, they must perform the steps needed to complete the Action Task. When done, they click the appropriate button at the bottom of the Waiting Owner action box (Approve, Approve & Close, or Reject). The action completes, and the subsequent remaining actions in the playbook run.

Add a user choice node to a playbook

When a user choice node is encountered, the execution will pause until a user selects an option. For example, after enrichment, a user could be asked whether to proceed with a containment action or to perform additional enrichment first. When a playbook is paused at a user choice node, the status of that playbook will say Waiting user interaction.

1. Either create a new playbook as described above, or edit an existing playbook.
2. Hover your mouse over an existing node and click on the + button that appears.
   
   
3. The Add node dialog displays.
   
4. Select User Choice. The user choice node configuration dialog displays.
   
5. Type a Question for the user. The answers they can choose from are provided by the Answers field.
   If desired, you can click the variable icon and click in the resulting box to display a list of variables you can add to the description.
6. In Answers, enter selections that the user can choose from. By default, success and failure are provided.
7. For Authorizer, select the authorizer of the user choice.
8. Select Expires if you want the user choice to expire after a set amount of time so that the playbook can proceed when no choice is made. If you do not select Expires, the playbook does not proceed until the user makes a choice. If you select Expires, fill out additional fields for the amount of time to pass before expiration, and the Default answer to automatically be chosen at the end of the expiration period.
9. Click Create.

Following is an example of a user choice node. Note the the node branches to the next node depending on the user's answer.

Add a playbook node to a playbook

Define a playbook to run inside another playbook. For example, you may want to call another playbook in response to a condition statement.

1. Either create a new playbook as described above, or edit an existing playbook.
2. Hover your mouse over an existing node and click on the + button that appears.
   
   
3. The Add node dialog displays.
   
4. Select Playbook. The playbook node configuration dialog displays.
   
5. In the Playbook drop-down menu, select the playbook to run.
6. Click Create.

Add a filter node to a playbook

A filter node filters results from the preceding action based on the condition you write. You can only add a filter node after an action node. For example, let's suppose that the action feeding into the filter has 10 results, but you want to filter out all but the best two results. You can write a condition in the filter to do the filtering.

1. Add an action node.
2. Hover your mouse over an action node and click the + button. The available nodes are displayed.
   
3. Click Filter. The filter node configuration dialog displays.
   
4. (Optional) Use Split by to select an output if it is a list (array) and you want to evaluate each item separately. Each item in the list is checked against the filter condition. If the condition is true for an item, the item is passed to the next node. (If you do not use the Split by field on an output that is a list, then if the condition is true for any item in the list, the entire list moves forward to the next node.)
5. Configure the conditions you want to use for filtering.
6. Click Create.

Test a playbook

You can test a playbook to verify that it works properly. The test results show the outcome as if the playbook actually ran.

1. Select a playbook.
2. Click the kebab button in the upper-right corner of the UI.
3. Select Run Test.
   
4. In the Test playbook dialog, enter the requested information and click Run.
   
5. The results of the test are displayed in a new window labeled with the playbook name and (RUN TEST).
   
6. Click the clock icon in the upper-right corner to see the testing history. Select Latest actions to see test results for all the actions on the playbook, or select items on the list to see results for individual actions.
   

Playbook versioning

Every time you edit a playbook, a new version of the playbook is saved. In the screen image below, notice how all the versions of the playbook are listed (#4 being the published version as indicated by the publish icon). Click on a version to edit it, and if you want, publish it. In this way, you maintain version control of your playbooks, and ensure that all versions are retained.

Import and export playbooks

With the mechanism to import and export playbooks, you can move a playbook, along with all its configurations, from one instance to another. The file should be in tar.gz format and adhere to naming conventions.

1. Click on the Export icon located next to the playbook name.
   
2. Upon clicking, the tar.gz archive download will be initiated.
3. At this point, you can open the archive, modify the configuration data, recreate a tar.gz archive, and upload it. To upload the file, click on the Import icon.
   
4. Select the desired file and click Import.
   

It is crucial that the file names inside the tar.gz adhere to the following format: <unique_id>.<file_representing_name>.<file_type>.<file_extension>, for example, 97ad7d6e.IP-Reputation.action.yaml