Version: 1.2.0
Updates to CybOX Content¶
The following sections detail the changes that stix-ramrod makes when upgrading CybOX content.
Note
The sections below do not detail the full breadth and depth of changes made to the CybOX language between releases. Some updates, such as the addition of new CybOX Objects or controlled vocabulary terms do not require any changes to be made to the source content during an update.
To see a complete list of changes made to CybOX, check out the Release Notes section of a CybOX Language Release page.
Contents
CybOX v2.0.1 to 2.1¶
CybOX v2.1 was a minor release made to CybOX v2.0.1 and included many bug fixes, some of which resulted in backwards incompatibilities with previous versions of CybOX. On top of bug fixes, CybOX 2.1 introduced new controlled vocabularies and terms, CybOX Objects, data types and backwards-compatible structural enhancements.
The sections below describe the changes stix-ramrod performs during an upgrade from CybOX 2.0.1 to CybOX 2.1.
General Updates¶
The following general changes are made to CybOX 2.0.1 content when updating to CybOX 2.1.
- The
xsi:schemaLocation
attribute updated to refer to CybOX 2.1 schemas, hosted at http://cybox.mitre.org/. - The
cybox_major_version
attribute onObservableType
instances set to2
. - The
cybox_minor_version
attribute onObservableType
instances set to1
. - The
cybox_update_version
attribute removed fromObservablesType
instances.
Untranslatable Fields¶
The following fields, data types, attributes or other structures cannot be translated to CybOX v2.1. Updating content which includes these fields will require a forced update.
HTTPSessionObj:X_Forwarded_Proto
element instances.Type
elements instances found inWinExecutableFileObj:PESectionType
.WinMailslotObj:Handle
element instances when it contains more than one childHandle
element.WinTaskObj:Trigger_Type
element instances.
Object Updates¶
The following changes are made to CybOX Objects.
HTTP Session Object¶
HTTPSessionObj:DNT
element data type changed fromURIObj:URIObjectType
tocyboxCommon:StringObjectPropertyType
.HTTPSessionObj:Vary
element data type changed fromURIObj:URIObjectType
tocyboxCommon:StringObjectPropertyType
.HTTPSessionObj:Refresh
updated fromcyboxCommon:IntegerObjectPropertyType
tocyboxCommon:StringObjectPropertyType
Network Packet Object¶
PacketObj:Protol_Addr_Size
renamed toPacketObj:Proto_Addr_Size
PacketObj:Excapsulating_Security_Payload
renamed toPacketObj:Encapsulating_Security_Payload
PacketObj:Authenication_Data
renamed toPacketObj:Authentication_Data
Windows Driver Object¶
- The version of the
Win_Driver_Object.xsd
schema, which defines the Windows Driver Object was upgraded to3.0
. - The namespace for the Windows Driver Object was changed from
http://cybox.mitre.org/objects#WinDriverObject-2
to'http://cybox.mitre.org/objects#WinDriverObject-3
.
Windows Mailslot Object¶
The top-level
WinMailslotObj:Handle
container is removed, causingHandle
child to take it its place. This can only be done if there is oneHandle
child. If more than one childHandle
element is present, the top-levelWinMailslotObj:Handle
container is considered untranslatable.Example CybOX 2.0.1 WinMailslotObj:Handle
<cybox:Object> <cybox:Properties xsi:type="WinMailslotObj:WindowsMailslotObjectType"> <WinMailslotObj:Handle> <WinHandleObj:Handle> <WinHandleObj:Name>Test</WinHandleObj:Name> </WinHandleObj:Handle> </WinMailslotObj:Handle> </cybox:Properties> </cybox:Object>
Example CybOX 2.1 WinMailslotObj:Handle
<cybox:Object> <cybox:Properties xsi:type="WinMailslotObj:WindowsMailslotObjectType"> <WinHandleObj:Handle> <WinHandleObj:Name>Test</WinHandleObj:Name> </WinHandleObj:Handle> </cybox:Properties> </cybox:Object>
Example Untranslatable CybOX 2.0.1 WinMailslotObj:Handle
<cybox:Object> <cybox:Properties xsi:type="WinMailslotObj:WindowsMailslotObjectType"> <WinMailslotObj:Handle> <WinHandleObj:Handle> <WinHandleObj:Name>One Child</WinHandleObj:Name> </WinHandleObj:Handle> <WinHandleObj:Handle> <WinHandleObj:Name>Cannot translate! Two Handle children present.</WinHandleObj:Name> </WinHandleObj:Handle> </WinMailslotObj:Handle> </cybox:Properties> </cybox:Object>
Controlled Vocabulary Updates¶
At a minimum, controlled vocabulary updates include updates to the
vocab_name
, vocab_reference
, and xsi:type
attributes to refer
to new data type names and versions. Instance values may be updated if
typos were fixed in new versions.
The following updates were made to default CybOX controlled vocabularies,
defined by the cybox_default_vocabularies.xsd
schema.
ToolTypeVocab-1.0
updated toToolTypeVocab-1.1
.- Term
'A/V'
changed to'AV'
.
- Term
ObjectRelationshipVocab-1.0
updated toObjectRelationshipVocab-1.1
.ActionNameVocab-1.0
updated toActionNameVocab-1.1
.
Note
Controlled Vocabulary updates can be disabled in stix-ramrod via the
ramrod.UpdateOptions
class or the --disable-vocab-update
option if using ramrod_update.py
.
Empty Optional Fields Removed¶
The following elements were required in CybOX 2.0.1 but became optional in CybOX 2.1. Empty instances of these fields will be stripped during the update process.
DiskPartitionObj:Partition_ID
DNSCacheObj:DNS_Entry
DNSQueryObj:QName
FileObj:Depth
HTTPSessionObj:Message_Body
,HTTPSessionObj:Domain_Name
PacketObj:Address_Mask
,PacketObj:Address_Mask_Reply
,PacketObj:Address_Mask_Request
,PacketObj:Destination_Unreachable
,PacketObj:Echo_Reply
,PacketObj:Echo_Request
,PacketObj:Error_Msg
,PacketObj:Frag_Reassembly_Time_Exceeded
,PacketObj:Host_Redirect
,PacketObj:IP_Addr_Prefix
,PacketObj:IPv6_Addr
,PacketObj:Info_Msg
,PacketObj:Network_Redirect
,PacketObj:Outbound_Packet_Forward_Success
,PacketObj:Outbound_Packet_no_Route
,PacketObj:Receive_Timestamp
,PacketObj:Redirect_Message
,PacketObj:Source_Quench
,PacketObj:TTL_Exceeded_In_Transit
,PacketObj:Time_Exceeded
,PacketObj:Timestamp
,PacketObj:Timestamp_Reply
,PacketObj:Timestamp_Request
,PacketObj:ToS_Host_Redirect
,PacketObj:ToS_Network_Redirect
,PacketObj:Traceroute
,PacketObj:Transmit_Timestamp
SystemObj:IP_Address
URIObj:Value
WinComputerAccountObj:Delegation
,WinComputerAccountObj:Bitmask
,WinComputerAccountObj:Service
WinFileObj:Size_In_Bytes
WinNetworkShareObj:Netname
WinPrefetchObj:VolumeItem
,WinPrefetchObj:DeviceItem
Note
By default, stix-ramrod will remove empty instances of optional fields
which are discovered in input content. This behavior can be disabled via the
ramrod.UpdateOptions
class, or the --disable-remove-optionals
flag if using the bundled ramrod_update.py
CybOX v2.0 to v2.0.1¶
CybOX v2.0.1 was a bugfix release made to CybOX v2.0.1.
The sections below describe the changes stix-ramrod performs during an upgrade from CybOX 2.0 to CybOX 2.0.1.
General Updates¶
The following general changes are made to CybOX 2.0 content when updating to CybOX 2.0.1:
- The
xsi:schemaLocation
attribute updated to refer to CybOX 2.0.1 schemas, hosted at http://cybox.mitre.org/. - The
cybox_major_version
attribute onObservableType
instances set to2
. - The
cybox_minor_version
attribute onObservableType
instances set to0
. - The
cybox_minor_version
attribute added toObservablesType
instances and set to1
.
List Delimiters¶
CybOX 2.0 allows for the definition of multiple Object Property field values
through the use of a reserved list delimiter, which is defined to be ','
(a comma). Grammatical commas were expressed as <![CDATA[,]]>
.
CybOX 2.0.1 changed the reserved list delimiter to be '##comma##'
, allowing
for grammatical commas to be expressed without special syntax or CDATA
wrappers.
Example CybOX 2.0 List¶
<!-- Describes two email subjects: 'Foo' and 'Bar' -->
<EmailObj:Subject condition="Equals" apply_condition="ANY">Foo,Bar</EmailObj:Subject>
Example CybOX 2.0 Grammatical Comma¶
<!-- Use of a grammatical comma -->
<EmailObj:Subject>Et tu<![CDATA[,]]> Brute?</EmailObj:Subject>
CybOX 2.0.1 changed the default list delimiter to be '##comma##'
, allowing
for grammatical commas to be used naturally.
Example CybOX 2.0.1 List¶
<!-- Describes two email subjects: 'Foo' and 'Bar' -->
<EmailObj:Subject condition="Equals" apply_condition="ANY">Foo##comma##Bar</EmailObj:Subject>
Example CybOX 2.0.1 Grammatical Comma¶
<!-- Use of a grammatical comma -->
<EmailObj:Subject>Et tu, Brute?</EmailObj:Subject>
Untranslatable Fields¶
All CybOX 2.0 fields can be translated to 2.0.1. There should not be any need to perform a forced update.
Object Updates¶
All CybOX 2.0 Object content can be updated to 2.0.1 without any structural transformations or content translations.
Controlled Vocabulary Updates¶
At a minimum, controlled vocabulary updates include updates to the
vocab_name
, vocab_reference
, and xsi:type
attributes to refer
to new data type names and versions. Instance values may be updated if
typos were fixed in new versions.
The following updates were made to default CybOX controlled vocabularies,
defined by the cybox_default_vocabularies.xsd
schema.
EventTypeVocab-1.0
updated toEventTypeVocab-1.0.1
- Term
'Anomoly Events'
changed to'Anomaly Events'
- Term
Note
Controlled Vocabulary updates can be disabled in stix-ramrod via the
ramrod.UpdateOptions
class or the --disable-vocab-update
option if using ramrod_update.py
.
Empty Optional Fields Removed¶
No existing fields were made optional in CybOX 2.0.1.