Collaborative Automated Course of Action Operations (CACAO) is a schema and taxonomy for cyber security playbooks. The CACAO specification describes how these playbooks can be created, documented, and shared in a structured and standardized way across organizational boundaries and technological solutions [CACAO-Security-Playbooks-v2.0].

This specification defines the CACAO Layout Extension for the purpose of visually representing CACAO playbooks accurately and consistently across implementations.

Status:

This document was last revised or approved by the OASIS Collaborative Automated Course of Action Operations (CACAO) for Cyber Security TC on the above date. The level of approval is also listed above. Check the "Latest version" location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=cacao#technical.

TC members should send comments on this document to the TC's email list. Others should send comments to the TC's public comment list, after subscribing to it by following the instructions at the "Send A Comment" button on the TC's web page at https://www.oasis-open.org/committees/cacao/.

This document is provided under the Non-Assertion Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. For information on whether any patents have been disclosed that may be essential to implementing this document, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC’s web page (https://www.oasis-open.org/committees/cacao/ipr.php).

Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.

Key words:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Citation format:

When referencing this document, the following citation format should be used:

[CACAO-Layout-Extension-v1.0]

CACAO Layout Extension Version 1.0. Edited by Vasileios Mavroeidis and Mateusz Zych. 16 January 2024. OASIS Committee Specification Draft 01. https://docs.oasis-open.org/cacao/layout-extension/v1.0/csd01/layout-extension-v1.0-csd01.html. Latest version: https://docs.oasis-open.org/cacao/layout-extension/v1.0/layout-extension-v1.0.html.

Notices:

Distributed under the terms of the OASIS IPR Policy, [https://www.oasis-open.org/policies-guidelines/ipr/], AS-IS, WITHOUT ANY IMPLIED OR EXPRESS WARRANTY; there is no warranty of MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE or NONINFRINGEMENT of the rights of others. For complete copyright information please see the Notices section in the appendix.

Table of Contents

1 Introduction 4

1.1 Document Conventions 4

1.2 Glossary 4

2 Key Concepts and Features 5

3.1 Layout Properties 6

4.3.1 Connection Type Enumeration 9

5 Layout Extension Definition 10

Appendix A. Examples 11

Appendix B. Security & Privacy Considerations 13

Appendix C. References 14

Appendix D. Acknowledgements 15

Appendix E. Revision History 17

Appendix F. Notices 18

1 Introduction

This specification defines the CACAO Layout Extension for the purpose of visually representing CACAO playbooks consistently across implementations. Further, this specification makes this mechanism available through the Extension Definition of CACAO (see section 5).

1.1 Document Conventions

The following color, font and font style conventions are used in this document:

● The Consolas font is used for all type names, property names and literals.

○ type names are in red with a light red background – string

○ property names are in bold style – type

○ literals (values) are in blue with a blue background – coordinates

● In a property table, if a common property is being redefined in some way, then the background is dark grey.

● All examples in this document are expressed in JSON. They are in Consolas 9-point font, with straight quotes, black text and a light grey background, and using 2-space indentation. JSON examples in this document are representations of JSON objects [RFC8259]. They should not be interpreted as string literals. The ordering of keys is insignificant. Whitespace before or after JSON structural characters in the examples are insignificant [RFC8259].

● Parts of the example may be omitted for conciseness and clarity. These omitted parts are denoted with the ellipses (...).

● The term "hyphen" is used throughout this document to refer to the ASCII hyphen or minus character (45_dec or 2D_hex), which in Unicode is "hyphen-minus", U+002D.

● Some URLs have been defanged. This specification gives no guidance on how to defang or re-fang content. It is done to help ensure that the example URLs cannot be used directly.

1.2 Glossary

CACAO - Collaborative Automated Course of Action Operations

JSON - JavaScript Object Notation as defined in [RFC7493] and [RFC8259]

𝕎 - Whole numbers as defined as the set {0,1,2,3…} or {x: x >= 0}

2 Key Concepts and Features

This section explains some key concepts and features used in this specification.

2.1 Vocabularies

Some properties in this specification use defined vocabularies. These vocabularies can be either open or closed. An open vocabulary (see section 10.13 of the CACAO specification [CACAO-Security-Playbooks-v2.0]) allows implementers to use additional values beyond what is currently defined in the specification. However, if a similar value is already in the vocabulary, that value MUST be used. Open vocabulary types have an -ov suffix. A closed vocabulary is effectively an enumeration and MUST be used as defined. Enumeration types have an -enum suffix.

Vocabularies defined in this specification enhance interoperability by increasing the likelihood that different entities use the exact same string to represent the same concept.

2.2 Data Types

This specification uses the following data types as defined in the CACAO specification [CACAO-Security-Playbooks-v2.0]: string, integer, list, enum, and identifier.

In addition, this specification defines three new data types: canvas, coordinates, and connection.

2.3 CACAO Layout

This specification defines Layout as an Extension to CACAO Security Playbooks to be used for visually/graphically representing CACAO playbooks in a consistent, repeatable, and accurate manner.

This specification defines one Extension Definition (as defined in section 5) for CACAO Playbooks and has the following identifier:

extension-definition--418ee24c-9cb1-46d9-afa5-309e01aabc7f

3 Layout

The Layout object (layout) defines the canvas size (meant to be used in the playbook metadata level - section 3.1 in the CACAO specification [CACAO-Security-Playbooks-v2.0]) and coordinates for Workflow Steps and Agent and Targets.

3.1 Layout Properties

Property Name	Data Type	Description
type (required)	string	The value of this property MUST be layout.
canvas (optional)	canvas	This property defines the canvas size. This property MUST be used only with the “playbook_extension” property at the metadata level of a CACAO playbook as defined in section 3.1 of the CACAO specification.
coordinates (optional)	coordinates	The coordinates of the visualized object in relation to the upper-left corner of the canvas. This property MUST be used with the “step_extensions” and/or “agent_target_extensions” CACAO properties.

Example 3.1

Layout object when used to define the size of the Canvas at the playbook metadata level (“playbook_extensions” property).

{

"type": "layout",

"canvas": { … }

}

Example 4.2

Layout object when used to define the Coordinates of the workflow steps and agent and targets and their connections (“step_extensions” or “agent_targets_extensions” properties).

{

"type": "layout",

"coordinates": { … }

}

4 Data Types

4.1 Canvas

The Canvas data type (canvas) indicates the overall size (in pixels) of the canvas that subsequent playbook elements will be displayed. This data type MUST only be populated when the Layout object is used in the playbook_extensions property in the Playbook object of CACAO (as described in Section 3.1 of the CACAO specification [CACAO-Security-Playbooks-v2.0]).

Property Name	Data Type	Description
width (required)	integer	A number (𝕎 - whole number) representing the width of the canvas. This number refers to pixels.
height (required)	integer	A number (𝕎 - whole number) representing the height of the canvas. This number refers to pixels.

Example 4.1

{

"width": 1000,

"height": 500

}

4.2 Coordinates

The Coordinates data type (coordinates) indicates the position (in pixels) of the midpoint of a visualized CACAO object relative to the upper left (origin - O) corner of a canvas, along with its connections (paths) to other objects. This data type MUST only be populated when the Layout object is used in the step_extension (in the Workflow Step object) and/or the agent_target_extension (in the Agent-Target object) properties.

Property Name	Data Type	Description
x (required)	integer	A number (𝕎 - whole number) representing the X coordinate of the midpoint of the object visualized relative to the upper-left (origin - O) corner of the canvas. This number refers to pixels.
y (required)	integer	A number (𝕎 - whole number) representing the Y coordinate of the midpoint of the object visualized relative to the upper-left (origin - O) corner of the canvas. This number refers to pixels.
outgoing_connections (optional)	list of connection	The outgoing connections (paths) of the object visualized.

Example 4.2

{

"x": 40,

"y": 30,

"outgoing_connections": [ ... ]

}

4.3 Connection

A Connection data type (connection) defines the position of an outgoing relation/path of a visualized CACAO object. It comprises a list of points (in pixels) that altogether represent a line. A CACAO object may have multiple outgoing connections, each one of them represented by a connection data type. A connection should have, at a minimum, two x and y values to represent a straight line (point to point).

Property Name	Data Type	Description
connection_type (required)	enum	The type of connection being used. The value of this property MUST come from the connection-type-enum enumeration.
x (required)	list of integer	A list of numbers (𝕎 - whole number) numbers (𝕎 - whole number) representing the X coordinates of the connection. The list MUST contain at least two values to represent one straight line. x1 and the last x coordinate of a path SHOULD represent the midpoint x coordinates of the two connected visualized objects. This property is strongly connected with the y property. Both x and y lists MUST have the same number of values defined, as they together create a point of the connection on the canvas (e.g., x1 with y1, x2 with y2, etc.).
y (required)	list of integer	A list of numbers (𝕎 - whole number) numbers (𝕎 - whole number) representing the Y coordinates of the connection. The list MUST contain at least two values to represent one straight line. y1 and the last y coordinate of a path SHOULD represent the midpoint y coordinates of the two connected visualized objects. This property is strongly connected with the x property. Both x and y lists MUST have the same number of values defined, as they together create a point of the connection on the canvas (e.g., x1 with y1, x2 with y2, etc.).
case (optional)	string	A string that represents the case value. This property MUST match a dictionary key as defined in the dictionary of a CACAO Switch Condition Step. This property MUST be used only with the CACAO Switch Condition Step.
next_step (optional)	identifier	An identifier that identifies the next step. This property MUST be used only with the CACAO Parallel Step.

4.3.1 Connection Type Enumeration

Enumeration Name: connection-type-enum

This section defines the following connection types. For more information about the meaning of each connection type, refer to the CACAO specification [CACAO-Security-Playbooks-v2.0].

Connection Type	Description
on-completion	This connection type is valid for all Workflow steps and is mutually exclusive with on-success and on-failure.
on-success	This connection type is valid for all Workflow steps and is mutually exclusive with on-completion.
on-failure	This connection type is valid for all Workflow steps. It is mutually exclusive with on-completion.
on-true	This connection type MUST only be used by If Condition Steps and While Condition Steps.
on-false	This connection type MUST only be used by If Condition Steps.
cases	This connection type MUST only be used by Switch Condition Steps.
next-steps	This connection type MUST only be used by Parallel Steps.

Example 4.3

The “on-completion” connection from a CACAO Workflow Step

{

"connection_type": "on-completion"

"x": [40, 90],

"y": [30, 30]

}

Example 4.4

Connection from a CACAO Switch Conditional Step

{

"connection_type": "cases"

"x": [40, 90],

"y": [30, 30],

"case": "1"

}

Example 4.5

Connection from a CACAO Parallel Step

{

"connection_type": "next-steps"

"x": [40, 90],

"y": [30, 30],

"next_step": "action--c6728da5-f96a-4ba8-a4eb-fda6f24c9d7f"

}

5 Layout Extension Definition

This section defines the Layout extension for CACAO Playbooks and has the following identifier:

extension-definition--418ee24c-9cb1-46d9-afa5-309e01aabc7f

The definition for this extension is as follows:

{

"type": "extension-definition",

"name": "CACAO Layout",

"description": "Extension definition for diagramming CACAO playbooks.",

"created_by": "identity--5abe695c-7bd5-4c31-8824-2528696cdbf1",

"schema": "https://raw.githubusercontent.com/oasis-tcs/cacao/master/Extensions/layout/schemas/layout.json",

"version": "1.0.0",

"external_references": [

{

"name": "CACAO Layout Specification.",

"description": "Specification for diagramming CACAO Playbooks.",

"source": "[CACAO-Layout-Extension-v1.0] CACAO Layout Extension Version 1.0. Edited by Vasileios Mavroeidis and Mateusz Zych. 16 January 2024. OASIS Committee Specification Draft 01. https://docs.oasis-open.org/cacao/layout-extension/v1.0/csd01/layout-extension-v1.0-csd01.html. Latest version: https://docs.oasis-open.org/cacao/layout-extension/v1.0/layout-extension-v1.0.html.",

"url": "https://docs.oasis-open.org/cacao/layout-extension/v1.0/layout-extension-v1.0.html"

}

]

}

Appendix A. Examples

The following example highlights how a CACAO Switch Condition Step is visualized using the Layout Extension. A complete example is available on the official CACAO TC GitHub [CACAO-TC-GitHub].

{

"type": "playbook",

"spec_version": "cacao-2.0",

"id": "playbook--aa1898b6-5251-49b4-aeb7-fd5e912583ff",

"name": "Example Playbook",

"description": "A CACAO playbook showcasing how to use the Layout extension.",

"created_by": "identity--5abe695c-7bd5-4c31-8824-2528696cdbf1",

"created": "2023-11-20T13:26:54.640Z",

"modified": "2023-11-20T13:26:54.640Z",

"revoked": false,

"workflow_start": "start--5820e9bf-35c0-4b36-a266-7c173a9edeb5",

"workflow": {

...

"switch-condition--72c55a11-5091-4714-8050-baa854d72eda": {

"type": "switch-condition",

"name": "switch case example",

"cases": {

"1": "action--4005472a-0b74-48c6-b04b-45bb8cf2b1ae",

"2": "action--63483dce-6122-4975-8c7c-795d2453243d",

"default": "action--9a4ef680-ba51-4c1b-9b2d-715caf06ef3a"

"on_completion": "action--9ae9e500-155e-4f63-a76e-a43856063f55",

"step_extensions": {

"extension-definition--418ee24c-9cb1-46d9-afa5-309e01aabc7f": {

"type": "layout",

"coordinates": {

"x": 690,

"y": 440,

"outgoing_connections": [

{

"connection_type": "on-completion",

"x": [810, 900],

"y": [470, 470]

{

"connection_type": "cases",

"x": [750, 750, 900],

"y": [500, 540, 540],

"case": "1"

{

"connection_type": "cases",

"x": [750, 750, 900],

"y": [500, 610, 610],

"case": "2"

{

"connection_type": "cases",

"x": [750, 750, 900],

"y": [500, 690, 690],

"case": "default"

}

]

}

...

"playbook_extension": {

"extension-definition--418ee24c-9cb1-46d9-afa5-309e01aabc7f": {

"type": "layout",

"canvas": {

"width": 1300,

"height": 800

}

"extension_definitions": {

"extension-definition--418ee24c-9cb1-46d9-afa5-309e01aabc7f": {

"type": "extension-definition",

"name": "CACAO Layout",

"description": "Extension definition for diagramming CACAO playbooks.",

"created_by": "identity--5abe695c-7bd5-4c31-8824-2528696cdbf1",

"schema": "https://raw.githubusercontent.com/oasis-tcs/cacao/master/Extensions/layout/schemas/layout.json",

"version": "1.0.0",

"external_references": [

{

"name": "CACAO Layout Specification.",

"description": "Specification for diagramming CACAO Playbooks graphically.",

"url": "https://docs.oasis-open.org/cacao/layout-extension/v1.0/layout-extension-v1.0.html"

}

]

}

Appendix B. Security & Privacy Considerations

See Appendix B from CACAO Security Playbooks Version 2.0 [CACAO-Security-Playbooks-v2.0].

Appendix C. References

[CACAO-Security-Playbooks-v2.0]

CACAO Security Playbooks Version 2.0. Edited by Bret Jordan and Allan Thomson. 27 November 2023. OASIS Committee Specification 01. https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html. Latest version: https://docs.oasisopen.org/cacao/security-playbooks/v2.0/security-playbooks-v2.0.html.

[RFC7493]

The I-JSON Message Format, RFC 7493, March 2014. [Online]. Available: https://www.rfc-editor.org/info/rfc7493

[RFC8259]

The JavaScript Object Notation (JSON) Data Interchange Format, RFC 8259, December 2017. [Online]. Available: https://www.rfc-editor.org/info/rfc8259.txt

[CACAO-TC-GitHub]

The official GitHub of the CACAO Technical Committee. [Online]. Available: https://github.com/oasis-tcs/cacao

Appendix D. Acknowledgements

Chairs:

Bret Jordan (jordan@afero.io), Afero

Allan Thomson (atcyber1000@gmail.com), Individual

Special Thanks:

Substantial contributions to this specification from the following individuals are gratefully acknowledged:

Bret Jordan, Afero

Allan Thomson, Individual

Mateusz Zych, University of Oslo & Cyentific AS

Vasileios Mavroeidis, University of Oslo & Sekoia.io

Participants:

The following individuals were members of this Technical Committee during the creation of this specification and their contributions are gratefully acknowledged:

Bret Jordan, Afero

Patrick Maroney, AT&T

Dean Thompson, Australia and New Zealand Banking Group (ANZ Bank)

Naasief Edross, Cisco Systems

Omar Santos, Cisco Systems

Michael Simonson, Cisco Systems

Jyoti Verma, Cisco Systems

Arsalan Iqbal, CTM360

Jane Ginn, Cyber Threat Intelligence Network, Inc. (CTIN)

Ryan Hohimer, Cyber Threat Intelligence Network, Inc. (CTIN)

Christian Hunt, Cyber Threat Intelligence Network, Inc. (CTIN)

Ben Ottoman, Cyber Threat Intelligence Network, Inc. (CTIN)

Christopher Robinson, Cyber Threat Intelligence Network, Inc. (CTIN)

Avkash Kathiriya, Cyware Labs

Ryan Joyce, DarkLight, Inc.

Paul Patrick, DarkLight, Inc.

Marlon Taylor, DHS Cybersecurity and Infrastructure Security Agency (CISA)

Francisco Luis de Andres Perez, Francisco Luis de Andrés Pérez

Stephanie Hazlewood, IBM

John Morris, IBM

Mahbod Tavallaee, IBM

Srinivas Tummalapenta, IBM

Terry MacDonald, Individual

Anil Saldanha, Individual

Allan Thomson, Individual

Rodger Frank, Johns Hopkins University Applied Physics Laboratory

Karin Marr, Johns Hopkins University Applied Physics Laboratory

Desiree Beck, Mitre Corporation

Richard Piazza, Mitre Corporation

David Kemp, National Security Agency

Stephen Banghart, NIST

Jason Keirstead, Cyware Labs

David Bizeul, Sekoia.io

Duncan Sparrell, sFractal Consulting LLC

Marco Caselli, Siemens AG

Manos Athanatos, Telecommunication Systems Institute

Franck Quinard, TIBCO Software Inc.

Frank Fransen, TNO

Luca Morgese Zangrandi, TNO

Mateusz Zych, University of Oslo & Cyentific AS

Vasileios Mavroeidis, University of Oslo & Sekoia.io

Appendix E. Revision History

Revision

Date

Editor(s)

Changes Made

2024-01-16

Vasileios Mavroeidis,

Mateusz Zych

Write up of Version 1.0.

Appendix F. Notices

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website: [https://www.oasis-open.org/policies-guidelines/ipr/]

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. OASIS AND ITS MEMBERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THIS DOCUMENT OR ANY PART THEREOF.

As stated in the OASIS IPR Policy, the following three paragraphs in brackets apply to OASIS Standards Final Deliverable documents (Committee Specifications, OASIS Standards, or Approved Errata).

[OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Standards Final Deliverable, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this deliverable.]

[OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this OASIS Standards Final Deliverable by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this OASIS Standards Final Deliverable. OASIS may include such claims on its website, but disclaims any obligation to do so.]

[OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this OASIS Standards Final Deliverable or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Standards Final Deliverable, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.]

The name "OASIS" is a trademark of OASIS, the owner and developer of this document, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, documents, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark/ for above guidance.