Example Thread

[<duncan@sfractal.com>]

I’m sending this email as sFractal Consulting, not as LSC co-chair.

The agile methodology encourages delivering frequently and incrementally. In Agile software development, what is delivered is based on (1) business needs and (2) taking a ‘thread’ completely thru the architecture to meet a portion of that need, even if it’s a very skinny thread. Ie to deliver something of value, even it is only a small piece of what is needed overall.

Applying this philosophy to our developing the language specification, I suggested the ‘thread’ approach at the F2F.

My idea of a thread was the JSON for a particular command in a particular use case; and the corresponding JSON response.

This email is amplify on what I intended - by explaining using an actual sFractal use case. I would like to use https://github.com/sparrell/openc2-lsc-usecases/blob/master/sFractalConsulting/01.another_user.md. For the purpose of the LSC, the use case details are largely immaterial and I don’t think we should spend time at the LSC discussing - members can read the page on their own. What is important to discuss is the thread, ie the JSON command sent:

https://github.com/sparrell/openc2-lsc-usecases/blob/master/sFractalConsulting/01.another_user.md#openc2-json-command

and the response:

https://github.com/sparrell/openc2-lsc-usecases/blob/master/sFractalConsulting/01.another_user.md#response.

I think it would be valuable to discuss the following for the command, and for the response:

• Does it meet the spec?
• If not, why not?
• • If something missing from spec, what to add to spec?
  • If different from spec, does spec change or sFractal JSON change?

Walking thru the sFractal thread for illustrative purposes yields:

1. “action”:"allow” -
   
• I believe it meets WD02. No need to discuss further
2. “target”:{} -
   
• I believe the concept of the target being a JSON object meets the intent of 3.1.1.1 and 3.1.1.3
3. “ip_connection” -
   
• I think the underscore is correct per WD2 section 1.6.
  
• ip_connection is a valid target per table 2.2 and table 3.1.1.3. Note there is not a name space (ie openc2) defined for the target since we default to openc2.
  
4. "ipv4_src": "6.6.6.6","ipv4_dst": "1.1.1.1","layer4_protocol": "TCP", "dst_port": 443, "src_port": 44306
• These are not specified in WD02.
  
• Where do we put the specifiers for ip_connection?
  
• Is it ipv4_dst or dst_ipv4 or a more complicated nested object?
  
• How do we handle defaults (eg the use case above has a default ‘any’ for ipv4_src)?
• Should we add a property table similar to
• id=1, element name = “layer4_protocol”, description = get ietf def
  id=2, element name = “ipv4_dest” or  "Ipv6_dest", description = describe 
  id=3, element name = “dst_port”, description = get ietf def
  id=4, element name = “ipv4_src” or  "Ipv6_src", description = describe 
  id=5, element name = “src_port”, description = get ietf def
• Do we add subtending property table for layer4_protocol and the other elements?
5. “options”:
• Table 3.1.1.1 gives the name as ‘command-options’. In a previous meeting I thought we’d agreed to just call it options since you knew by position it wasn’t actuator options or target options. This is an example of deciding should spec change or should my JSON change. I have no issue with changing my JSON, albeit I do prefer ‘options’.
  
6. The {} after “options”
• is this a JSON object {} or a list []? The wording of 3.1.1.1 indicates an object so I did an object. But is it a list?
7. "command_id": "pf17_8675309"
• These are not specified in WD02. Table 2-3 in section 2.2.5 is TBSL. I don’t propose to open the discussion to all possible options but I do think we should discuss adding these particular options in the context of this particular use case (and others if someone submits use cases/threads where they are needed).
8. "start_time": "now"
• ditto
  
9. "duration": “30s"
• ditto
  
10. Note the command did not specify a ‘response desired’ command option, yet a response is created. This use case assumes that since it is an https api, that there will be a response of some sort. Should the 'want a response' command option default 'yes' (my assumption) or 'no' (in which case I need to add it so I would get a response)?
11. The response on the https api is 200/OK.
    
• This is not mentioned in current WD02.  I thought we had previously agreed to HTTP response codes.What text goes where to say this?
  
12. "response_code" : "Command Accepted"
• not in WD02 since 2.3.1 and 3.1.2 are TBSL
13. "command_id": "pf17_8675309"
• ditto
  

The method described above should tease out missing aspects of the specification. We could go down a lot of rabbit holes of possible arguments on hypothetical usecases, so I propose we focus on those that we have black ink examples of. This would then encourage others to get their black pens out and submit more command/responses of interest to them.

I am submitting this in the spirit of explaining what I meant by threads and how it might help us focus. As this shows, just a simple thread has plenty of issues (13 listed). Conversely, if we solve these the tractable 13 issues, we then have at least one implementable thread complete. I would propose we tackle those issues one a time, but not necessarily in the order above. For example people may want to discuss the command options first and then the response and then the details of ip_connection.

I am not wedded to doing this particular command. As my previous email stated, I would prefer to start on simpler and less controversial threads. Looking at the other threads I know of includes the 4 directories in https://github.com/oasis-tcs/openc2-lsc-usecases (yes I'm plugging github as usual):

• ATT
• DoD
• PolyLogyx
• sFractalConsulting

Looking at them in reverse order - I've already covered what I think is the most appropriate sFractal use case. PolyLogyx has the presentation we viewed at F2F but doesnot yet have specific threads as I define them (ie actual example JSON commands and responses) so for now I'll defer. The DoD use case is not what I would consider 'simpler', but I could be wrong since it doesn't yet include example JSON; so for now I'll defer. There were more ATT use cases at the F2F than on github but I think the two threads that Mike Stair put on github are particularly relevant and I suggest we walk thru them in a similar way I did the above analysis.They are at

- https://github.com/oasis-tcs/openc2-lsc-usecases/blob/master/ATT/01.contain.md

- https://github.com/oasis-tcs/openc2-lsc-usecases/blob/master/ATT/02.allow.md

If there are other threads that people have black-penned, we can do similar.

Duncan Sparrell

sFractal Consulting LLC

iPhone, iTypo, iApologize