PRD-02 Comments (in bulk)

[Brian Berliner <Brian_Berliner@symantec.com>]

As a member of the Technical Committee, the OASIS process requires that I send my own comments to the TC directly, as opposed to using the openc2-comments mailing list. As such, I have combined all my comments into this single message (and, hopefully, sent them to the proper list!).

 

These comments are related to Language Spec PRD-02 (dated April 04, 2019; PDF version).

 

1. Section 1.4, Page 13: Should have a link to the âActive Cyber Defenseâ paper, which is https://www.semanticscholar.org/paper/Active-Cyber-Defense-%3A-A-Vision-for-Real-Time-Cyber-Herring-Willett/7c128468ae42584f282578b86439dbe9e8c904a8

 

2. Section 1.4, Page 13: Should have a link to the âIntegrated Adaptive Cyberspace Defenseâ paper, which is https://www.semanticscholar.org/paper/Integrated-Adaptive-Cyberspace-Defense-%3A-Secure-by-Willett/a22881b8a046e7eab11acf647d530c2a3b03b762

 

3. Section 1.5.2, Page 14: The first example shown for OpenC2 in the spec is not compliant with the spec as it refers to a âuser_accountâ target, which is not part of the language. The very first example that readers see should accurately reflect a compliant command, like a âdeny/file/hashes/sha256â command. I can supply an example if necessary, but using âuser_accountâ definitely feels wrong to me at this spot in the document.

 

4. Section 1.6, Page 15: The first bullet that says âThe OpenC2 Language Specification providesââ should mention the face that this is the document with something like âThe OpenC2 Language Specification (this document) providesââ

 

5. Section 1.6, Page 17: The âMessageâ definition still mentions notifications, even though there is no way to do any notification style messages with this version of the spec, which is confusing.

 

6. Section 3.1.4, Page 26: The example that says âExample SetValue operationâ confuses me. What does âoperationâ mean in this specification? I think you are trying to show what the serialization would be for the SetValue example Record, but the word âoperationâ does not match anything else in the spec. Frankly, this whole section on Derived Enumerations is extremely confusing, and the example using Pixels and SetValue do not seem to have any actual meaning in cybersecurity. There must be an easier way to say what you are tyring to say here.

 

7. Section 3.1.5, Page 26: Is a bit of a mess. Says âAll extension names must being with a namespace identifier followed by a colonâ. That is not accurate, or at least not clear on what you are trying to say. You are actually describing how extension âtargetsâ are named, but you never reference the word âtargetâ here, so it becomes very confusing. We basically want to say that the NSID of an official profile with not start with âx-â while a non-standard extension profile must start with âx-â. Then, point out clearly that the extension profile NSID is used as a field in the of the âargsâ or âactuatorâ records of an OpenC2 Command or in the âresultsâ record of an OpenC2 Response. And, further, that when use in the âtargetâ record of an OpenC2 Command, that the fully-qualified target name MUST be constructed using the NSID followed by a â:â and the name of the profile target, then show the example for the slpf (âslpf:rule_numberâ) and add another one for an âx-acmeâ extension target (like âx-acme:containerâ, say). The spec shows a flattening of some other places, like a reference to âslpf:directionâ in the âargsâ record (which should actually be â{ âargsâ: { âslpfâ: { âdirectionâ: âingressâ } } }â. Yet in the example for the âactuatorâ extension it is correct (not flattened). But, the example for the âresponseâ record is wrong as well, since it has been flattened, and is not even inside the proper âresultsâ record. Whatâs going on here! So, letâs make it say what I said above and keep it simple and consistent. The only place we flatten and use the â:â separator is for Target, and nowhere else.

 

8. Section 3.1.6.2, Page 30: For Integer Serialization, the wording of the description is a bit confusing. It says that for JSON (or default serialization format), âintegers are converted to stringsâ, but that is not true as integers are represented as the ânumberâ data type in the JSON standards document. I think the comment is trying to say that JSON is not a binary format (even though clearly it is binary; itâs just represented in a standard character set). So, please fix up the wording here to not imply that integers should be serialized as strings! It does say this later, so itâs just this first paragraph that is unnecessarily wordy and inaccurate.

 

9. Section 3.1.2, Page 24: The âemailâ constrain references RFC5322, but does not also allow for internationalized email addresses which are defined in RFC6531. Is that a conscious decision or an oversight?

 

10. Section 3.1.2, Page 24: The âhostnameâ constrain references RFC1034, but does not also allow for internationalized hostnames which are defined in RFC5890. Is that a conscious decision or an oversight?

 

11. Section 3.2, Page 31: The âmsg_typeâ description mentions that a Message-type can include ânotificationâ, even though no other mention of what a notification message would be in the spec, so itâs actually impossible to have a compliant msg_type that is a ânotificationâ, so I donât think we should mention it.

 

12. Section 3.2, Page 32: Honestly, the initial discussion in Section 3.2 I find very confusing, since we have specified that JSON is the default encoding that everyone must support, why do we continue to describe things with these odd words. In any case, the entry for the âtoâ field is particularly confusing. The language spec requires that all Commands must include a âtoâ field and that field MUST be an Array Of Strings. However, the only transfer spec that we have cannot possibly receive an Array Of Strings as the destination address (and simply uses the HTTP standard Host field. So, does that mean that our HTTPS spec is not compliant with the Language Spec? Can we just largely get rid of this 3.2 section altogether?

 

13. Section 3.2, Page 32: The bullets use the words âproducerâ and âconsumerâ and they are not capitalized. I expected that they should be in that context.

 

14. Section 3.2, Page 32: The wording for the ârequest_idâ field says that the language spec requires this field only if the Producer does not âexpectâ a response. The word âexpectâ here seems odd to me. Responses will always be sent based on the setting of the âresponse_requestedâ field, so are we saying that the ârequest_idâ can only be not sent when the âresponse_requestedâ field specifically says ânoneâ, otherwise it must always be sent? My person feeling is that, since request_id cannot be queried in any way using this spec, forcing all Producers to send it on all commands is wasteful, and we have not written our Producers to require the field. Instead, a Symantec Consumer will create a new request_id if it is not supplied by the Producer and return the request_id (either the one supplied or the one we create) for any and all responses. Much simpler and lighter-weight for the Consumers without forcing them to use a request_id in 1.0 when the spec does not allow you to query by request_id today (only by command_id, which is different).

 

15. Section 3.3.2, Page 37: The OpenC2 Response is still including the âintsâ and âstringsâ arrays, though I thought we had agreed to remove those once we added the more generic âresultsâ map to the response. I think we should remove these (and fix the example to use a string array with a proper key in the âresultsâ record instead).

 

16. Section 3.3.2, Page 38: Formatting: âUsage Requirementsâ should be in bold to be consistent with the rest of the spec.

 

17. Section 3.4.1.1, Page 39: Is it your intention that the âArtifactâ target could be simply â{}â (empty)? That is what is says here, as all the fields are optional. Should you require the âpayloadâ field, at least (or âpayloadâ AND âmime_typeâ)?

 

18. Section 3.4.1.2, Page 39: For âDeviceâ target, it implies that a hostname must be specified and a device_id is optional. For Symantecâs systems, the opposite is actually true. We must have a device_id. These fields should probably all be marked optional, and a âUsage requirementâ statement added that you must include at least one of âhostnameâ or âdevice_idâ (or both).

 

19. Section 3.4.1.5, Page 40: Includes both a âUsage Requirementsâ and a âUsage Notesâ section, but I think they can be combined into a single âUsage Requirementsâ section.

 

20. Section 3.4.1.6, Page 40: The âFileâ target is currently defined as supporting an empty record as well, since all fields are marked optional. At Symantec, we typically require the âhashesâ field to be provided and donât usually refer to the other fields at all. I think a reasonable Usage Requirementâ section can be added to the File target which says that you must supply a âhashesâ value or one/both of the others (the name/path fields).

 

21. Section 3.4.1.11, Page 42: The âMAC Addressâ target totally confuses me, since the Type is described as âBinary (eui)â. The Binary type must be serialized as Base64url, but I donât think thatâs right for a MAC Address. Proper JSON serialization for a MAC Address would be something like: â8c:85:90:72:31:afâ, which is closer to âBinary/xâ in our spec, but not exactly. This format is usually described as a âcolon-hexadecimalâ format, so we should use that (it is the âcanonicalâ format for MAC addresses).

 

22. Section 3.4.1.12, Page 42: The âProcessâ target is another one that is valid if empty (â{}â) since everything is optional. For process, however, I would think that the Usage Requirement would say that you must specify the âpidâ or one of ânameâ/âexecutableâ.

 

23. Section 3.4.2.5, Page 44: The âHashesâ field could be sent as an empty record since all fields are optional, so we should add a Usage Requirement section that at least one of the supported fields must be supplied.

 

24. Section 4.1, Page 47: In other places we use a capitalized âTarget Specifierâ, but all of the bullets in this section use a lowercase âsâ as in âTarget specifierâ. Is that intentional or an oversight?

 

25. Section 5.3, Page 50: A conformant Producer MUST also implement JSON serialization of generated Responses.

 

26. Section 5.3, Page 50: A conformant Consumer MUST also implement JSON serialization of received Commands.

 

27. Section A.1, Page 51-52: Totally confuses me. Since we are requiring JSON serialization, why donât we just show JSON examples consistently? Also, JSON strings used in that example are enclosed in single-quotes, which is not JSON-standard. You need to use double-quetes in the âcontentâ examplesâ

 

28. Section A.2.2, Page 53: I donât really like that you are using a âbatteryâ example in the results, as the term âbatteryâ is not part of any OASIS OpenC2 standardized language. I would be more excited by an actual âslpfâ example response here AND a response showing the whole âbatteryâ object, but enclosed inside the âx-acmeâ extension. I can provide that example for you, if you like. We REALLY need to show folks how the extension results are returned, so this is super important.