Skip to main content

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

The number of actions that can be run per hour is limited 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. Classic UI. In the main Sumo Logic menu, select Automation.
    New UI. In the main Sumo Logic menu, select Automation > Playbooks. You can also click the Go To... menu at the top of the screen and select Playbooks.
    The list of playbooks displays.
    Automation Playbook list
  2. Select a playbook to see the elements in the workflow.
    Opened playbook
  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.
    Action example

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. Classic UI. In the main Sumo Logic menu, select Automation.
    New UI. In the main Sumo Logic menu, select Automation > Playbooks. You can also click the Go To... menu at the top of the screen and select Playbooks.
    Previously-created playbooks display.
  2. Click the + button to the left of Playbook.
    New playbook button
  3. A new configuration box will be displayed. Name your new playbook.
    New playbook dialog
  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.
    New playbook
  8. The Start node displays a + icon and an Edit icon. Click the Edit icon.
    Start node
    The Edit node dialog appears.
    Edit node dialog
  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:
  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.
    Add node

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.
    Start node
  3. The Add node page displays.
    Add node
  4. Select Action. The action node configuration screen displays.
    Add action node
  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.
    Configure action node
  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. Deselect the Cartesian product checkbox.
    warning

    Use the Cartesian product checkbox with caution. Large array fields in the input can result in the action being called many times, causing the action to exceed the actions limit. Only select this checkbox if you want to evaluate data from array input fields using the Cartesian product method. For example, suppose one input field is for signal name, and another is for signal value. If you have 2 arrays like this, and each array has 3 items, the Cartesian product evaluation pairs each item from the first set with each item from the second set, which will produce 9 pairs (3x3). Without Cartesian product evaluation, only matching position items are paired, which will produce 3 pairs (equal to the number of items).

  12. Once you have entered all the information requested, click Create. The action node is added to the playbook.
  13. Repeat the steps to add other action nodes.
  14. Add condition nodes if desired.
  15. When you are done configuring your playbook, click Save at the bottom of the window.
    Save the playbook
  16. When you are ready to allow the playbook to be used in automations, click the Publish button at the bottom of the playbook window.
    Publish the playbook

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.
    Add node button
  3. The Add node dialog displays.
    Add node
  4. Select Condition. The condition node configuration dialog displays.
    Add condition node
  5. Deselect the Cartesian product checkbox.
    warning

    Use the Cartesian product checkbox with caution. Large array fields in the input can result in the action being called many times, causing the action to exceed the actions limit. Only select this checkbox if you want to evaluate data from array input fields using the Cartesian product method. For example, suppose one input field is for signal name, and another is for signal value. If you have 2 arrays like this, and each array has 3 items, the Cartesian product evaluation pairs each item from the first set with each item from the second set, which will produce 9 pairs (3x3). Without Cartesian product evaluation, only matching position items are paired, which will produce 3 pairs (equal to the number of items).

  6. Click Create. The empty condition appears on the playbook.
  7. 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.
  8. 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.
    Edit a condition node
  9. The condition node configuration dialog displays again. Under Condition1, click Select a value.
    Select values for the condition
  10. Click Get Value and select from the drop-down menu whether the value will evaluate to true (bool), false (bool), or empty.
    Get values for the condition
  11. 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.
  12. 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.
  13. Now that Condition 1 is defined, you can choose to filter your results further by selecting an AND/OR operator to define another condition.
  14. Click Update.
  15. 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.
    Add node button
  3. The Add node dialog displays.
    Add node
  4. Select Task. The task node configuration dialog displays.
    Add task node
  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 Placeholder 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.

Example task node

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.

Complete task

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.
    Add node button
  3. The Add node dialog displays.
    Add node
  4. Select User Choice. The user choice node configuration dialog displays.
    Add user choice node
  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 Placeholder 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.

Example user choice node

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.
    Add node button
  3. The Add node dialog displays.
    Add node
  4. Select Playbook. The playbook node configuration dialog displays.
    Add playbook node
  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.
    Add filter node
  3. Click Filter. The filter node configuration dialog displays.
    Add filter node conditions
  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. Deselect the Cartesian product checkbox.
    warning

    Use the Cartesian product checkbox with caution. Large array fields in the input can result in the action being called many times, causing the action to exceed the actions limit. Only select this checkbox if you want to evaluate data from array input fields using the Cartesian product method. For example, suppose one input field is for signal name, and another is for signal value. If you have 2 arrays like this, and each array has 3 items, the Cartesian product evaluation pairs each item from the first set with each item from the second set, which will produce 9 pairs (3x3). Without Cartesian product evaluation, only matching position items are paired, which will produce 3 pairs (equal to the number of items).

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

Playbook versions

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.
    Export Playbook
  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.
    Import Playbook
  4. Select the desired file and click Import.
    Import Playbook modal

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.
    Run a playbook test
  4. In the Test playbook dialog, enter the requested information and click Run.
    Test playbook
  5. The results of the test are displayed in a new window labeled with the playbook name and (RUN TEST).
    Test results
  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.
    Filtered test results

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.

tip

To test a playbook before using it in an automation, see Test a playbook.

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.
    Playbook on an 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.
    An alert playbook with errors

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.
    Cloud SIEM automations
  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.
    A Cloud SIEM automation playbook with errors

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.
    Playbooks on an incident in Cloud SOAR
  3. Click Graph View in the upper-right and click > to page through the playbooks.
    Playbook in graph view in Cloud SOAR
  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.
    Failed actions on a playbook
  2. Click an action for an explanation of the problem.
    Reasons for failed actions on a playbook
  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.
    Failed action in playbook graph view
  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.
    Open playbook payload
  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.
    Playbook payload
  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).
Status
Legal
Privacy Statement
Terms of Use

Copyright © 2024 by Sumo Logic, Inc.