-
Notifications
You must be signed in to change notification settings - Fork 0
Suggested Practices
This page contains suggested practices for developing and consuming CybOX content. There's a similar page in the STIX wiki for STIX Suggested Practices.
Note that these are simply suggested practices. In many cases, operational or technical concerns may prohibit you from implementing them or they may just not make sense in your situation. That's perfectly fine, these are just suggestions.
CybOX IDs are XML QNames. Each ID includes both a namespace portion (optional) and an ID portion (required) separated by a colon (:). The recommend approach to creating CybOX IDs is to define a producer namespace and namespace prefix, then use the form:
[ns prefix]:[construct type]-[GUID]
The "ns prefix" should be a namespace prefix bound to a namespace owned/controlled by the producer of the content.
Some examples:
acme:event-ce431003-ad07-4c96-bd7a-a50a3196e2a0
acme:action-bf8bc5d5-c7e6-46b0-8d22-7500fea77196
acme:observable-79090715-8d6a-46b7-943b-c0bb9e063788
acme:fileobj-965e1140-2c22-4408-a423-b7acc08290a7
In order to use this approach, you will need to define that namespace prefix in the head of your XML document:
<cybox:Observables xmlns:acme="http://acme.example.com" ...This format provides high assurance that IDs will be both unique and meaningful, because the producer namespace denotes who's producing it, the construct name denotes what it is, and the GUID guarantees uniqueness.
In many cases, you'll have an option to either include a component (an object, for example) within the parent component or to reference the component by ID to a representation in a global location.
For example, an Object can include Related Objects. One way of doing this is to include the related object inline in the parent object:
<cybox:Object id="acme:fileobj-f7304dae-94c6-4592-b943-398e1e6916a7">
<cybox:Properties xsi:type="FileObj:FileObjectType">
<!-- SNIP -->
</cybox:Properties>
<cybox:Related_Objects>
<cybox:Related_Object id="acme:mutexobj-3c1221bd-2037-45ec-8129-4ba8d791e86b">
<cybox:Properties xsi:type="MutexObj:MutexObjectType">
<!-- SNIP -->
</cybox:Properties>
<cybox:Relationship xsi:type="cyboxVocabs:ObjectRelationshipVocab-1.0">Created</cybox:Relationship>
</cybox:Related_Object>
</cybox:Object>The other alternative is to reference that TTP, which would be represented elsewhere:
<cybox:Object id="acme:fileobj-f7304dae-94c6-4592-b943-398e1e6916a7">
<cybox:Properties xsi:type="FileObj:FileObjectType">
<!-- SNIP -->
</cybox:Properties>
<cybox:Related_Objects>
<cybox:Related_Object idref="acme:mutexobj-3c1221bd-2037-45ec-8129-4ba8d791e86b" />
<cybox:Relationship xsi:type="cyboxVocabs:ObjectRelationshipVocab-1.0">Created</cybox:Relationship>
</cybox:Related_Object>
</cybox:Object>These situations are a judgment call, but when making that judgment you should consider whether the related construct (object in this case) has value individually or only within the context of the parent? If it only has value in the parent, embedding it may be appropriate. Otherwise it's probably better to reference it. If you're unsure, it's generally safer to reference it.
When creating references, you'll use the idref attribute:
<cybox:Related_Object idref="acme:mutexobj-3c1221bd-2037-45ec-8129-4ba8d791e86b" />When using this idref attribute, you should avoid putting any other attributes or elements in the reference element.
These suggestions only apply when you're creating documents you intend to be human-readable. They simply make the document more readable and easy to validate by XML editors but are not important for automated processing.
For best readability:
- Only include necessary namespaces
- Use the namespace prefixes as defined in the schemas
- Affinity-group or alphabetize namespaces
- Do not include attributes that have default attributes if you're simply setting the attribute to the default (i.e. @negate on indicators).
To ease validation in XML editors:
- Include schemaLocation attributes to the hosted versions of the CybOX schemas
Many places in CybOX use controlled vocabularies to represent data. When possible, you should use the vocabularies included in the CybOX defaults. If necessary you can use your own vocabulary or even use strings outside of any vocabularies.
If you do this to add values that you think might be useful for other CybOX users, you should let us know so we can consider adding it to the default vocabulary.
To remove ambiguity regarding the timezone, all times should include an explicit timezone if possible.
CybOX observables are capable of representing both instance observables (specific events or properties that were observed) or pattern observables (patterns of events or properties that may potentially be observed). The conditional nature of patterns is expressed through the use of the @condition attribute on the fields within the observable. If the @condition attribute is set, that denotes that the field is part of a pattern.
Because it doesn't make sense to mix pattern fields with instance field, if @condition is set on any fields it should be set on all fields. You should not mix and match fields with @condition set and fields without @condition set.
Sometimes, a tool will capture properties about a CybOX object that aren't in the schema for that object type. In some cases this is because the schemas need to be expanded to cover that property, but in other cases this is because the tool is collecting derived information or other properties that are not generally represented for that object type.
In either case, those properties should be collected using the Custom_Properties element of the object properties. This is essentially a simple list of key/value pairs:
<cybox:Properties xsi:type="FileObj:FileObjectType">
<cyboxCommon:Custom_Properties>
<cyboxCommon:Property name="Property Name">Property Value</cyboxCommon:Property>
</cyboxCommon:Custom_Properties>
<!-- Other properties from the FileObjectType schema -->
</cybox:Properties>
When capturing the output from a tool, the suggested practice is to set the @name attribute of the custom property to the exact field name used in the tool. If possible, the @datatype attribute should be set to the datatype that will be output and the value formatted to fit that datatype's formatting. If that's not possible, the exact value reported by the tool should be used and the @datatype attribute should be omitted.
The Bro tool captures the HTTP Transaction depth of an HTTP connection. In the Bro output, this field is called "trans_depth" and the value will be set to some integer (whatever the depth is). So the @name attribute should be set to trans_depth, the value should be set to the output from Bro, and the @datatype attribute should be set to "int" (Integer). That would give you something like:
<cyboxCommon:Custom_Properties>
<cyboxCommon:Property name="trans_depth" datatype="int">3</cyboxCommon:Property>
</cyboxCommon:Custom_Properties>