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.
Parameters: - doc – A STIX or CybOX document filename, file-like object,
etree._Element
oretree._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. IfNone
,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
orObservables
root-level node. - If`force` is
False
and an untranslatable field or non-unique ID is found in the input doc.
- The input doc does not contain a
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. IfFalse
no version check operations will be performed. Default value isTrue
.
-
new_id_func
¶ A function for setting new IDs on an
etree._Element
node. The function must accept oneetree._Element
instance argument and assign it a new, uniqueid
attribute value. Default value isramrod.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. IfFalse
, no updates will be performed against controlled vocabulary instances. Default isTrue
.
-
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 isTrue
.
-
-
class
ramrod.
UpdateResults
(document, removed=None, remapped_ids=None)¶ Bases:
object
Returned from
ramrod.update()
,ramrod.cybox.update()
, andramrod.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 theirid
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 onramrod.UpdateResults
Note
This class overrides the
__str__
and__unicode__
methods and can be used withstr()
orprint
.Parameters: document – An instance of etree._Element
oretree._ElementTree
.-
as_element
()¶ Returns an
etree._Element
representation of theResultDocument
instance.
-
as_element_tree
()¶ Returns an
etree._ElementTree
representation of theResultDocument
instance.
-
as_stringio
()¶ Returns a
StringIO
representation of theResultDocument
instance.
-