oasis-tcs / openc2-oc2arch

OASIS OpenC2 TC: Developing a standard architecture to guide all developers of Profiles. https://github.com/oasis-tcs/oc2arch

An OASIS Work Product Repository

Members of the OASIS Open Command and Control (OpenC2) Technical Committee use this GitHub repository as part of the TC's chartered work. Contributors must be Members of the TC. Work is governed by the OASIS policies and is not done under typical open source licensing. For more details, see the Contributions and Licensing sections below.

📘 Open Command and Control (OpenC2) Architecture Specification 📘

This specification provides overall architectural guidance to the OpenC2 implementation community for the use of the OpenC2 language, actuator profiles, and transfer specifications.

This repository also contains the OpenC2 namespace registry, which maintains the record of unique names and identifiers of OpenC2 Actuator Profiles. Appendix F of the Architecture Specification explains the use of namespaces in OpenC2.

🔀 Repository Organization 🔀

OpenC2 work product repositories are organized a bit differently than typical open source software project repositories:

• The Published (default) branch represents the current, stable, approved version of the work product. If the product hasn't progressed past an OASIS Committee Specification Draft (CSD), this branch is essentially empty
• The Working branch is where all work-in-progress content is captured, and is the place to go for the current working version of this work product

More information about the TC's repository organizing conventions and branching strategy can be found in our Documentation Norms.

🗨️ Description 🗨️

All OpenC2 Profiles work within an implied architecture as well as a in a common language. The purpose of this repository is to develop a specification of the standard architecture to guide all developers of Actuator Profiles (APs) and Transfer Specifications.

✍️ Contributions ✍️

As stated in this repository's CONTRIBUTING file, contributors to this repository must be Members of the OASIS OpenC2 TC for any substantive contributions or change requests. Anyone wishing to contribute to this GitHub project and participate in the TC's technical activity is invited to join as an OASIS TC Member. Public feedback is also accepted, subject to the terms of the OASIS Feedback License.

📜 Licensing 📜

Please see the LICENSE file for description of the license terms and OASIS policies applicable to the TC's work in this GitHub project. Content in this repository is intended to be part of the OpenC2 TC's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository LICENSE.

📩 Contact 📩

Please send questions or comments about OASIS TC GitHub repositories to the OASIS TC Administrator. For questions about content in this repository, please contact the TC Chair or Co-Chairs as listed on the the OpenC2 TC's home page.

openc2-oc2arch's Issues

2: Overview Image

OpenC2 abstract schematic image found in SBOM actuator file rightfully belongs in the Architecture doc at the head of Section 2.

Readme and published v master

Should update the readme to reflect the published branch:

"The Master branch contains TC-approved Committee Specification (CS) or OASIS Standard versions of the work product. Until the first CS is approved, the Master branch will not contain a complete version of the work product."

1.5 Update

First paragraph of section 1.5: Goals needs to change in reflection of differences between language spec and architecture document.

Add "introspection" discussion?

At the 2/23 working meeting, @davaya made the following observation in chat:

For AP-SBOM Issue #34, having a "tell me what you've got" command analogous to "query features" is a design pattern that may apply to more than just SBOMs. A short paragraph on introspection might be a good addition to the Architecture spec.

Should we add a discussion of introspection as a design pattern into the Architecture Spec? Where?

EDIT (3/30): One reasonable location would be a new section 2.1.3:

• 2.1.1 OpenC2 Command
• 2.1.2 OpenC2 Response
• 2.1.3 OpenC2 Interaction Patterns

The new section 2.1.3 could be the home for discussion of interactions patterns as influenced both by the nature of the interaction (use of introspection) and the transfer environment (point-to-point vs. pub/sub), as well as possibly other factors.

emphasize commands only defined in LS (ARCH-102)

Regarding 2.3.2, Alex Everett wrote: Consider emphasizing this statement, I know I tripped on it in some early APs:

The available set of actions for creating OpenC2 commands is limited to those defined in the Language Specification in order to encourage commonality and interoperability of implementations.

Clarification for profile unique names

I assume that it has been discussed multiple times already, but why we don't follow the OASIS guidelines for creating URIs? https://docs.oasis-open.org/specGuidelines/namingGuidelines/resourceNaming.html

Examples?

Our other specifications typically include examples to illustrate their use "in action". What examples, if any, are appropriate for the Arch Spec?

Missing Material? Leverage Other Material?

What is missing from the current Arch Spec content or organization that should be included?

• Have we addressed all of the relevant Section 1 content of our original 3 specifications? (LS v.10 linked for convenience)
• Should we incorporate material from the VasileiosM / JoeB overview paper?
• Should we leverage any of the content from the informal OpenC2 Companion captured in the TC Ops repo?
• Are there other useful sources that could improve the Arch Spec?

Add Architecture doc to section 1.0

Language in section 1.0 is a direct copy/paste lift from the language spec. It should be updated to reflect position in architecture doc.

Message Serialization

At present the only mention of serialization in the Architecture Spec is in the abstract. "Transfer Syntax" appear in figure 2-3.

While we have considered serialization primarily a concern of the language and transfer specifications, it seems like the Arch Spec should have at least some discussion of our serialization-agnostic philosophy.

Enhance authentication discussion (ARCH-103)

Alex Everett wrote: "The section on authentication should be more detailed or more prescriptive; we should probably have a conformance section for it. My read of it is that authentication is an exercise left to the reader without a lot of specific guidance even though it is a MUST. Certainly, the threat model would be greatly affected by authentication. I know in the past something along the lines of using JWT was brought up."

Presume this is a reference to section B.3.4 (Alex didn't provide a reference).

Content for Appendix B. Safety, Security and Privacy Considerations

OASIS is placing greater emphasis on the content of Appendix B, and pointing to IETF guidance:

We encourage editors and TC members concerned with this subject to read Guidelines for Writing RFC Text on Security Considerations, IETF [RFC3552], for more information.

What is the appropriate Appendix B content for the Arch Spec?

• Could draw on never-published CN on IA considerations (long untouched)
  • https://docs.google.com/document/d/1lmN9EQGUaj-HdpJFFtdonpHgcukImB3bnf9s0AV1u0U/edit#heading=h.gjdgxs
• Could have concise IA section in Architecture and revisit completing and publishing the IA CN
• Other approaches?

Editorials from public review (ARCH-101)

Per Alex Everett comments:

Acronym table in 1.3.2:

• SHA: "Security Hash Algorithm" should be "Secure Hash Algorithms"
• UDP: "User Datagram Control Protocol" should be "User Datagram Protocol"

Add Document Conventions

After current 1.4 and before current 1.5, boiler-plate section titled "Document Conventions" should be inserted to reflect OASIS best practices.

Query Features Profiles behavior

In issue 20 against the MQTT Transfer Spec @sparrell requested "an example of a profile query to all slpf would help in understanding."

I think this raises some interesting questions, which we discussed at the 2 March IC-SC and agreed should be presented here:

• if query features profiles is directed at Consumer devices with a specific AP (either by pub/sub topic selection or using the actuator field in the request), what is the desired response (e.g., "the specified profile" or "all profiles supported by that consumer")?
• And what is the response if the Consumer does not implement the specified AP?

Example 1 (pub/sub): producer sends a query features profiles request to oc2/cmd/ap/slpf, with no actuator field in the request. I think the correct response is that any consumer that implements the SLPF AP should respond with all APs that consumer implements. But it's worth considering that at least for a moment. And in discussion at the 2 March IC-SC, Duncan and I agreed that not using the actuator field in the request message is a poor approach because it's transfer-solution specific.

Example 2 (pub/sub): producer sends a query features profiles request to oc2/cmd/all, with slpf specified in the actuator field in the request. This is a better message form, as the specification of an AP is now general, rather than transfer-specific. If using oc2/cmd/all then all Consumers will receive the request. Is the correct response that any consumer that implements the SLPF AP should respond with all APs that consumer implements, or just respond with slpf so that the producer can identify consumers that implement slpf? Does the answer change if the request were sent to the AP-specific channel (i.e., oc2/cmd/ap/slpf) as in Example 1?

Example 3 (point-to-point): producer sends a query features profiles request over, e.g., HTTP(S) to a consumer with slpf specified in the actuator field in the request. Is the correct response for that consumer if it implements the SLPF AP to respond with all APs that consumer implements, or just respond with slpf so that the producer can confirm the consumer implements SLPF? And if the consumer in this point-to-point case doesn't implement SLPF, is the response some kind of error, or just the list of profiles it does support?

Need Document Convention Section

After current 1.4 and before current 1.5, boiler-plate section titled "Document Conventions" should be inserted to reflect OASIS best practices.

Update to new OASIS Template

Rename to OpenC2-oc2arch?

The other repo's all start with OpenC2 to make for easy filtering/sorting. This is the one exception. Should we rename?

Clarity regarding "out of band" network (ARCH-105)

Regarding section B.4.2, Alex Everett wrote:

In B.4.2 it isnt exactly clear what constitutes out of band. Often this means a dedicated physical network solely for management requiring physical access and no remote access. If this is the idea, then maybe it should be stated.

However, that is probably not the most common implementation due to high cost and issues arising when something goes wrong such as having to drive in or support some very remote device. More often, a network is managed via a firewall with a default deny all. However, that makes the network more like any other network an organization manages and increases risk, esp. as network A has a path to network B which has a path to ...

Add Notification Message?

Currently the Arch Spec has no mention of the notification message type. Notifications don't appear in the published v1.0 LS, but are called out in sections 3.2 and 3.3.3 of the v1.1 working version. What, if anything, should the LS say about this message type?

Add rationale for action-target structure

Section 2 lists "Command" and "Response", then says "The Action and Target components are required."

A more comprehensive description of the design approach would be useful. Microsoft Powershell (https://docs.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands) uses a verb-noun pair for the names of cmdlets, and curates the list of verbs, providing recommendations to developers in order to "ensure consistency between the cmdlets that you create, the cmdlets that are provided by PowerShell, and the cmdlets that are designed by others."

OpenC2 adopted the same design philosophy for the same reasons - the list of actions is built into the language specification, while targets (nouns) are primarily defined by developers. The architecture document should both:

1. articulate that design philosophy, and
2. when proposing new actions to the LS, seriously consider Powershell conventions in order to maximize commonality when appropriate.

As an example, we have already chosen allow and deny because those verbs are common in network devices. Powershell uses block and unblock security verbs. We would not change existing OC2 actions solely for alignment. But OC2 has start, stop, and restart, which do align with Powershell lifecycle verbs, and if we consider additional actions (suspend, resume) we should align when it makes sense, and avoid non-recommended alternatives (e.g., pause).

Discuss: Producer / Consumer / Device / Actuator diagrams in 2.2

@dlemire submitted these diagrams long ago (PR #4, August 2020) and they were merged, but I don't believe they've ever been discussed. The view the present is influenced by the design of the OpenC2 Integration Framework (OIF). I think a meaningful discussion of these diagrams is appropriate, including consideration of whether the discussion of them is adequate and additional options are needed.

There's a related, lesser question regarding the presentation of the material: should the examples be separated into individual figures with a more extended discussion of each, perhaps as subsections of 2.3.

Finally, do we need a fourth configuration for when the Consumer is also a Producer (i.e., the interface to the managed devices behind the consumer is explicitly OpenC2)?

Integrate Namespace Registry Description

In PR #25 the registry was split into a registry file and a description file. The latter is contained in:
https://github.com/oasis-tcs/openc2-oc2arch/blob/working/namespace-registry-text.md

Need to determine where in the architecture spec this description material should be located and integrate the text.

Add Packet Filter to registry

https://docs.oasis-open.org/openc2/ap-pf/v1.0/csd01/ap-pf-v1.0-csd01.html

Add Overview

Between proposed new Document Conventions section (see #9) and existing 1.5, add Overview section complete with image schematic as it appears in HTTPS spec.

Importing Issues from other work products

I believe the following issues from other work products are relevant to the Architecture Specification:

• LS Issues:
  • 342: References Schemas, and NSIDs
  • 344: Multiple Actuators
  • 350: Query for Pairs
  • 353: Multiple Responses and Messages
  • 364: Undefined Consumer Behavior with Multiple APs
  • 365: Query Features Level of Inception
• MQTT Issues:
  • 20: Add all-slpf-devices query-profile example to CDS04, relates to Arch Spec issue #12
  • 21: Add slpf-deny-ip specific device example to CDS04, second items in the issue

Consider Producer breach in active attacks (ARCH-104)

Regarding B.2.3, Alex Everett wrote:

As far as active attacks, compromise or breach of a producer system(esp.) should be noted. Leaving a producer exposed to the Internet at large (or maybe even the whole company network) would significantly increase one risk of an attacker being able to issue (or stop issuance of) commands given the pace of vulnerabilities and misconfigurations.

Definition of Actuator

The Architecture Spec, being derived from the Language Spec, inherits the inconsistent meanings of "Actuator" that have existed since the beginning of OpenC2. The Glossary definition:

Actuator: The function performed by the Consumer that executes the Command (e.g., "Packet Filtering")

directly conflicts with the Command definition:

Actuator (optional): The Actuator executes the Command.

Since the English meaning of actuator is "a device that causes a machine or other device to operate", and the Command has always named the Actuator Profile that describes the operation to be performed, the choice of "actuator" as the Command property name was incorrect. Given the ongoing confusion caused by that choice, the property name should be fixed so that it does not conflict with the intended meaning: Command should have properties {action, target, args, profile(s)}.

Because modifying property names is a breaking change it will have to wait for a new OpenC2 major version (v2.0). In the meantime, the planned modification should be documented in v1.1, and all descriptions related to the "actuator" field should be made consistent with the field named "profile".

Decisions to be made:

• Should profile be singular or plural? (Can a single command perform operations defined in more than one AP?)
• Can actuator/profile specifiers be moved to command arguments, simplifying the command and eliminating questions like "does this belong in args or specifiers?".

Related to ER Issue #31 (oasis-tcs/openc2-ap-er#31)