Posted by:

David Greenwood

David Greenwood, Chief of Signal

If you are reading this blog post via a 3rd party source it is very likely that many parts of it will not render correctly. Please view the post on for the full interactive viewing experience.

In this post I will introduce the basic concepts of OASIS CACAO playbooks and how they can be used.

Note: this tutorial is written for CACAO version 1.1 (published on 2022-03-01). Some of the concepts discussed might not be correct for future versions of CACAO.

What SOAR tool are you using? XSOAR? Phantom? FortiSOAR?

Security Orchestration, Automation and Response (SOAR) products are as popular as ever. Many ship with default workflows and playbooks to perform automated actions.

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

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.

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

These are just two examples. Almost all major SOAR products use their own standards. As such, there is no easy way to share commands and playbooks developed with users of other SOAR products, thus hindering knowledge transfer (as the content needs to be rewritten for each products which is no easy task).

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.

CACAO Playbooks are structured like so;

CACAO playbook structure

  • Metadata: information about what the playbook does
  • Workflow: defines the steps (the logic using commands and targets) a playbook executes
  • Data Markings: represent handling or sharing requirements.
  • Targets: defines the specific system that an action is taken on (e.g. a specific API endpoint)
  • Extensions: ability to extend the specification as required where a default CACAO component / property is not suited
  • Digital Signatures: ability to sign playbooks to ensure they are not tampered with

Under the hood, CACAO Playbooks are represented as JSON Objects with defined properties. The easiest way to demonstrate this is to walk-through the construction of a playbook, so lets jump in.


At the top-level of the CACAO playbook is metadata about it including properties like name, description, or labels.

Here’s an example;

    "type": "playbook",
    "spec_version": "1.1",
    "id": "playbook--6b74199d-42a6-43a1-99cb-75d52207a778",
    "name": "Prevent FuzzyPanda Malware",
    "description": "This playbook will block traffic to the FuzzyPanda data exfil site",
    "playbook_types": [
    "created_by": "identity--1191b708-423b-493a-bc2c-44ad792e68fe",
    "created": "2021-04-19T23:32:24.399Z",
    "modified": "2021-04-19T23:32:24.399Z",
    "valid_from": "2021-04-19T23:32:24.39964Z",
    "valid_until": "2021-12-31T23:59:59.999999Z",
    "derived_from": [
    "priority": 3,
    "severity": 70,
    "impact": 5,
    "labels": [

The full list of metadata properties can be viewed here.

If you looked closely you will have seen the use of a STIX 2.1 Identity Object in the created_by property.

I won’t explain all these properties in this introduction, instead focusing on the actual playbook functions. That said, the playbook_types properties in the metadata defines some of the use-cases for which CACAO playbooks can be implemented.


THe CACAO specification defines 7 playbook_types which describe the situations in which a playbooks workflow is best suited;

  • Notification playbook (notification): focused on the orchestration steps required to notify and disseminate information and other playbooks about a security event, incident, or other threat.
  • Detection playbook (detection): focused on the orchestration steps required to detect a known security event, other known or expected security-relevant activity, or for threat hunting.
  • Investigation playbook (investigation): focused on the orchestration steps required to investigate what a security event, incident, or other security-relevant activity has caused
  • Prevention playbook (prevention): focused on the orchestration steps required to prevent a known or expected security event, incident, or threat from occurring.
  • Mitigation playbook (mitigation): focused on the orchestration steps required to mitigate a security event or incident that has occurred when remediation is not initially possible.
  • Remediation playbook (remediation): focused on the orchestration steps required to remediate, resolve, or fix the resultant state of a security event or incident, and return the system, device, or network back to a nominal operating state.
  • Attack playbook (attack): focused on the orchestration steps required to execute a penetration test or attack simulation to test or verify security controls or identify vulnerabilities within an organisations environment.

At least one of these types must be assigned to each playbook using the playbook_types property. A playbook can have more than one playbook_types.

Data Marking Definitions

CACAO data marking definition objects contain detailed information about a specific data marking. Data markings typically represent handling or sharing requirements and are applied via the markings property in a playbook.

If you’re familiar with STIX 2.1, then the concept of marking definitions is very similar.

    "data_marking_definitions": {
        "marking-tlp--a099a2eb-1113-4368-9b17-d7ef75841239": {
        "type": "marking-tlp",
        "spec_version": "1.0",
        "id": "marking-tlp--a099a2eb-1113-4368-9b17-d7ef75841239",
        "created": "2021-04-19T23:32:24.399Z",
        "modified": "2021-04-19T23:32:24.399Z",
        "tlp_level": "TLP-GREEN"

CACAO natively supports the following markings;

  • Statement (marking-statement): The statement marking definition defines the representation of a textual marking statement (e.g., copyright, terms of use).
  • First Traffic Light Protocol (marking-tlp): The TLP marking definition. Either TLP:RED, TLP:AMBER, TLP:GREEN, TLP:WHITE
  • First Information Exchange Policy (marking-iep): The IEP marking definition.

Markings are applied to the whole playbook. So adding the TLP-GREEN property to the playbook, would mean everything inside the playbook is considered TLP-GREEN.

Next time: Building Workflows

Now you know how to package playbooks it’s time to start laying down their logic.

If you read some of the CACAO playbook specification you will have seen other properties like features, playbook_variables, and workflow.

These are some of the properties I can use to define such logic.

In the next post I will show you how to create steps in a workflow that will define how the CACAO playbook works.

CACAO Certification (Virtual and In Person)

The content used in this post is a small subset of our full training material used in our CACAO training.

If you want to join a select group of certified CACAO professionals, subscribe to our newsletter below to be notified of new course dates.

Discuss this post

Signals Corps Slack

Never miss an update

Sign up to receive new articles in your inbox as they published.