Automation playbooks are a group of actions you want to take to achieve a goal. Playbooks can range from the simple (“Email my security mailing list”) to the complex (“Notify an on-call phone tree, network isolate any affected endpoints, and begin remediation”).

An action is the specific action taken by the automation, whether it be sending an email, calling a phone, changing a firewall rule, or sending an alert to your SIEM. 

Red Canary playbooks are designed to balance ease of use against complex use cases. For now, we’ve left out complex branching and flow control, but included error handling logic to give playbooks the best chance of achieving their purpose.

A playbook is executed by a trigger or a manual execution that immediately executes each action in the playbook. 

Because execution speed is critical during remediation and actions may take minutes to complete, all playbook actions are launched simultaneously when the playbook is executed. 

When each playbook action executes, the action can either succeed or fail. If the action fails, it will be retried 25 times on an exponential backoff scale (out to about 21 days). These retries are critical because the web services that actions interact with (such as Slack, PagerDuty, etc) are not always available, thus endpoint actions may be executing against endpoints that are temporarily offline.

Creating a playbook

To create a playbook associated with a trigger:

1. Click Add a Playbook next to any trigger.
2. Click Create a new Playbook.
3. Click the new playbook to begin editing.
4. Enter a name and description for the playbook (these changes will save automatically).

Playbooks are active by default. Click the Active slider to deactivate the playbook and prevent it from executing, or click the ICON_TRASH icon to permanently delete the playbook.

Adding actions to a playbook

Actions are how you define what should happen when a playbook is executed. 

To add an action to a playbook:

1. When viewing any playbook, click Add Action.
2. Click an action from the list of actions by product (to view these actions by outcome instead of product, click show actions by outcome).
3. Click Add to Playbook.
4. Customize the action as desired, then click Save.

Actions are active by default. Click the Active slider to deactivate the action and prevent it from executing, or click the ICON_TRASH icon to permanently delete the action.

Associating playbooks and triggers

Both triggers and playbooks are reusable so your automation is consistent and requires less work to define.

To associate an existing playbook to a trigger:

1. Click Add a Playbook next to any trigger.
2. Click the playbook you want associated with the trigger.

The playbook will now be executed when the trigger is triggered.

To remove a playbook’s association to a trigger:

1. When viewing any trigger, click the (X) icon next to the playbook.

The playbook will no longer be executed when the trigger is triggered (but it is not deleted).

Using interpolation to customize actions

Many fields in playbook actions support the interpolation of attributes from the event that triggered the action. For example, an action that sends an email might send the email to the user that acknowledged a detection ($Detection.marked_acknowledge_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 

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

Keep in mind that all interpolated fields will not 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.

Requiring approvals for an action

You can require that your team approve an action before it is executed to allow you to ease into full automation.

Learn more about easing into automation with action approvals.

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

To view a playbook’s execution history:

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.

What if I connect a trigger to a playbook with actions that don’t make sense?

The great thing about reusable triggers and playbooks is that they save you a lot of time when you need multiple triggers to call the same actions. But they also allow you to connect playbooks that are incompatible with a specific trigger.

We’re working on ways to prevent this in the future, but for now, make sure you don’t connect your “endpoint remediation” playbook to an When an audit log occurs trigger, or nothing will happen!