Version: 1.2.0

ramrod Module

ramrod.update(doc, from_=None, to_=None, options=None, force=False)

Updates an input STIX or CybOX document to align with a newer version of the STIX/CybOX schemas.

This will perform the following updates:

  • Update namespaces
  • Update schemalocations
  • Update construct versions (STIX_Package, Observables, etc.)
  • Update controlled vocabularies and fix typos
  • Translate structures to new XSD data type instances where possible.
  • Remove empty instances of attributes and elements which were required in one version of the language and declared optional in another.
  • doc – A STIX or CybOX document filename, file-like object, etree._Element or etree._ElementTree object instance.
  • to (optional, string) – The expected output version of the update process. If not specified, the latest language version will be assumed.
  • from (optional, string) – The version to update from. If not specified, the from_ version will be retrieved from the input document.
  • options (optional) – A UpdateOptions instance. If None, ramrod.DEFAULT_UPDATE_OPTIONS will be used.
  • force (boolean) – Attempt to force the update process if the document contains untranslatable fields.

An instance of UpdateResults.

  • UpdateError – If any of the following occur:
    • The input doc does not contain a STIX_Package or Observables root-level node.
    • If`force` is False and an untranslatable field or non-unique ID is found in the input doc.
  • InvalidVersionError – If the input document contains a version attribute that is incompatible with a STIX/CybOX Updater class instance.
  • UnknownVersionError – If from_ was not specified and the input document does not contain a version attribute.
class ramrod.UpdateOptions

Bases: object

Defines configurable options for STIX/CybOX updates.


If True, input document version information will be collected and checked against what the Updater class expects. If False no version check operations will be performed. Default value is True.


A function for setting new IDs on an etree._Element node. The function must accept one etree._Element instance argument and assign it a new, unique id attribute value. Default value is ramrod.utils.new_id() function.


>>> def my_id_func(node):
>>>     new_id = my_generate_unique_id()
>>>     node.attrib['id'] = new_id
>>> options = ramrod.UpdateOptions()
>>> options.new_id_func = my_id_func

If True, default controlled vocabulary instances will be updated and typos will be fixed. If False, no updates will be performed against controlled vocabulary instances. Default is True.


Between revisions of language, some elements which were required are made optional. If True, an attempt is made to find and remove empty instances of once required elements/attributes. Default is True.

class ramrod.UpdateResults(document, removed=None, remapped_ids=None)

Bases: object

Returned from ramrod.update(), ramrod.cybox.update(), and ramrod.stix.update() methods.


The updated document. An instance of ramrod.ResultDocument.


Untranslatable nodes that were removed from the document. An instance of tuple.


An { id: [nodes] } dictionary where the key is a non-unique ID that was discovered in the input document, and the nodes are all the nodes which had their id attribute reassigned to be unique.

class ramrod.ResultDocument(document)

Bases: object

Used to encapsulate an updated XML document. This is the type of the document attribute on ramrod.UpdateResults


This class overrides the __str__ and __unicode__ methods and can be used with str() or print.

Parameters:document – An instance of etree._Element or etree._ElementTree.

Returns an etree._Element representation of the ResultDocument instance.


Returns an etree._ElementTree representation of the ResultDocument instance.


Returns a StringIO representation of the ResultDocument instance.