oasis-tcs / cacao Goto Github PK

After carefully reading the CACAO v2.0 spec and looking at the examples there and in playbooks from the GH repo, I have some questions regarding the realities of OpenC2 commands being sent from CACAO playbooks. This is loosely related to issue #6.

First, we describe OpenC2 as the Acting capability at the end of a cyber defense OODA loop (e.g., IACD's S-SM-D-A loop) so there's an expectation that the details of the action to be taken are determined dynamically. If the OpenC2 command message is b64encoded w/in the playbook that doesn't seem to offer much opportunity for real-time adjustment. Even if there was a Block-Traffic-OC2 playbook that incorporated knowledge of all of the “firewall” elements in the infrastructure:

1. The address / netblock to be denied is the Target in the OpenC2 command and would be different every execution, necessitating that the b64encoded value be supplied from the decision process and updated within the playbook prior to execution (or something similar).
2. There's an implicit need to update the playbook as the “firewall” structure changes, something that might be a manageable routine playbook maintenance action in an in-prem data center but would be very challenging in a dynamic cloud environment.

Second, there's a question of transferring (addressing) the OpenC2 command to the appropriate Consumer(s), either via the endpoint an HTTP POST would be sent to or the selection of a pub/sub topic to publish the comment onto. There's really nothing in the spec to indicate how the destination of a command would either be determined or passed to the transfer mechanism.
I’d be happy to learn more about how this is envisioned to operate in practice.

After careful review of the current CACAO specification I have a few detailed questions / comments:

1. Shouldn't examples 7.3, 7.5, 7.7, ... 7.21, be “(XXXXX Target)” rather than “Agent” again?
2. In 7.1.1, the statement is that the vocabulary “is not intended to be exhaustive nor binary.” -- what does “binary” mean in this context?
3. In 7.1.1, suggest adding language that “ragdoll” is associated with Caledera (as with “manx”), as there is a Ragdoll tool in other contexts with very different functionality (physics modeling for games)
4. How are values assigned to variables? The spec mostly talks about initial creation & use in conditionals; STIX patterning grammar isn't really helpful WRT assigning values.

Concerns:

• Branching steps (if, while, parallel) have multiple branches: on_true, on_false, on_completion, next_steps.
• All branches must end in an end_step.
• All end steps in all branches should be interpreted as “end of the workflow branch, continue to the next workflow command” (details of on_true in e.g. 4.8: “This branch MUST reference a unique end step when that branch has completed processing. This allows implementations to know when to return to the original if condition step that started that branch to look for any on_completion, on_success, or on_failure actions.”)
• Workflow branch end steps should hence be used to back-track to the branching step (if, while, parallel), to then trigger the on_completion (/success/failure) step.
• This requires that if a playbook has complex and nested conditional logic, all the conditional steps must be back-tracked by the implementation that executes the playbook. Hence, this introduces a great overhead for execution implementations.
• As related consideration, it may be the case that the entire playbook execution should terminate upon reaching a condition “nested deep” in the conditional logic, without having to backtrack the previous condition nodes.
• This is alike to using a return value inside nested or otherwise complex conditional logic in programming.
  Possible ways to address
• Introduce the concepts of playbook-end step and branch-end step.
• A “branch-end” step should provides necessary information for back-tracing.
• If a playbook reaches a playbook-end step, no more processing is needed. If a playbook reaches a branch-end step, the execution can be back-traced.
• Must add fall-back back-track from branching step back to branching step
• Nice to note: this would be retro-compatible.

Possible ways to address

• Introduce the concepts of playbook-end step and branch-end step.
• A “branch-end” step should provide necessary information for back-tracing.
• If a playbook reaches a playbook-end step, no more processing is needed. If a playbook reaches a branch-end step, the execution can be back-traced.
• Note: it is not needed that a branching step itself points to a previous branching step. Instead, the on_completion step can continue the current-level branch sequence, and eventually point to a branch_end step, which in turn points to the branching step (if any) which initiated the current-level branch.
• Nice to note: this would be retro-compatible.

The CACAO v2.0 spec includes a command type of openc2-http which provides a starting point for integrating the two standards. However, this support needs updating:

• As written, the description appears to be applying the July 2019 v1.0 HTTPS Transfer Spec, however that spec isn't actually referenced and has been superseded by the November 2021 v1.1 Spec. CACAO should apply the newer version and add it as a reference document.
• The OpenC2 community is emphasizing the use of pub/sub transfer mechanisms, with many advantages over HTTP for this application. We have a transfer specification for MQTT (also November 2021). CACAO should add an openc2-mqtt command type to use pub/sub message transfer and add our MQTT specification as a reference.

Working on an OpenC2 extension for CACAO. Is there any underlying rationale for why the openc2-http and http-api commands in CACAO uniquely use content_b64 rather than command_b64 as the name of their base64-encoded field? It seems like a distinction without a difference.

Originally we had implemented a limited version of the STIX design for a hash property. However, it became clear that without extra details, there is no good way of implementing that. Meaning do you include the headers, or just the content. Is it the whole resource or just part of it. So we dropped this from the spec for now but need to add it back later when we do digital signatures.

The idea is to have playbooks that can contact/notify (or alert) one or more entities about a particular situation (proactive/ongoing/reactive) and share relevant information in different forms like structured threat information (STIX feeds), threat reports, information about an early-stage ongoing adversarial operation, notes, and also for disseminating actionable/executable playbooks for (example) detection and remediation.

We need a new playbook type as the proposed functionality cannot be reflected within one of the available playbook tags. Maybe call them notification playbooks.

The information is included by using the external_references property within the workflow steps. The URL of an external reference may direct the consumer (target of the workflow step) to secure infrastructure for accessing all the relevant information or the playbooks. The external_id field annotates the note, STIX bundle, CACAO playbooks to be accessed related to the notification issued.

Concern

Observing that:

• playbook_variables (3.1) define variables in playbook scope. step_variables (4.1) define variables in step scope. These are the only two explicit variables scope in a playbook: global, or step-specific.
• All playbook steps can define step_variables specific to that step, and which can be accessed by objects “used or referenced by that object” (10.18.1).
• in_args are used in playbook action steps, or action steps. They are a list of string, i.e., the keys of the variables to resolve, and refer to variables used within that step or playbook.
• out_args are also used in playbook action steps, or action steps. They are also a list of strings, i.e., the keys of the variables that are expectedly modified by the execution of the step.

Note that:

• A workflow execution tool will always resolve/substitute variables in a step upon parsing the field that contains variables, hence, in_args potentially does not serve a purpose.
  • The resolution/substitution of a variable can still be expected to first check the local step scope (step_variables), then the global playbook scope (playbook_variables)
  • But as discussed, its use is intended to allow an efficient "fetch" of the relevant variables for the context, in the use-case of very large playbooks. This may be made clearer.
• In the general case, there is little meaning that out_args refer to step-local variables, as once the step is executed, the step-local variables will be out of scope of the playbook.
  • step-local out_args makes sense only in specific cases such as:
    • where an action step uses multiple commands, and subsequent commands use variables obtained from previous commands.
    • where a variable returned in a step should be "pushed out" of the workflow execution, for any use that cannot be addressed via a workflow step
  • In the general case, it makes sense if out_args refer to playbook scope variables, as updating them will contribute information to the workflow.
• IF and WHILE condition branches may only need step_variables if their condition is not dependent on the workflow. If the condition is dependent on the workflow, then the variables used in the condition need to be global, as the condition changes based on the execution of previous steps, or consequent branch steps. (Alternatively, an additional playbook branch variables scope may be added).

Possible ways to address

• Introduce explicit branch scope for variables for if, while, and parallel steps
• Document best-practices related to the envisioned use of in_args, and step-local out_args

Concerns

• According to the specification, a step handles exceptions in the following way with respect to on_completion, on_success, on_failure, and workflow_exception:
  • Use on_completion only
  • Use on_completion and define workflow_exception
  • Use on_success together with on_failure
  • Use on_success only (without specifying on_failure, nor workflow_exception),
  • Use on_success and define workflow_exception
• There is no explicit indication on how to behave if an “on_completion only” or “on_success only” step “fails” (without there being a “workflow_exception” defined).
• There is no explicit indication on how to behave if an on_completion + workflow_exception step “fails”, but this can happen:
  • Throw the workflow_exception
    • but this makes on_completion superfluous: just use on_success without on_failure
  • continue to the next step anyway
    • plausible, but not explicitly mentioned
  • Either of the two, or up to the implementation
    • flexible, but it may create issues in executing a playbook inconsistently with two different CACAO execution implementations
• The specification says “The determination of a step being successful, failing, or completing is implementation specific and is out of scope for this specification”, but this also favours inconsistent behaviour of how to execute a CACAP playbook in two different playbook execution implementations, or human interpretation.

Possible ways to address

• Make mandatory use of workflow_exception
• Add the concept of “workflow execution failure”, as a execution-level exception.
• add optional “on_exception” property, which overwrites the playbook_exception, for a finer workflow management.
• Make mandatory use of on_failure if on_success is used (and vice versa).
• Clarify uses of on_success and on_failure for OpenC2 use-cases
• Define best practices for uses of on_completion, on_success, on_failure

Hi - please point me in the right direction if this is not the appropriate place for this.

I am using the spec defined here to create an application that creates CACAO playbooks.

To do this, a couple of tools that are essential:

• TypeScript typings
• A validator that validates that any arbitrary json conforms to the spec.

Both of these toolings can easily be created from a JSON Schema spec.

So question is:

• Does a JSON Schema spec already exist?

  • If not, how are you currently generating that documentation.

• Does it make sense to the committee to use a JSON schema spec?

For what it's worth, I currently have a tool that scrapes the documentation page and converts the tables into CSVs, and I then convert those into TypeScript typings. I can probably modify my tooling to convert to JSON Schema instead, at least to give a starting point.

Let me know if it'll be helpful, and I can give you my scripts and/or a generated JSON Schema

The following is the definition of step_variables in the v2.0 CACAO Spec (emphasis added):

This property contains the variables that can be used within this workflow step or within commands, agents, and targets referenced by this workflow step. See section 10.18.2 for information about referencing variables.

The key for each entry in the dictionary MUST be a string that uniquely identifies the variable. The value for each key MUST be a CACAO variable data type (see section 10.18.3).

The first sentence refers to "variables, ... agents, and targets referenced" but then the second sentence limits the values to "a CACAO variable data type", which seems to exclude "agents, and targets". In addition, the Workflow Action Step example 4.3 calls out an agent independent of any step_variables context:

{
  "workflow": {
    ...,
    "action--ba23c1b3-fdd2-4264-bc5b-c056c6862ba2": {
      "type": "action",
      "commands": [
        {
          "type": "manual",
          "command": "Disconnect the machines from the network",
        }
      ],
      "agent": "individual--328a89ab-3b8f-40c4-a491-24a40bcd3cd4",
      "delay": 5000,
      "timeout": 60000,
      "on_success": "action--e5f0d00d-3047-4432-8964-cc0c56e5ab12",
      "on_failure": "action--e7e93280-ab26-45aa-baa8-423c44f917a6"
    },
    ...
  }
}

What is the correct / permitted content for step_variables? There are no examples of this field in the spec.

What is the proper approach to linking agents and targets to actions steps? Is a correction to the spec text needed?