A first look at the OASIS CACAO Roaster

To defend against threat actors and their tactics, techniques, and procedures organizations need to detect, investigate, prevent, mitigate, and remediate threats in cyber relevant time. To do this, organizations need to identify, create, document, and test the orchestration steps needed to achieve these outcomes. These steps, when grouped together, form a cyber security playbook that can be used to protect organizational systems, networks, data, and users.

From the CACAO v2 spec.

Some of you will associate security playbooks with SOAR products.

Take a look at Palo Alto’s XSOAR content pack library of playbooks.

Or Microsoft Sentinel’s playbook repository.

Such content is very useful when getting started with playbooks. Though here also lies the problem; vendor lock-in.

Vendors have their own proprietary way of defining a playbooks.

Compare these Crowdstrike actions that can be used in Microsoft Sentinel playbooks, and then this Crowdstrike command for Palo Alto XSOAR playbooks.

The two function the same, but are written in different ways.

The other half will be thinking of security playbooks as documented sets of actions to be completed when something happens (e.g. a security incident) to trigger the start of a playbook.

CACAO aims to solve for both sides of the fence with a single standard.

Introducing CACAO

A few years ago OASIS set out on defining a standard way for documenting security playbooks that are both human-understandable and machine-executable.

The Collaborative Automated Course of Action Operations (CACAO) Security Playbooks is a standards-track work that defines a playbook schema and taxonomy for the purpose of standardizing the way we create, document, and share security playbooks.

CACAO Security Playbooks Version 1.1.

At the time of writing the specification is still in draft state, and as a result adoption is very low. However, to me, the initiative shows real promise.

The video above gives a great overview as to how CACAO playbooks works and the problems it solves for.

That video was published in 2020. For a long time the barrier to entry to write CACAO playbooks was high. Essentially you had to author the underlying JSON by hand.

Jump forward almost four years and the team recently launched v2 of the spec:

And CACAO Roaster, a web application for generating, parsing and validating, manipulating, and visualizing CACAO v2.0 playbooks… hopefully solving the adoption problem.

I decided to take a look…


git clone https://github.com/opencybersecurityalliance/cacao-roaster
cd cacao-roaster
npm i
npm run start

Now you should be able to access the CACAO UI at: http://localhost:3000/

Playbook basics

Before trying to create my own, I’m going to import an existing on from the CACAO repository here to get a feel for how they are constructed:

Staring with the simplest example…

This contains one Action Step, simply to block a MAC address when the playbook is started.

The details of the step can be seen in the right hand panel after clicking the step;

They underlying JSON representing this part of the playbook is also available by toggling the view;

          "id": "action--6398eb05-3eb8-43f5-87d3-f24e07492a41",
          "type": "action",
          "name": "Block MAC address",
          "description": "This command blocks a MAC address on a switch.",
          "commands": [
                              "type": "ssh",
                              "command": "Switch(conf)#mac address-table static 3467.0933.341c vlan X drop"
          "agent": "individual--75baba7d-a198-4c5c-805c-af616b4f7a31",
          "targets": [
          "on_completion": "end--116cdac5-63f1-4d8f-b3a8-e5667936e9b6"

The key things to get your head around for this step, and other steps are three concepts;

  • commands: executed automatically or manually as part of an action step
  • agents / targets: agents are the entities that execute commands on or against targets

In this example the command is of type ssh, with the command being the SSH command to be executed when this step is triggered

Switch(conf)#mac address-table static 3467.0933.341c vlan X drop

This is fairly simple.

In the playbook JSON you’ll also find

  "agent_definitions": {
    "individual--75baba7d-a198-4c5c-805c-af616b4f7a31": {
      "type": "individual",
      "name": "Network Admin",
      "description": "The admin who responds to an alert by configuring a switch."
  "target_definitions": {
    "security-category--3c1daf98-7e22-4e0c-bb8c-6bd78159ca5d": {
      "type": "security-category",
      "name": "Switch",
      "category": ["switch"]

You can see both of these referenced (through ID) in the agent and targets properties of the playbook.

Here the agent is a network admin.

Agents can involve either manual or automated processing. Here it’s manual, the individual must perform the command. However, this could just as easily be automated.

For example an Agent might be a HTTP API (http-api). That is the HTTP API performs the command (in which case the command might be a REST API query).


"agent_definitions": {
  "http-api--7e9174ec-a293-43df-a72d-471c79e276bf": {
    "type": "http-api",
    "name": "Server 1",
    "address": {
      "dname": [ "server1.example.com" ]
    "authentication_info": "http-basic--c2557066-1ffe-440e-b474-fea8158ab202",
    "category": [ "server" ],
    "location": { ... }

You’ll see the authentication information is held in another JSON blob in the playbook (http-basic--c2557066-1ffe-440e-b474-fea8158ab202).

Targets, simply put, are where the commands are executed. In this case, a network switch.

Building out a playbook

It’s important to understand the other Workflow steps that are available.

  • Start Step: The start step workflow step is the starting point of a playbook and represents an explicit entry in the workflow to signify the start of a playbook
  • End Step: The end step workflow step is the ending point of a playbook or branch of step (e.g., a list of steps that are part of a parallel processing branch) and represents an explicit point in the workflow to signify the end of a playbook or branch of steps.
  • Action Step: The action step workflow step contains the actual commands to be executed by an agent against a set of targets. These commands are intended to be processed sequentially.
  • Parallel Step: The parallel step workflow step defines how to create steps that are processed in parallel. This workflow step allows playbook authors to define two or more steps that can be executed at the same time. For example, a playbook that responds to an incident may require both the network team and the desktop team to investigate and respond to a threat at the same time.

There are also Conditional Steps

  • if: The if condition step workflow step defines the ‘if-then-else’ conditional logic that can be used within the workflow of the playbook
  • while: The while condition step workflow step defines the ‘while’ conditional logic that can be used within the workflow of the playbook.
  • switch: The switch condition step workflow step defines the ‘switch’ condition logic that can be used within the workflow of the playbook.

There are also three ways in which steps can be joined

  • on completion (black arrow in CACAO Roaster)
  • on success (green)
  • on failure (red)

Hopefully this will be enough to get you started!

I’m looking forward to seeing how CACAO develops in the coming year, and if we’ll see any widespread adoption.