Version: 1.2.0

Getting Started

This page gives an introduction to stix-ramrod and how to use it. Please note that this page is being actively worked on and feedback is welcome! If you have a suggestion or something doesn’t look right, let us know: (stix@mitre.org).

Note that the GitHub repository is named stix-ramrod, but once installed, the library is imported using the import ramrod statement.

Installation

To install stix-ramrod just run pip install stix-ramrod. If you have any issues, please refer to the instructions found on the Installation page.

Scripts

These instructions tell you how to upgrade STIX or CybOX content using the scripts bundled with stix-ramrod.

Ramrod Update

Currently, the only script bundled with stix-ramrod is the ramrod_update.py script, which can be found on your PATH after installing stix-ramrod.

Options

Running ramrod_update.py -h displays the following:

$ ramrod_update.py -h
usage: ramrod_update.py [-h] --infile INFILE [--outfile OUTFILE]
                        [--from VERSION IN] [--to VERSION OUT]
                        [--disable-vocab-update] [--disable-remove-optionals]
                        [-f]

Ramrod Updater v1.0a1: Updates STIX and CybOX documents.

optional arguments:
  -h, --help            show this help message and exit
  --infile INFILE       Input STIX/CybOX document filename.
  --outfile OUTFILE     Output XML document filename. Prints to stdout if no
                        filename is provided.
  --from VERSION IN     The version of the input document. If not supplied,
                        RAMROD will try to determine the version of the input
                        document.
  --to VERSION OUT      Update document to this version. If no version is
                        supplied, the document will be updated to the latest
                        version.
  --disable-vocab-update
                        Controlled vocabulary strings will not be updated.
  --disable-remove-optionals
                        Do not remove empty elements and attributes which were
                        required in previous language versions but became
                        optional in later releases.
  -f, --force           Removes untranslatable fields, remaps non-unique IDs,
                        and attempts to force the update process.

Updating STIX And CybOX Content

The ramrod_update.py script can accept either STIX STIX_Package or CybOX Observables documents as input. You don’t need to tell it that you’re updaing STIX or CybOX content–it’ll figure it out for you!

Basics

To update content, just provide --infile and --outfile arguments which specify the input filename and output filename. If --outfile is not specified, the updated document will be printed to stdout.

$ ramrod_update.py --infile stix_doc.xml --outfile update_stix_doc.xml
Specifying Input And Output Versions

By default, ramrod_update.py will inspect the input document for a version number and assume that it wants to be updated to the latest version. However, you can pass in --from and/or --to arguments to override this behavior.

To specify the output version, use the --to argument. The following example shows how to translate a STIX v1.0 document to STIX v1.0.1:

$ ramrod_update.py --infile stix_1.0_doc.xml --to 1.0.1

If the input document does not have a version number specified (it should!), you can use the --from argument to declare the version of the document. The following example shows how you might declare the input document to be version STIX v1.1:

$ ramrod_update.py --infile stix_unversioned_doc.xml --from 1.1
Handling Untranslatable Elements And Attributes

Some STIX and CybOX constructs have changed a lot between revisions because of growing requirements from community members, or bugfixes where the incorrect data type was assigned to a field initially and needed to be corrected. Because of this, sometimes a lossless update isn’t possible.

By default, ramrod_update.py will inspect the input document for untranslatable fields or ID collisions, and alert the user of their presence:

$ ramrod_update.py --infile samples/stix_1.0_forcible.xml
[!] Update Error: Found untranslatable fields in source document.
[!] Found the following untranslatable items:
    Line 88: {http://stix.mitre.org/TTP-1}Attack_Pattern
    Line 71: {http://stix.mitre.org/TTP-1}Malware_Instance

At this point, users can decide to force the update process by using the --force or -f argument. This will remove the untranslatable items from the document during the update process and attempt to render a schema-valid document in the process.

Note

STIX v1.1 and CybOX v2.1 introduced schema-enforced ID uniqueness constraints. If updating content that is older than STIX v1.1 or CybOX 2.1, non-unique IDs will halt an update process. Using --force will cause new, unique IDs to be generated and assigned to colliding nodes.