Playbooks | Sumo Logic Docs (2024)

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.

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.

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.

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.

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 yourresults further by selecting an AND/OR operator to define anothercondition.
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.

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

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.
   

Troubleshoot playbooks​

You can run playbooks in automations for monitors, Cloud SIEM, or Cloud SOAR. If a playbook has a problem when it runs in an automation, an error message often displays in the playbook providing information about the problem.

Open playbooks that require investigation​

Open a playbook from an alert​

1. Access the alerts list.
2. Open an alert that uses a playbook.
3. On the alert details page, click the Playbooks button to see automated playbooks attached to the alert.
   
4. Hover your mouse over the icon to the right of the playbook to see its status. In the example above, the playbook completed with errors.
5. To investigate the problem, click the playbook name. The playbook opens in the Automation Service and any issues display in the results section.
   

Proceed to Investigate playbook problems below to look into playbook problems.

Open a playbook from Cloud SIEM​

1. Open an Insight or Entity that uses playbooks (that is, that has automations).
2. Click the Automations button at the top of the page to view the automations on the Insight or Entity.
   
3. Click View Playbook for a playbook you want to investigate. In the example above, the playbook we want to investigate completed with errors. The playbook opens in the Automation Service, and the issues display in the results section.
   

Proceed to Investigate playbook problems below to look into playbook problems.

Open a playbook from Cloud SOAR​

1. Open an Incident.
2. On the incident details page, select Operations > Playbooks. Playbooks appear that have run for the incident.
   
3. Click Graph View in the upper-right and click > to page through the playbooks.
   
4. Click a node on the playbook that displays an error.

Proceed to Investigate playbook problems below to look into playbook problems.

Investigate playbook problems​

After you have opened a playbook that requires investigation, follow the steps below to investigate problems with the playbook.

1. The Filtered Results section shows the status of actions that ran on the playbook. The example below shows two failed actions that require investigation.
   
2. Click an action for an explanation of the problem.
   
3. For more detailed information about the action, click the Graph View in the upper right and then click on the action. A pane opens that displays more information about the action.
   
4. Sometimes the playbook's payload will provide more information about why an action has a problem. To view the playbook's payload, click > to the right of the playbook name.
   
5. Examine the payload for information that might help you resolve the problem. For example, the payload may be able to tell you if a field has not been properly passed from a previous action, or a field was unintentionally left blank that the action requires.
   
6. Based on what you uncover during investigation, you may need to make changes to the playbook and then test the playbook to ensure it works correctly.

Common playbook problems​

Following are some common problems that can occur with playbooks:

• No response from the bridge
  The automation bridge is offline, or the bridge does not have the egress firewall settings to handle the outbound request.
• API rate limiting issues
  The vendor has capped the number of requests that can be made to their API in a certain time frame.
• HTTPS connection pool issues
  There are no available connections at the vendor, usually indicative of a vendor API health issue.
• A required field is empty that the action is looking for
  A field has not been properly passed from a previous action, or a field was unintentionally left blank that the action requires.
• Permission denied
  The API key is incorrect on the integration resource, or the account running the playbook has invalid credentials or insufficient permissions.
• You have exceeded the actions limit
  The number of actions that your organization can run per hour is limited to a certain threshold. Any actions that are launched beyond this actions limit will not run. You might exceed the limit if:
  • There are alert surges.
    
  • The playbook is not optimized properly and actions are stuck in a loop.
  • There are Cartesian flag issues (too many nested elements to process as part of the returned API result).