Understand Playbook Features and Attributes

For an overview on what a playbook is, and how to create and customize it, please watch this video. A playbook is initiated manually or by a trigger and executes each action in the playbook. Because execution speed is crucial during remediation, and actions can take minutes to complete, when the playbook is executed all playbook actions are started simultaneously.

When each playbook action executes, the action can either succeed or fail. If the action fails, it will retry 13 times over a 24 hour period on an exponential backoff scale (out to about 21 days). It is critical to perform these retries because the web services that actions interact with (Slack, PagerDuty, etc.) are not always available. Also endpoint actions may be run against endpoints that are temporarily offline.

Use interpolation to customize actions

Playbook actions include many fields where attributes are interpolated from the triggering event. For example, an action that sends an email might send the email to the user that acknowledged a detection ($Detection.marked_acknowledged_by_user.email) with a subject including the detection’s identifier ($Detection.human_id).

Fields that support interpolation are labeled with Type “$” to insert object attributes. These attributes can mixed with other text, such as:

Subject: New $Detection.severity severity detection on $Endpoint.hostname 

Note: Detection here refers to Threat.

To view the fields that can be interpolated into a playbook action, click Show list next to any interpolatable field.

Keep in mind that not all interpolated fields will be available for playbooks executed from every trigger. For example, the $ActivityMonitorMatch attributes will only be present for When a File Integrity Match occurs triggers.

Use the Acknowledged by email address Playbook attribute

Which attribute can I use in a playbook to pull the email address of the person who acknowledged a threat?

The $Detection.marked_acknowledged_by_user.email attribute will return the email address of the person who acknowledged the threat. In the case of an unacknowledged threat, however, the attribute name will be returned since no email address is available. If you create a Playbook that is triggered when a threat is remediated, but no one acknowledges the threat, there will be no email address to populate the attribute.

Note: Detection here refers to Threat.

View a playbook’s execution history

You can view the history of how a playbook has been edited and executed over time. This history includes activities such as actions being created or edited, the playbook being modified, and both automated and manual executions of the playbook.

1. When viewing any playbook, click History.

2. You will see the playbook’s history, including changes made to the playbook or its actions, times it has executed, etc.

Playbook Variable List

Red Canary has created a list of the most commonly used variables for each action. During an execution, select variables are available. For example, if an AuditLog creation triggered an action to run, $Detection variables won't be available. 

Variables embedded in custom payloads can also be formatted using JSON or XML if they need to be escaped. Use $JSON:Variable.name or$XML:Variable.name in place of $Variable.name to use this functionality.

You can select all objects within an array using brace notation ["*"].

For example, use $Model.attributes["users"]["*"]["name"] to parse to JSON object {"users": [{"name": "John Doe"}, {"name": "Jane Doe"}]} to receive both user's names.