Full format communication

[j---]

In subsection Guidance on Communicating Results (Section 4) determine what we should do about full format result formatting. It may be too early to do this well, so it may not be appropriate for v2.

This is closely related to #24 and more specifically #25 #26 and #29.

[sei-vsarvepalli]

Jono,

I think this is not difficult to do (unless I understood the request wrong). I developed one such representation for the SSVC calculator tool I wrote up, which basically can represent a full decision tree

Schema - https://github.com/CERTCC/SSVC/blob/main/ssvc-calc/SSVC_JSON_2.0_min.schema.json

Sample - https://github.com/CERTCC/SSVC/blob/main/ssvc-calc/sample-ssvc.json

This was written mainly to make it easy for the tool to ingest a new decision tree. The tool also exports part of the tree which was followed by an "analyst" which can also be represented in a JSON schema. The JSON schema can also be built from the CSV input, but it will be missing some metadata on the decisions themselves.

[j---]

I think you're right it should be pretty easy. The "guidance on communicating results" section (https://github.com/CERTCC/SSVC/blob/main/doc/version_1/047_treesForVulMgmt_4.md) is now mostly together, so we can make sure the schema and that section match, and then describe the schema a bit there.
Loose requirements to check:

• Decision points are defined
• Values for decision points are fixed
• "Whole tree" schema is defined with some reasonable definition of when a tree is complete (all leaf nodes have a label, etc.)
• Ideally, "whole tree" schemas can inherit the definitions of decision points from one document, to make it easier to keep those definitions consistent
• "Choice schema" for a specific set of choices of values for decision points and the resulting decision is defined and allows for the uncertainty in
• "Choice schema" allows for identifying which "whole tree schema" was used
• Timestamps are required for the "choice" schema
• "Choice" schema can handle partial information (see "Guidance..." section description)
• Formatting (upper / lower case, etc.) match https://github.com/CERTCC/SSVC/blob/main/doc/style-guide-how-to (as much as makes sense, there is no italics in JSON)
• Style guide documents that JSON literals are written in the .md files as code literals

[sei-vsarvepalli]

I think it looks fine.

Here is how I propose for next steps for which i will submit part of the PR.

1. Create a "schema" folder under SSVC/data - where we have the schema definitions by themselves which can include the full decision tree schema "whole tree" call it "SSVC provision schema" (JSON schema file called SSVC_Provision_v2.schema.json) and "SSVC computed schema" (JSON schema file called SSVC_Computed_v2.schema.json) - the computed schema can optionally include the full decision tree "Provisioned Schema"
2. Have each example tree you have in "SSVC/data" folder also be represented in JSON using the above recommended JSON schema in the same folder (I can do this)
3. Create a "computed" folder under "SSVC/data" where @j--- (or other team of analysts) can have a few sample CVE's computed SSVC score using multiple "stakeholder" trees.

Vijay

3. Extend the schema to add the representation of the " SSVCv2/Ps:Nm/T:T/U:E/1605040000/

[j---]

Sounds good, thanks.

[ahouseholder]

Summarizing a conversation between @sei-vsarvepalli and myself earlier today:

1. consider choices as a dict of lists rather than list of single-element dicts; e.g., '''choices = { "exploitation": ["none","poc","active], ...etc '''
2. consider changing the name of the object "choices" in the decision spec to "options" to avoid conflict with the name "choices" in the answers spec
3. allow for out-of-order answers to questions within trees: While it's ok for the order of questions to be consistent in the JSON format that doesn't mean that answers will always answer q1 then q2 then q3 etc.
4. allow for underspecified answers: related to above, it should be possible to say things like "exploitation" = "none" or "poc" but not "active". If each value is a list of values, then this just means the cardinality of the list can be >1 up to the max of all the possible options for that item. Furthermore this just means that a fully-specified answer is a list with cardinality = 1.
5. in the vector notation, address underspecification as well: E.g., E:[N,P] for the previous example.
6. in the vector notation, consider a wildcard character in place of a full list when a decision is entirely unspecified e.g., X:* instead of X:[A,B,C,D] if X has four options, but X:[A,B] if we know X is neither C nor D.
7. add "key" to the full tree specification to decisions and options to their corresponding short-form key in vector notation. The goal is to allow full parsing of the vector notation to a verbose interpretation given the tree description.
8. We should allow for vector keys and possibly value keys to be more than 1 character. We can declare by convention a preference for single character keys, but being able to accomodate longer ones without having to rev the spec will likely be convenient in the future. We are likely to run out of letters in the decision options first because we're already using a sizable fraction of 26. Within any given decision it's really only necessary that the option values are unique to that decision (i.e., "E:A" is not the same "A" as "D:A", but we can't have two "D:A"s). And it seems like if we have a single decision with >26 options maybe we're doing something wrong.
9. vector notation should specify both version and role so it's clear which tree the vector is addressing. Suggest sticking with "/" as field separator, and "k:v" as key:value syntax for these. E.g., /V:2/R:C/
10. in the ensuing discussion of the above, we realized we might have a need for tree IDs in the future, to avoid having to rev SSVC just because we change an option in the Coordinator tree for example. That's likely a future request, but I'm noting it here first just to get it written down.
11. While it's not necessary that all the above be addressed to close this issue, if any are left unresolved when this issue is closed, please ensure that they are propagated to new issues so they can be revisited in future revisions. And resolved needn't mean implemented. It could also mean "we thought about it and decided not to". My concern here is just to avoid a situation where we defer an item for the future but it gets closed out in this issue and forgotten.

[j---]

Since #65 has an open PR, I'm moving any new items to be handled under a new issue.