Skip to content

Playbooks Overview🔗

In Automation, a playbook defines what actions to take and when to take them using one or more configured connections. This allows actions to be performed in your environment automatically based on your configuration. Playbooks are defined through playbook templates, some of which are provided by Secureworks, and some of which may be defined by your organization.

Example of a Completed Playbook

Note

Each playbook has built-in documentation that walks through the steps to create a new playbook. Select Documentation from a playbook template or configured playbook in XDR to open this in a new tab and follow the guidance there.

What Makes up a Playbook?🔗

Playbooks are made up of a few essential components:

  • Required Connections
  • Playbook Execution
  • Inputs

Playbooks can be triggered by the XDR platform, by a user (as an action), or manually.

Important

Playbooks only allow you to configure options that are supported by the playbook template. Unsupported options are greyed out and cannot be configured.

Required Connections🔗

A typical playbook template contains one or more tasks, each of which calls upon a connector action. For that reason, most playbook templates require a connection to a connector that performs that action. When creating or configuring a playbook template, you must select a single connection for each connector that the template requires.

Note

Connectors and connections are versioned. The version of the selected connection must match that of the connector that the template requires.

Playbook Execution🔗

A playbook by itself doesn’t provide any value until it is executed. Define the playbook execution within XDR to determine how the playbook is initiated.

Execution Type🔗

There are three types of execution currently supported by XDR:

  • Platform — Execute a playbook based on events occurring within XDR
  • User-initiated — Execute a playbook as a user-initiated action in XDR
  • Generic — Execute a playbook manually, on a schedule, or for a notification

Platform: Source🔗

Platform execution requires a source that defines the context within XDR that determines what data the playbook will receive as input.

Platform: Events🔗

Platform initiation requires the end user to define the events that will cause the playbook to execute. These events include create, update, and delete. This event applies within the source defined above. For example, a platform trigger with an alert2 source and a create event would cause the playbook to execute when an alert is created.

User-initiated: Category🔗

Category defines the type of user-initiated execution. The category is used to define where the user-initiated action appears within XDR. There are currently two supported values: Response Action and Lookup Contextual Information.

User-initiated: Context🔗

Select the context in which the action is available, which defines the expected input to the playbook.

User-initiated: Name🔗

The Name field on a user-initiated execution allows the end user to define the name for the action within a menu in XDR.

Execution Filter🔗

Note

Alert executions are currently limited to High and Critical severity.

The When does this playbook run? section allows the end user to define custom criteria that must be true in order for the playbook to execute (if platform type) or for the action to appear (if user-initiated type). This field supports the Common Expression Language (CEL) as well as the inputs as defined by the source selected for the trigger. This field is not evaluated if the playbook is executed manually.

Tip

The CEL Helper displays where applicable to provide common CEL expressions for use in automation configurations.

CEL Helper

You can also use CEL Explorer to test CEL expressions against a specific type of input so that you can see the outcome of the expression while completing your configuration. For more information, see CEL Explorer.

Generic: Playbook Schedule🔗

Select Generic as the execution type and choose Playbook Schedule as the usage in order to schedule executions of the configured playbook to occur automatically. Not all playbook templates support scheduled executions. See Playbook Scheduling for more information.

Inputs🔗

Templates may require one or more inputs in order to configure the playbook to run as desired. Each template will contain documentation that describes the required inputs in more detail.

View Playbooks Overview🔗

To view a summary of playbooks:

  1. From the Taegis Menu, select Automations > Playbooks.

  2. The Playbooks overview is displayed.

The summary cards at the top of the Playbooks overview display the following counts:

  • Total — The total number of playbook executions during the selected time period
  • Completed — The number of playbook executions successfully completed during the selected time period
  • Started — The number of playbooks executed during the selected time period currently in a Started state
  • Failed — The number of playbook executions that failed during the selected time period
  • Canceled — The number of playbook executions that were canceled during the selected time period

Use the date/time picker to change the displayed time period.

Playbook Summary Cards