From 5f58db4e9d1fc4406a16d1948e7adf79b2469418 Mon Sep 17 00:00:00 2001 From: David Lemire Date: Wed, 10 Jul 2024 14:50:03 -0400 Subject: [PATCH 1/7] initial content for __openc2-responses__ plus other tuning --- openc2-cacao-ext-v1.0.md | 38 ++++++++++++++++++++++++++++++++++---- 1 file changed, 34 insertions(+), 4 deletions(-) diff --git a/openc2-cacao-ext-v1.0.md b/openc2-cacao-ext-v1.0.md index 76990e1..b088895 100644 --- a/openc2-cacao-ext-v1.0.md +++ b/openc2-cacao-ext-v1.0.md @@ -648,8 +648,7 @@ The `variable-type-ov` is extended as follows: |------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------| | `topic-list` | A list of strings that identify one or more publish / subscribe topics to which a message should be published. The format of the topic names should be appropriate to the messaging protocol being invoked. | `"type": "topic-list",`
`"value": ["oc2/cmd/"]` | -**Example 5.1 (`__mqtt-topics__`)**
-_The IDs used in this example are notional and for illustrative purposes, they do not represent real objects._*_ +**Example 5.1 (`__mqtt-topics__`)** ```json { @@ -677,8 +676,39 @@ The value of `__http-endpoints__` MUST be a `dictionary` of address(es) as defined for the CACAO `http-api` agent object (section 7.8 of the [[CACAO Playbooks](#cacao-security-playbooks-v20)] specification). -**Example 5.2 (`__http-endpoints__`)**
-*The IDs used in this example are notional and for illustrative purposes, they do not represent real objects.* +**Example 5.2 (`__http-endpoints__`)** + +```json +{ + "type": "playbook", + …, + "playbook_variables": { + "__http-endpoints__": { + "type": "dictionary", + "description": "A list of endpoints for delivery of an OpenC2 command via HTTP(S)", + "value": { + "url": ["https://oc2consumer.example.com"], + "ipv4" : ["11.22.33.44", "55.66.77.88"] + }, + "constant": false, + "external": true + } + } +} +``` + +## 5.3 `__openc2-responses__` Variable + +The `__openc2-responses` variable is used to aggregate the responses from one or +more OpenC2 Consumers for return to the calling `openc2 ` command action step. +The return of results from OpenC2 Consumer responses enables conditional +processing by subsequent action steps in the CACAO playbook. + +> To-Do: determine (or define) a suitable `variable-type-ov` for this variable. +> Since it's an `-ov` a new type may be in order. + + +**Example 5.3 (`__openc2-response__`)** ```json { From be36689b865419eed0fe8144b1be8f8af8b2ee5b Mon Sep 17 00:00:00 2001 From: David Lemire Date: Wed, 10 Jul 2024 14:53:43 -0400 Subject: [PATCH 2/7] add more explanatory text for __mqtt-topics__ --- openc2-cacao-ext-v1.0.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/openc2-cacao-ext-v1.0.md b/openc2-cacao-ext-v1.0.md index b088895..453e008 100644 --- a/openc2-cacao-ext-v1.0.md +++ b/openc2-cacao-ext-v1.0.md @@ -646,7 +646,14 @@ The `variable-type-ov` is extended as follows: | Vocabulary Value | Description | Examples | |------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------| -| `topic-list` | A list of strings that identify one or more publish / subscribe topics to which a message should be published. The format of the topic names should be appropriate to the messaging protocol being invoked. | `"type": "topic-list",`
`"value": ["oc2/cmd/"]` | +| `topic-list` | A list of strings that identify one or more publish / subscribe topics to which a message should be published. | `"type": "topic-list",`
`"value": ["oc2/cmd/"]` | + +MQTT offers great flexibility regarding topic naming. The format of the topic +names in the `topic-list` value should be appropriate to the application. The +[[OpenC2 MQTT Transfer Specification](#openc2-mqtt-v10)] provides specific +guidance regarding the use of MQTT topics for OpenC2 message transfer. Other +users of the MQTT Broker CACAO agent and `__mqtt-topics__` variable for publish +/ subscribe messaging should apply their own corresponding guidance. **Example 5.1 (`__mqtt-topics__`)** From e0e658e924158986e1106991a9c8295ec31f7b82 Mon Sep 17 00:00:00 2001 From: David Lemire Date: Wed, 10 Jul 2024 14:57:19 -0400 Subject: [PATCH 3/7] flesh out __openc2-responses__ description, example --- openc2-cacao-ext-v1.0.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/openc2-cacao-ext-v1.0.md b/openc2-cacao-ext-v1.0.md index 453e008..067d79c 100644 --- a/openc2-cacao-ext-v1.0.md +++ b/openc2-cacao-ext-v1.0.md @@ -677,7 +677,7 @@ users of the MQTT Broker CACAO agent and `__mqtt-topics__` variable for publish The `__http_endpoints__` variable is used to convey a list of endpoints to an OpenC2 command should be published. -The `variable-type-ov` for `__http-endpoints__` MUST be `dictionary`. +The `variable-type-ov` for `__http-endpoints__` MUST be `dictionary`. The value of `__http-endpoints__` MUST be a `dictionary` of address(es) as defined for the CACAO `http-api` agent object (section 7.8 of the [[CACAO @@ -711,9 +711,12 @@ more OpenC2 Consumers for return to the calling `openc2 ` command action step. The return of results from OpenC2 Consumer responses enables conditional processing by subsequent action steps in the CACAO playbook. -> To-Do: determine (or define) a suitable `variable-type-ov` for this variable. +> To-Do: confirm this is a suitable `variable-type-ov` for this variable. > Since it's an `-ov` a new type may be in order. +The `variable-type-ov` for `__openc2-responses__` MUST be `dictionary`. + +> To-Do: develop more realistic response content for this example **Example 5.3 (`__openc2-response__`)** @@ -722,15 +725,16 @@ processing by subsequent action steps in the CACAO playbook. "type": "playbook", …, "playbook_variables": { - "__http-endpoints__": { + "__openc2-response__": { "type": "dictionary", - "description": "A list of endpoints for delivery of an OpenC2 command via HTTP(S)", + "description": "A collection of responses for an OpenC2 command", "value": { - "url": ["https://oc2consumer.example.com"], - "ipv4" : ["11.22.33.44", "55.66.77.88"] + "device1": { }, + "device4": { }, + "device9": { } }, "constant": false, - "external": true + "external": false } } } From be6400977d56a63ecfe1551a672befd0eb487d1e Mon Sep 17 00:00:00 2001 From: David Lemire Date: Wed, 10 Jul 2024 15:02:13 -0400 Subject: [PATCH 4/7] tune section 5 intro text --- openc2-cacao-ext-v1.0.md | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/openc2-cacao-ext-v1.0.md b/openc2-cacao-ext-v1.0.md index 067d79c..1adfea5 100644 --- a/openc2-cacao-ext-v1.0.md +++ b/openc2-cacao-ext-v1.0.md @@ -625,35 +625,37 @@ Stateless Packet Filtering AP would specify the profile as follows: *** -# 5 Standard Playbook Variables +# 5 Standardized Playbook Variables -A set of standard CACAO variables are defined for use when invoking an MQTT -broker or OpenC2 HTTP API agent to handle message transfer. These CACAO +This section defines a set of standardized CACAO variables for use when invoking +an MQTT broker or OpenC2 HTTP API agent to handle message transfer. These CACAO variables are playbook variables whose values can be set internally via an `openc2` command object or from a `playbook-action` step in a calling playbook and accessed by the appropriate agent. +A standardized CACAO variable is also defined for returning OpenC2 responses to +the calling `openc2` playbook action step for subsequent processing. + ## 5.1 `__mqtt-topics__` Variable The `__mqtt-topics__` variable is used to convey a list of MQTT topics onto -which a message should be published. The `mqtt-broker` agent is general purpose -and not limited to sending and receiving OpenC2 commands and responses, however -when employed for that purpose the topics specified as `__mqtt-topics__:value` -should conform to the topic structure guidance in Section 2.2 of the -[[OpenC2 MQTT Transfer Specification](#openc2-mqtt-v10)]. - -The `variable-type-ov` is extended as follows: +which a message should be published. The `variable-type-ov` is extended as follows: | Vocabulary Value | Description | Examples | |------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------| | `topic-list` | A list of strings that identify one or more publish / subscribe topics to which a message should be published. | `"type": "topic-list",`
`"value": ["oc2/cmd/"]` | -MQTT offers great flexibility regarding topic naming. The format of the topic -names in the `topic-list` value should be appropriate to the application. The -[[OpenC2 MQTT Transfer Specification](#openc2-mqtt-v10)] provides specific -guidance regarding the use of MQTT topics for OpenC2 message transfer. Other -users of the MQTT Broker CACAO agent and `__mqtt-topics__` variable for publish -/ subscribe messaging should apply their own corresponding guidance. +The `mqtt-broker` agent is general purpose. MQTT offers great flexibility +regarding topic naming. The format of the topic names in the `topic-list` value +should be appropriate to the application. The [[OpenC2 MQTT Transfer +Specification](#openc2-mqtt-v10)] provides specific guidance regarding the use +of MQTT topics for OpenC2 message transfer. When an `mqtt-broker` agent is +employed for sending and receiving OpenC2 messages the topics specified as +`__mqtt-topics__:value` should conform to the topic structure guidance in +Section 2.2 of the +[[OpenC2 MQTT Transfer Specification](#openc2-mqtt-v10)]. +Other users of the MQTT Broker CACAO agent and `__mqtt-topics__` variable for +publish / subscribe messaging should apply their own corresponding guidance. **Example 5.1 (`__mqtt-topics__`)** From f20950e921d3f442f92f5babf2fe50eabe112b73 Mon Sep 17 00:00:00 2001 From: David Lemire Date: Wed, 10 Jul 2024 15:06:37 -0400 Subject: [PATCH 5/7] formatting fix --- openc2-cacao-ext-v1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openc2-cacao-ext-v1.0.md b/openc2-cacao-ext-v1.0.md index 1adfea5..47167a0 100644 --- a/openc2-cacao-ext-v1.0.md +++ b/openc2-cacao-ext-v1.0.md @@ -653,7 +653,7 @@ of MQTT topics for OpenC2 message transfer. When an `mqtt-broker` agent is employed for sending and receiving OpenC2 messages the topics specified as `__mqtt-topics__:value` should conform to the topic structure guidance in Section 2.2 of the -[[OpenC2 MQTT Transfer Specification](#openc2-mqtt-v10)]. +[[OpenC2 MQTT Transfer Specification](#openc2-mqtt-v10)]. Other users of the MQTT Broker CACAO agent and `__mqtt-topics__` variable for publish / subscribe messaging should apply their own corresponding guidance. From 4c8e1f2d83a3016bdb7f29e50bebf0c0d6516548 Mon Sep 17 00:00:00 2001 From: David Lemire Date: Wed, 10 Jul 2024 15:08:10 -0400 Subject: [PATCH 6/7] terminology fix --- openc2-cacao-ext-v1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openc2-cacao-ext-v1.0.md b/openc2-cacao-ext-v1.0.md index 47167a0..292991e 100644 --- a/openc2-cacao-ext-v1.0.md +++ b/openc2-cacao-ext-v1.0.md @@ -634,7 +634,7 @@ variables are playbook variables whose values can be set internally via an and accessed by the appropriate agent. A standardized CACAO variable is also defined for returning OpenC2 responses to -the calling `openc2` playbook action step for subsequent processing. +the calling `openc2` action step for subsequent processing. ## 5.1 `__mqtt-topics__` Variable From 6f130bf840cd668fbb9af347d5ddd3efc78955f1 Mon Sep 17 00:00:00 2001 From: David Lemire Date: Wed, 10 Jul 2024 15:10:21 -0400 Subject: [PATCH 7/7] update TOC --- openc2-cacao-ext-v1.0.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/openc2-cacao-ext-v1.0.md b/openc2-cacao-ext-v1.0.md index 292991e..cbdeff0 100644 --- a/openc2-cacao-ext-v1.0.md +++ b/openc2-cacao-ext-v1.0.md @@ -102,17 +102,16 @@ For complete copyright information please see the full Notices section in an App - [4.1.1 MQTT Broker Agent](#411-mqtt-broker-agent) - [4.1.2 OpenC2 HTTP-API Agent](#412-openc2-http-api-agent) - [4.2 OpenC2 CACAO Targets](#42-openc2-cacao-targets) -- [5 Standard Playbook Variables](#5-standard-playbook-variables) +- [5 Standardized Playbook Variables](#5-standardized-playbook-variables) - [5.1 `__mqtt-topics__` Variable](#51-__mqtt-topics__-variable) - [5.2 `__http-endpoints__` Variable](#52-__http-endpoints__-variable) + - [5.3 `__openc2-responses__` Variable](#53-__openc2-responses__-variable) - [6 Conformance](#6-conformance) - [Appendix A. References](#appendix-a-references) - [A.1 Normative References](#a1-normative-references) - [A.2 Informative References](#a2-informative-references) - [Appendix B. Safety, Security and Privacy Considerations](#appendix-b-safety-security-and-privacy-considerations) - [Appendix C. Acknowledgments](#appendix-c-acknowledgments) - - [C.1 Special Thanks](#c1-special-thanks) - - [C.2 Participants](#c2-participants) - [Appendix D. Revision History](#appendix-d-revision-history) - [Appendix E. Use Cases and Examples](#appendix-e-use-cases-and-examples) - [E.1 Use Cases](#e1-use-cases)