Update each SDO doc to include Stix v2.1 Examples, if there weren't any

[brettforbes]

Altered some of the docs to include new Stix 2.1 examples, based on:

• OASIS Stix2 Python Library, where the object was an existing SCO
• Hand-made id fields, using a UUID4 Generator for the SDO's
• A Sighting to refer to any of the SDO's and the Observed Data

In short, through some relatively minor changes, we upgrade each document page to include a Stix 2.1 example

[CharlesFrick]

X-oca-asset

This can be an SCO and we will accept changing it to one, that should remove a few of the elements

On line 14: “spec (optional)” needs to be “spec_version (required)”
Line 16: modified (optional) should be modified (required)

X-oca-behavior
spec_version should be required, not optional
Modified should be required, not optional

X-oca-detection
spec_version should be required, not optional
Modified should be required, not optional

X-oca-detector
spec_version should be required, not optional
Modified should be required, not optional

X-oca-geo
spec_version should be required, not optional
Modified should be required, not optional

X-oca-playbook
spec_version should be required, not optional
Modified should be required, not optional

[brettforbes]

X-oca-asset

This can be an SCO and we will accept changing it to one, that should remove a few of the elements

On line 14: “spec (optional)” needs to be “spec_version (required)” Line 16: modified (optional) should be modified (required)

X-oca-behavior spec_version should be required, not optional Modified should be required, not optional

X-oca-detection spec_version should be required, not optional Modified should be required, not optional

X-oca-detector spec_version should be required, not optional Modified should be required, not optional

X-oca-geo spec_version should be required, not optional Modified should be required, not optional

X-oca-playbook spec_version should be required, not optional Modified should be required, not optional

All fixed and pushed as an update. Thanks for the comments, happy to keep refining, cheers

[subbyte]

x-oca-asset should be a SCO in my opinion as well. Thanks for your careful check about spec_version @CharlesFrick

The PR looks good to me. Thanks much for your update and added examples @brettforbes !

[DerekRushton]

I've left a few comments, but everything here seems good to me. The few changes here are really minor so I'll approve this.

[DerekRushton]

"tne runtime environment" should be "the runtime environment", assuming this is a typo.

[brettforbes]

Fixed, I didn't actually write this stuff, but its great for you to point it out at this time, as it is easy for me to correct it.

Thanks a heap

[DerekRushton]

It's minor, but should ensure that the descriptions are either all capitalized or none are.

[brettforbes]

Thanks for pointing that out, there should be a preposition as well, since thats how most descriptions start. So i made it
"The name of the host"

[DerekRushton]

Probably falls out of scope for what you are trying to do, but these descriptions aren't great. They are obvious (except for container type which is somewhat vague) so not a big deal or anything.

[brettforbes]

Wow, great pick.

This "type" field is a clear example of the need for controlled language, and hence should actually be either an Enum (fixed set of strings, cannot be added to) or a Vocab (set of strings, can be added to).

Can you give us a list of strings/descriptions for this type field @subbyte , and your choice of Enum versus Vocab??

It will be easy to add a small table to the markdown doc, and create support in our OCA Vocab repo

[DerekRushton]

Is this just git being weird or do these have odd tab spacing?

[brettforbes]

Aah yes, in your examples, which i copied originally, and then edited, there was a lot of hand-created different types of spacing. We should never use spacing in a json, as it will visualise differently on different formats (IDE vs web).

I had to feed all of my stuff through online space eliminators for json files. Then you use the auto json layout of your IDE, then update it that way. But unfortunately i did not fix any spacing in the original v2.0 examples, so they are still there.

I manually removed these spaces you indicate, which should fix the problem's you have highlighted

[DerekRushton]

Also here.

[brettforbes]

Good spotting, sorted

[brettforbes]

Hi Guys,

Thanks very much for shepherding me through my first PR to a public repo, I appreciate it. I'm actually more of a modeller in different disciplines than an actual computer scientist, so i appreciate working with the big dogs.

As you know our aim is to blend your OCA extensions, with the existing Stix Incident Management extensions and Identity Contact extensions we currently support.

I think its a perfect match, the Stix Incident Management extensions are focused on providing a single layer, at the Sightings Level, where, provenance for each of the 8 different types of evidence can be gathered, thus evidence can be weighted and the decision process semi-automated (e.g. Assessment of Competing Hypotheses), all in Stix. Stix 21 Evidence Model v8.pptx

Behaviours are just a 9th type of evidence, with a well -defined provenance and much higher weighting. They are the next step up from a basic Sighting Analytic, or OCSF Alert in terms of signal quality and weighting, as they are based on a series of deductions made on telemetry, either a prior-discovered pattern or perhaps as the result of a Hunt. Behaviours are less likely to be a false positive and should be able to generate a call to a CACAO server, to run a CACAO workflow from the library (easy if they are using our OS Threat app).

On the other hand, I can't help but feel that the specificity of the Behaviour SDO, and some of the other great ones (x-oca-detection, x-oca-detector, x-coa-playbook etc.) is diminished by being associated with objects with clearly ambiguous meanings which are purely derived from fixed rules and telemetry. They are observables and should be taken in context:

• x-ibm-finding Is this simply the summary OCSF record? An SCO, with refs to other SCO's? Is this observed based on rules?
• x-ibm-tagging Should this be weighted as highly or differently to the assignment of a TTP by a human?
• x-oca-event, how can this be similar to the Event SDO in Incident Stix extension?? Human decision vs telemetry?
• x-oca-geo Is the telemetered location of the same or different value to a human-assigned location??

I found these objects inside the examples I edited, inside an Observed Data object, so they are clearly telemetry. In our view:

• Observables contained within an Observed Data object must form a DAG (Directed Acyclic Graph) -> Stix Best Practices
• In the original examples, the above objects are each connected to other SCO's in a DAG, perfect for a single observation (i.e. a simple decomposition process for a composite OCSF object)
• Telemetry is fundamentally different to externally assigned evidence.
• The report from the inside is different to the external derived report, and the data they hold is often different, although with overlaps (e.g. where would the Asset Registry ID be found, vs the CPU ID? Telemetry Asset SCO, or Asset SDO?
• SCO's seem the best objects for holding telemetry, SDO's seem best for human-assigned objects, stored patterns (Behaviours), or known facts (e.g. the current asset list, SBOM's, installed defences (D3FEND), user identities etc)

You guys are the first to innovate by integrating telemetry into Stix (i.e. Stix-Shifter, Kestrel, Behaviours), and thus you guys are the cutting edge for integration of Stix with OCSF, 3rd-party detection tools and Kestrel hunts.

To finish this PR, we probably should build the vocab or enum object for Container "Type" property. Can you comment please @subbyte?

Respectfully, once this is complete, my next PR will shift those objects into the SCO category, deleting the Sighting objects in the examples, and placing the above objects in the Observed Data "observed_data_refs" fields in the examples, and probably avoiding the need for a whole load of code for you guys. If this next PR is accepted, all that Dev will have to do is the relatively straightforward change of the Observed Data object referencing from v2.0 to v2.1.

Thoughts?