Skip to content

Page permalink

Always use the following permalink when referencing this page. It will remain unchanged in future help versions.

https://docs.sophos.com/fusion/customer/help/en-us/index.html?contextId=xdr-automations-playbooks

Playbooks overview

A playbook defines what actions run and when they run. Playbooks use one or more configured connections to perform actions automatically or on demand. You create playbooks from templates provided by Sophos or your organization.

To see your configured playbooks, playbook executions, templates, and schedules, go to Security Operations > Automations > Playbooks.

Playbook documentation

Each playbook includes setup and configuration guidance. To see the documentation, do one of the following:

  • When viewing playbook templates, click the Documentation tab.
  • When viewing configured playbooks, click View Documentation.
  • When configuring a playbook, click Documentation.

Configure a playbook

You use playbook templates to create playbooks in your tenant. A single template can be used to create as many playbooks as needed. For details, see Playbook templates.

The following sections provide you with details on the components you configure.

Playbook components

Playbooks are made up of a few essential components:

  • Playbook connections
  • Playbook execution settings
  • Inputs and settings

Note

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

Playbook 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 configured connection 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

You must configure the playbook's execution for the playbook to be able to run. There are three trigger types supported by Sophos XDR for execution:

  • User Initiated: Execute a playbook as a user-initiated action in Sophos XDR.
  • Platform Events: Execute a playbook based on events occurring within Sophos XDR.
  • Generic Trigger: Execute a playbook manually, on a schedule, or for a notification.

User Initiated

This trigger type requires the following configuration:

  • Category: Defines where the user-initiated action or auto-triggered output is available in Sophos XDR. There are currently two supported values:

    • Response Action: The user-initiated action shows in the relevant Actions menus.
    • Lookup Contextual Information: The output of the auto-triggered action shows in relevant Enrichment tabs.

  • Context: Context in which the action is available, which defines the expected input to the playbook.

  • Name: Defines the name for the action in Sophos XDR menus.

Platform Events

This trigger type requires the following configuration:

  • Source: Defines the source of the event in Sophos XDR, which determines what data the playbook will receive as input.
  • Events: What types of events cause the playbook to execute. These events include create, update, and delete. This event applies to the chosen source. For example, a platform event execution type with a case source and a create event would cause the playbook to run when a case is created.

Execution filter

You can use CEL expressions to further control when a playbook runs or when a user-initiated action is shown.

Note

Detection executions are currently limited to high and critical severity.

In the When does this playbook run? section, define the criteria that must be true for the playbook to run or for the user-initiated action to be available. This field supports Common Expression Language (CEL) as well as the inputs as defined by the source selected for the execution type. This field is not evaluated if the playbook is executed manually.

Tip

Click AI Expression Assistant above a CEL field in supported workflows to create CEL expressions from natural language descriptions. For more information, see AI Expression Assistant.

You can also use CEL Explorer to test expressions against specific inputs and see the results while you configure the workflow. For more information, see CEL Explorer.

Generic Trigger

This trigger type requires you to define the Playbook Usage as one of the following:

  • Playbook Schedule: This lets you schedule automatic executions of the playbook. Not all playbook templates support scheduled executions. See Playbook schedules.
  • Other: This lets you run the playbook manually. Not all playbook templates are designed for this purpose. Refer to the template's documentation to learn if it is designed to be executed manually.

Inputs and settings

Templates may require one or more inputs in order to configure the playbook to run as desired. Each template has documentation that describes the required inputs in more detail. Click Documentation at the top of the page to open the documentation in a new tab.

Friendly history field names

When a playbook or other automation changes a record, Sophos XDR shows an automation-related identity instead of a logged-in user..

The following identities are used for various automation actions:

  • Automatic Case: These are cases created by or appended to by the Automatic Case engine. They can result from rules executed by a provider on behalf of their sub-tenants or within each tenant based on tenant-level rules.
  • Automatic Evidence Sync: This label applies whenever the platform bulk-appends detection and event data to a case.
  • Automation: Changes made by playbooks and connectors running in Sophos XDR.
  • Sophos MDR: Encompasses automation and scripting leveraged in the delivery of our Sophos MDR services.