Version: 1.2.0

ramrod.cybox.cybox_2_0_1 Module

class ramrod.cybox.cybox_2_0_1.Cybox_2_0_1_Updater

Updates CybOX v2.0.1 content to CybOX v2.1.

The following fields are translated:

  • ToolTypeVocab-1.0 updated to ToolTypeVocab-1.1
  • ObjectRelationshipVocab-1.0 updated to ObjectRelationshipVocab-1.1
  • ActionNameVocab-1.0 updated to ActionNameVocab-1.1
  • HTTPSessionObj:DNT updated from URIObjectType to StringObjectPropertyType
  • HTTPSessionObj:Vary updated from URIObjectType to StringObjectPropertyType
  • HTTPSessionObj:Refresh updated from IntegerObjectPropertyType to StringObjectPropertyType
  • PacketObj:Protol_Addr_Size renamed to PacketObj:Proto_Addr_Size
  • PacketObj:Excapsulating_Security_Payload renamed to PacketObj:Encapsulating_Security_Payload
  • PacketObj:Authenication_Data renamed to PacketObj:Authentication_Data
  • WinMailslotObj:Handle container element removed and child bubbled up when only one child is defined.

Empty instances of the following optional elements are removed:

  • DiskPartitionObj:Partition_ID
  • DNSCacheObj:DNS_Entry
  • DNSQueryObj:QName
  • FileObj:Depth
  • HTTPSessionObj:Message_Bod, 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

The following fields cannot be translated:

  • HTTPSession:X_Forwarded_Proto instances.
  • WinExecutableFileObj:PESectionType/Type instances.
  • WinMailslotObj:Handle when more than one child is defined.
  • WinTaskObj:Trigger_Type instances.
check_update(root, options=None)

Determines if the input document can be upgraded.

Parameters:
  • root – The XML document. This can be a filename, a file-like object, an instance of etree._Element or an instance of etree._ElementTree.
  • options (optional) – A ramrod.UpdateOptions instance. If None, ramrod.DEFAULT_UPDATE_OPTIONS will be used.
Raises:
  • UnknownVersionError – If the input document does not have a version.
  • InvalidVersionError – If the version of the input document does not match the VERSION class-level attribute value.
  • UpdateError – If the input document contains fields which cannot be updated or constructs with non-unique IDs are discovered.
clean(root, options=None)

Removes disallowed elements from root and remaps non-unique IDs to unique IDs for the sake of schema-validation.

Removed items can be retrieved via the removed attribute on the return value:

>>> results = updater.clean(root)
>>> print(results.removed)
(<Element at 0xffdcf234>, <Element at 0xffdcf284>)

Items which have been reassigned IDs can be retrieved via the remapped_ids attribute on the return value:

>>> results = updater.clean(root)
>>> print(results.remapped_ids)
{'example:Observable-duplicate': [<Element {http://cybox.mitre.org...

Note

This does not remap idref attributes to new ID values because it is impossible to determine which entity the idref was pointing to.

Parameters:
  • root – The XML document. This can be a filename, a file-like object, an instance of etree._Element or an instance of etree._ElementTree.
  • options (optional) – A ramrod.UpdateOptions instance. If None, ramrod.DEFAULT_UPDATE_OPTIONS will be used.
Returns:

An instance of ramrod.UpdateResults.
get_version(observables)

Returns the version of the observables Observables node.

Returns:

A dotted-decimal a version string from the cybox_major, cybox_minor and cybox_update attribute values.
Raises:

UnknownVersionError – If observables does not contain any of the following attributes:

  • cybox_major_version
  • cybox_minor_version
  • cybox_update_version
update(root, options=None, force=False)

Attempts to update root to the next version of its language specification.

If force is set to True, items may be removed during the translation process and IDs may be reassigned if they are not unique within the document.

Note

This does not remap idref attributes to new ID values because it is impossible to determine which entity the idref was pointing to.

Removed items can be retrieved via the removed attribute on the return value:

>>> results = updater.update(root, force=True)
>>> print(results.removed)
(<Element at 0xffdcf234>, <Element at 0xffdcf284>)

Items which have been reassigned IDs can be retrieved via the remappped_ids attribute on the return value:

>>> results = updater.update(root, force=True)
>>> print(results.remapped_ids)
{'example:Observable-duplicate-id-1': [<Element {http://cybox.mitre...
Parameters:
  • root – The XML document. This can be a filename, a file-like object, an instance of etree._Element or an instance of etree._ElementTree.
  • options – A ramrod.UpdateOptions instance. If None, ramrod.DEFAULT_UPDATE_OPTIONS will be used.
  • force – Forces the update process to complete by potentially removing untranslatable xml nodes and/or remapping non-unique IDs. This may result in non-schema=conformant XML. USE AT YOUR OWN RISK!
Returns:

An instance of ramrod.UpdateResults.
Raises:
  • UpdateError – If untranslatable fields or non-unique IDs are discovered in root and force is False.
  • UnknownVersionError – If the root node contains no version information.
  • InvalidVersionError – If the root node contains invalid version information (e.g., the class expects v1.0 content and the root node contains v1.1 content).