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.

Parameters:	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.
Returns:	An instance of UpdateResults.
Raises:	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.

check_versions¶

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.

new_id_func¶

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.

Example

>>> 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

update_vocabularies¶

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.

remove_optionals¶

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.

document¶

The updated document. An instance of ramrod.ResultDocument.

removed¶

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

remapped_ids¶

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.

document

class ramrod.ResultDocument(document)¶

Bases: object

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

Note

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.

as_element()¶

Returns an etree._Element representation of the ResultDocument instance.

as_element_tree()¶

Returns an etree._ElementTree representation of the ResultDocument instance.

as_stringio()¶

Returns a StringIO representation of the ResultDocument instance.