STIX 2.1 105: Versioning

Posted by:

If you are reading this blog post via a 3rd party source it is very likely that many parts of it will not render correctly. Please view the post on signalscorps.com for the full interactive viewing experience.

In this post I will show you some best practices for modifying STIX Objects by implementing proper versioning.

Note: this post is written for OASIS STIX version 2.1. The concepts discussed are not always correct for earlier versions of OASIS STIX.

Intelligence evolves over time. New things are learned. Errors are identified. Adversaries change their tactics.

STIX 2.1 Versioning allows for the tracking and management of such changes.

STIX SDOs and SROs can be versioned in order to update, add, remove information, or revoke the entire Object.

The decision ultimately comes down to whether to use the same Object (minor change), a new Object (major change), or to revoke the Object from circulation entirely when creating a new version of it.

First it is important to realise every STIX Object has three required Common Properties important for versioning;

id: e.g. attack-pattern--0c7b5b88-8ff7-4a4d-aa9d-feb398cd0061
created: The time the Object was created
modified: The time the Object was last modified
created_by_ref: e.g. identity--f431f809-377b-45e0-aa1c-6a4751cae5ff
revoked: if set to true means that the Object no longer considered valid by the creator

OASIS don’t define exactly what constitutes a minor or major change, but I will give you some guidance in this post based on my experience.

Versioning minor changes

In the case of minor changes you can modify all the Object Properties, including adding new ones or removing old ones. The only exception being the id and created values. The modified Property should be updated with the timestamp of the change.

For example, if I wanted to change the name Property of a Threat Actor Object from Evil Org to New Evil Org, all I need to do is modify the Object with the new name, making sure to update the modified time.

Here is an example of the. First the original SDO;

And the second, updated, version of the same SDO;

Note, the two have the same id and modified values but different name and modified values (where the year has changed from 2016 to 2020 – the time the update happened).

Consumers (and the software they are using) should now default to the latest version using the modified time, ignoring any earlier modified times for that Object.

Versioning major changes

Like with minor changes, there is no formal definition to what constitutes a major change where a new Object should be created.

However, one common scenario where a new Object must be created is when someone other than the creator (defined in the created_by_ref Property) wants to make a change to an Object.

Other scenarios where a major change might be considered, but it not required, is when a fundamental change to the Object occurs, for example, new Properties are added because more is understood about what is being represented in the Object.

Instead of updating the Object like in a minor change, the process of performing a major change involves creating a new Object with the updated data (including a new id), and then linking the two SDOs together using an SRO with the Property "relationship_type": "derived-from".

I will use the same SDO example as before, but this time demonstrate a major change which produces;

Now two SDOs exists, the new (New Evil Org) and the old one (First Evil Org) both with different ids with the SRO showing where the latest version was derived-from.

If you download the STIX Bundle for this graph, you will see both versions of the Object in the Bundle.

You might be tempted to default to major updates so that you have a clear audit trail. Though it is important to stress that this is not required.

When creating new minor versions, you can keep (and disseminate) all versions of the Object (with different modified times) in your TAXII feed (or whatever other method you use to share).

As a rule of thumb, if the content is yours then it is likely a minor change is what you need. If you want to modify someone else’s content then a major change is what you need.

Versioning revoked objects

In some cases you might want to completely revoke an Object.

This is often used when a data producer makes an error in the creation of an Object that was never meant to exist. For example, an Indicator SDO for google.com.

In other cases, you might want to revoke a SRO, for example, when you realise two Objects are not actually related.

In the case of typos or small errors, it is generally better to evoke a minor update instead of revoking the entire Object.

Revoking an Object is very simple. All you need to do is add the Property and Property value "revoked": true as shown below;

What about SCOs?

SCOs are not versioned and therefore do not have the four versioning Properties covered for SCOs.

However, there are of course many occasions where SCOs do need to be updated.

OASIS warn against using the Properties created, modified, created_by_ref, revoked due to interoperability and sharing issues.

As there is no standard way to define an update to an SCO, I use the same approach as major updates to update SCOs, using a SRO to link them with with the Property "relationship_type": "derived-from".

Here is an example of just that where I update a Network Traffic SCO to include new content in its Extension Property;

You have now read about some of the most important and widely used STIX 2.1 concepts.

The next step is to share your STIX 2.1 content and the knowledge it holds with other consumers.

In my next post I will put what I have shared over the previous weeks together to create STIX Bundles.

STIX 2.1 Certification (Virtual and In Person)

The content used in this post is a small subset of our full training material used in our STIX 2.1 training.

If you want to join a select group of certified STIX 2.1 professionals, subscribe to our newsletter below to be notified of new course dates.

Discuss this post

JOIN US