Cacao

S4E playbooks are designed to align with the CACAO (Collaborative Automated Course of Action Operations) v2.0 standard published by OASIS. This page documents how S4E playbook constructs map to CACAO, and how to import and export between the two formats.

What is CACAO?

CACAO is an open standard for defining, sharing, and executing security playbooks across organizations and tools. It provides a common language for describing automated and semi-automated courses of action in response to cyber threats.

Key CACAO concepts:

  • Playbook --- A complete workflow definition with metadata, triggers, and steps.
  • Workflow Step --- An individual unit of work (action, condition, parallel, etc.).
  • Command --- The executable instruction within a step (HTTP API call, SSH command, etc.).
  • Target --- The system or asset a command operates on.
  • Agent --- The entity that executes the command.

Note

S4E supports CACAO Security Playbook v2.0 (OASIS Standard). Earlier versions are not supported.

Field Mapping

The following table shows how S4E playbook fields correspond to CACAO fields.

Playbook-Level Mapping

S4E Field CACAO Field Notes
id id (UUID format) S4E uses short IDs; CACAO requires UUIDs.
name name Direct mapping.
version playbook_variables.version CACAO uses variables for version tracking.
description description Direct mapping.
trigger workflow_start S4E trigger maps to CACAO start step.
steps workflow (step dictionary) S4E uses ordered array; CACAO uses a map.
tags labels Direct mapping.
on_failure on_failure Direct mapping.
timeout_minutes timeout CACAO uses seconds; conversion applied.

Step-Level Mapping

S4E Step Type CACAO Step Type Notes
action action Direct mapping. Command details differ.
condition if-condition S4E expression maps to CACAO condition.
parallel parallel Direct mapping. Branch handling is similar.
delay action (with delay) CACAO uses delay property on action steps.
approval action (manual) Mapped as manual action with human target.

Command Mapping

S4E Executor CACAO Command Type Notes
http http-api Direct mapping.
script bash Shell script execution.
opservant ssh or openioc Closest CACAO equivalent for agents.
webhook http-api Mapped as HTTP API command.

Importing CACAO Playbooks

Import a CACAO-format playbook into S4E using the API:

curl -X POST "https://api.s4e.io/api/playbooks/import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "cacao_v2",
    "playbook": {
      "type": "playbook",
      "spec_version": "cacao-2.0",
      "id": "playbook--a]1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Ransomware Response",
      "description": "Standard response to ransomware detection.",
      "workflow_start": "start--001",
      "workflow": {
        "start--001": {
          "type": "start",
          "on_completion": "action--isolate"
        },
        "action--isolate": {
          "type": "action",
          "name": "Isolate Affected Host",
          "commands": [{
            "type": "http-api",
            "command": "POST /api/actions/isolate"
          }],
          "on_completion": "end--001"
        },
        "end--001": {
          "type": "end"
        }
      }
    }
  }'

The import endpoint converts CACAO structure to S4E's native format, generating appropriate step IDs and action references.

Tip

Use "dry_run": true in the import request to preview the conversion without creating the playbook.

Exporting S4E Playbooks to CACAO

Export any S4E playbook in CACAO v2.0 format:

curl "https://api.s4e.io/api/playbooks/pb-critical-vuln-response/export?format=cacao_v2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o playbook-cacao.json

The exported JSON conforms to the CACAO v2.0 schema and can be shared with other CACAO-compatible tools.

Side-by-Side Comparison

S4E Format

id: pb-isolate-host
name: Isolate Compromised Host
version: "1.0.0"
trigger:
  event: finding.new
  conditions:
    severity: critical
steps:
  - id: notify
    type: action
    action_ref: act-slack-notify
    parameters:
      channel: "#incidents"
      message: "Isolating {{ finding.asset.name }}"
    on_success: isolate
  - id: isolate
    type: action
    action_ref: act-host-isolate
    parameters:
      asset_id: "{{ finding.asset.id }}"

CACAO v2.0 Equivalent

{
  "type": "playbook",
  "spec_version": "cacao-2.0",
  "id": "playbook--8a3b9c2d-1e4f-5678-90ab-cdef12345678",
  "name": "Isolate Compromised Host",
  "description": "Isolate a compromised host when a critical finding is detected.",
  "playbook_types": ["prevention"],
  "created_by": "identity--s4e-platform",
  "workflow_start": "start--001",
  "workflow": {
    "start--001": {
      "type": "start",
      "on_completion": "action--notify"
    },
    "action--notify": {
      "type": "action",
      "name": "Notify via Slack",
      "commands": [{
        "type": "http-api",
        "command": "POST https://slack.com/api/chat.postMessage",
        "content_b64": "eyJjaGFubmVsIjoiI2luY2lkZW50cyIsInRleHQiOiJJc29sYXRpbmcgaG9zdCJ9"
      }],
      "on_completion": "action--isolate"
    },
    "action--isolate": {
      "type": "action",
      "name": "Isolate Host",
      "commands": [{
        "type": "http-api",
        "command": "POST https://api.s4e.io/api/actions/act-host-isolate/trigger"
      }],
      "on_completion": "end--001"
    },
    "end--001": {
      "type": "end"
    }
  }
}

Compliance Benefits

Adopting CACAO-compatible playbooks provides:

  • Interoperability --- Share playbooks with partners, ISACs, and industry peers using a common format.
  • Regulatory alignment --- Demonstrate standardized incident response procedures for audits.
  • Tool portability --- Migrate playbooks between CACAO-compatible SOAR platforms if needed.
  • Community sharing --- Contribute and consume playbooks from the CACAO community library.

Limitations

Area Limitation
Step ordering CACAO uses a graph (step references); S4E uses an ordered array. Circular references are not imported.
Custom executors S4E's opservant executor has no direct CACAO equivalent. It is mapped to http-api on export.
Variable syntax S4E uses {{ }} templates; CACAO uses $$variable$$. Conversion is automatic.
Approval steps CACAO does not have a native approval type. Mapped as manual action steps.
Triggers CACAO's trigger model differs. S4E event triggers are exported as start steps with metadata.

Warning

Always review imported playbooks before enabling them. Automated conversion may require manual adjustments for complex workflows.

Next Steps