CACAO playbooks user guide

Overview

What are CACAO playbooks?

Unlike linear checklists, CACAO playbooks support branching logic, parallel execution, and automated actions to handle complex security scenarios.

CACAO playbooks are visual workflow templates that guide analysts through incident response procedures. They support:

• Branching Logic: Make decisions based on conditions (if/then/else/switch)

• Parallel Execution: Run multiple steps simultaneously

• Automation: Trigger external actions automatically when steps are ready

• Variable Tracking: Pass data between steps and track inputs/outputs

Key concepts

Playbook lifecycle

1. Draft stage

When you create a new playbook, it starts as a draft:

• Drafts can be edited freely using the visual editor

• Drafts are saved automatically as you work

• Drafts cannot be added to cases

• A "Draft" badge appears in the playbook list

2. Published stage

Publishing makes a playbook available for use:

• Published playbooks can be added to cases

• You can create new draft versions to make changes

• Multiple versions can coexist (one published, multiple drafts)

3. Case instance

When a playbook is added to a case:

• A new instance is created specific to that case

• Step statuses are tracked independently

• Variables are bound to case-specific values

• Progress is saved and visible to all case participants

Creating a playbook

Step 1: Open the playbook editor

1. Navigate to Playbooks from the main menu

2. Click Create CACAO Playbook

3. The visual editor opens in a new view

Step 2: Start step

Every playbook needs a start step:

1. The editor creates a "Start" node automatically

2. This defines where execution begins

3. Connect subsequent steps from the Start node

Step 3: Add workflow steps

Drag steps from the palette onto the canvas:

Step 4: Connect steps

1. Click and drag from a step's output connector

2. Drop onto another step's input connector

3. For conditional steps, connect each branch (true/false paths)

Step 5: Configure step properties

Click on any step to configure (noting that each step requires an "Agent" from the Agent Definitions)

• Name: A descriptive title for the step

• Description: Detailed instructions for the analyst

• Condition (for decision steps): The logic to evaluate

• Commands: Specific actions to perform

• Variables: Input and output data mappings

Step 6: Save and publish

1. Click Save to preserve your draft

2. When ready, click Publish to make it available

3. The playbook appears in the list without the "Draft" badge

Step types explained

Action steps

Action steps represent work to be done:

Manual actions:

• Display instructions for the analyst

• Analyst marks complete when finished

• Can include checklists, commands, or procedures

Automated actions:

• Linked to a Triggered Automation

• Execute automatically when the step becomes ready

• Results feed back into the workflow

If-condition steps

Create two-way branches based on conditions: 

Condition syntax:

• Reference variables: __variable_name__:value

• Comparisons: ==, !=, >, <

• Example: __ip_address__:value == '192.168.1.1'

Switch steps

Create multi-way branches: 

Parallel steps

Execute multiple paths simultaneously: 

Working with variables

Variable types

• Constant: Value is fixed and cannot be changed during execution

• External: Value must be provided when the playbook is added to a case

Using variables in steps

Reference variables in conditions and commands: 

Variable bindings

When adding a playbook to a case:

1. External variables prompt for values

2. Enter case-specific data (e.g., the suspicious IP being investigated)

3. Values are stored with the playbook instance

4. Variables can be updated as the workflow progresses

Adding automation to steps

What is step automation?

Automation connects playbook steps to external systems. When a step becomes "ready", Cydarm can automatically:

• Query threat intelligence APIs

• Create tickets in external systems

• Send notifications

• Execute scripts or commands

• Update case data

Linking automation to a step

1. Open the playbook in the editor

2. Click on an Action step

3. In the properties panel, find Linked Automation

4. Click Add Automation or Edit Automation

5. Configure the Triggered Automation (see below)

Creating a triggered automation

Triggered Automations define what happens when a step is ready:

1. Navigate to Settings > Triggered Automations

2. Click Create Automation

3. Configure:

   • Name: Descriptive name for the automation

   • Event Type: Select "Playbook Action Ready"

   • Condition: Matches the specific step and playbook version

   • Operation: The action to perform (API call, webhook, etc.)

Automation condition format

The condition automatically matches the step:

This ensures the automation only triggers for:

• The specific step (by UUID)

• Compatible playbook versions (>= specified version)

Best practices

1. Test in isolation: Verify automations work before linking to playbooks

2. Handle failures: Configure appropriate failure responses

3. Logging: Enable logging to troubleshoot automation issues
   
   

Using playbooks in cases

Adding a playbook to a case

1. Open the case in Cydarm

2. Navigate to the Playbooks tab

3. Click Add Playbook

4. Select the playbook from the list (only published playbooks appear)

5. Fill in any required external variables

6. Click Add

Viewing playbook progress

The playbook visualisation shows:

• Step status: Colour-coded by state (ready, in progress, complete, failed)

• Current position: Highlighted active steps

• Assignees: Who is responsible for each step

• Variable values: Current data flowing through the workflow

Updating step status

Click on a step to update its status:

Assigning steps

1. Click on a step in the playbook view

2. Select Assign from the step menu

3. Choose a team member from the list

4. The assignee receives notification of the assignment

Adding tags to steps

Tags help categorise and filter step work:

1. Click on a step

2. Select Add Tag

3. Choose or create a tag

4. Tags appear on the step and in case activity

Managing playbooks

Editing a published playbook

1. Navigate to Playbooks

2. Find the playbook and click Edit

3. A new draft version is created

4. Make your changes in the editor

5. Publish when ready (creates a new version)

Deleting a playbook

1. Navigate to Playbooks

2. Find the playbook and click Delete

3. Confirm the deletion

Note: Deleting a playbook does not affect instances already attached to cases.

Viewing playbook history

Each playbook maintains version history:

• View previous versions

• Compare changes between versions

• Revert to earlier versions if needed

Troubleshooting

1. Playbook not appearing in case add dialog

Cause: The playbook is still in draft status.

Solution: Open the playbook editor and click Publish.

2. Automation not triggering

Possible causes:

• Automation condition doesn't match the step UUID

• Version mismatch in condition

• Automation is disabled

• Connector or actuator not running

Solutions:

• Verify the step UUID matches the automation condition

• Check version compatibility (>= vs ==)

• Ensure the automation is enabled in Settings

• Verify actuators are running and connected

3. Step stuck in "Ready" status

Possible causes:

• No assignee designated

• Automation failed silently

• Waiting for manual action

Solutions:

• Assign the step to an analyst

• Check automation logs for errors

• Manually update status if automation failed

4. Variables not resolving

Possible causes:

• Variable name mismatch

• Variable not marked as external

• Value not provided when adding playbook

Solutions:

• Verify variable names match exactly (case-sensitive)

• Check variable is marked external in playbook definition

• Re-add the playbook and provide missing values

Best practices

Playbook design

1. Start simple: Begin with linear workflows, add complexity as needed

2. Use descriptive names: Clear step names help analysts understand the workflow

3. Document thoroughly: Include detailed descriptions and commands in each step

4. Plan for failure: Add error handling paths for critical steps

5. Reuse with sub-playbooks: Create modular playbooks for common procedures

Variable management

1. Name consistently: Use clear, descriptive variable names

2. Mark external appropriately: Only mark variables external if they need case-specific values

3. Use constants: For fixed values that shouldn't change during execution

4. Document variable purpose: Include descriptions for each variable

Automation

1. Test before linking: Verify automations work in isolation

2. Version appropriately: Use >= for forward compatibility

3. Monitor execution: Review automation logs regularly

4. Handle failures gracefully: Configure alternate paths for automation failures

Team collaboration

1. Assign owners: Designate playbook maintainers

2. Review before publishing: Have peers review playbook changes

3. Communicate changes: Notify team when playbooks are updated

4. Gather feedback: Improve playbooks based on analyst experience

FAQs

Q: Can I use the same playbook in multiple cases simultaneously?
A: Yes, each case gets its own independent instance of the playbook.

Q: What happens to running instances when I update a playbook?
A: Existing instances continue using their original version. New instances use the updated version.

Q: Can I duplicate a playbook?
A: Yes, use the duplicate function to create a copy that you can modify.

Q: How do I share playbooks between organisations?
A: Export the playbook as JSON and import it in the target organisation.

Q: Can automation update variables?
A: Yes, automation results can be mapped back to playbook variables.

Q: Is there a limit to playbook complexity?
A: There's no hard limit, but very complex playbooks may impact performance. Consider breaking into sub-playbooks.

Getting help

If you need assistance with CACAO playbooks:

• Contact your organisation's Cydarm administrator

• Submit a support ticket through the Cydarm support portal

• Review the Cydarm knowledge base for additional guides

---

Last updated: January 2025