Version: 1.2.0
Updates to STIX Content¶
The following sections detail the changes that stix-ramrod makes when upgrading STIX content.
Note
The sections below do not detail the full breadth and depth of changes made to the STIX language between releases. Some updates, such as the addition of new structures or controlled vocabulary terms do not require any changes to be made to the source content during an update.
To see a complete list of changes made to STIX, check out the Release Notes section of a STIX Language Release page.
Contents
STIX v1.1.1 to v1.2¶
STIX v1.2 was a minor release of the STIX language that introduced new schemas, expanded vocabularies and introduced new capabilities for existing data types.
STIX 1.2 is completely backwards compatible with STIX 1.1.1, so stix-ramrod makes minimal changes to STIX v1.1.1 content when upgrading to STIX v1.2.
The sections below describe the changes stix-ramrod performs during an upgrade from STIX v1.1.1 to STIX v1.2.
General Updates¶
The following general changes are made to STIX v1.1 content when updating to STIX v1.1.1:
- The
xsi:schemaLocation
attribute updated to refer to STIX v1.2 schemas, hosted at http://stix.mitre.org/. - The
version
attribute onSTIXType
instances set to1.2
. - The
version
attribute onIncidentType
instances set to1.2
. - The
version
attribute onTTPType
instances set to1.2
. - The
version
attribute onCourseOfActionType
instances set to1.2
. - The
version
attribute onThreatActorType
instances set to1.2
. - The
version
attribute onCampaignType
instances set to1.2
. - The
version
attribute onExploitTargetType
instances set to1.2
. - The
version
attribute onIndicatorType
instances set to2.2
.
Untranslatable Fields¶
No field translations are performed when upgrading from STIX v1.1.1 to STIX v1.2.
Translated Fields¶
There are no required translations when upgrading from STIX v1.1.1 to STIX v1.2.
Controlled Vocabulary Updates¶
At a minimum, controlled vocabulary updates include updates to the
vocab_name
, vocab_reference
, and xsi:type
attributes to refer
to new data type names and versions. Instance values may be updated if
typos were fixed in new versions.
The following updates were made to default STIX controlled vocabularies,
defined by the stix_default_vocabularies.xsd
schema.
DiscoveryMethodVocab-1.0
updated toDiscoveryMethodVocab-2.0
.- Term
'Fraud Detection'
corrected to'External - Fraud Detection'
.
- Term
Note
Controlled Vocabulary updates can be disabled in stix-ramrod via the
ramrod.UpdateOptions
class or the --disable-vocab-update
option if using ramrod_update.py
.
Empty Optional Fields Removed¶
No fields were changed from required to optional between STIX v1.1.1 and STIX v1.2.
STIX v1.1 to v1.1.1¶
STIX v1.1.1 was a bugfix release of the STIX language that fixed incorrect data types, typos, and requirements.
The sections below describe the changes stix-ramrod performs during an upgrade from STIX v1.1. to STIX v1.1.1
General Updates¶
The following general changes are made to STIX v1.1 content when updating to STIX v1.1.1:
- The
xsi:schemaLocation
attribute updated to refer to STIX v1.1 schemas, hosted at http://stix.mitre.org/. - The
version
attribute onSTIXType
instances set to1.1.1
. - The
version
attribute onIncidentType
instances set to1.1.1
. - The
version
attribute onTTPType
instances set to1.1.1
. - The
version
attribute onCourseOfActionType
instances set to1.1.1
. - The
version
attribute onThreatActorType
instances set to1.1.1
. - The
version
attribute onCampaignType
instances set to1.1.1
. - The
version
attribute onExploitTargetType
instances set to1.1.1
. - The
version
attribute onIndicatorType
instances set to2.1.1
.
Note
STIX v1.1 and STIX v1.1.1 are both tightly integrated with CybOX v2.1.
Updating STIX v1.1 content to STIX v1.1.1 will result in CybOX schema
locations in the xsi:schemaLocation
attribute to be updated
to point to the schemas hosted at http://cybox.mitre.org/. No other updates
to CybOX content are performed.
Untranslatable Fields¶
All fields can be translated from STIX v1.1 to STIX v1.1.1.
Translated Fields¶
The following fields and data types are were changed in STIX v1.1 in a manner that requires translation in order to maintain a schema-valid status.
stixCommon:ConfidenceType and stixCommon:StatementType¶
When updating from STIX v1.0.1 to STIX v1.1, instances of
stixCommon:ConfidenceType
and stixCommon:StatementType
must have
their Source
child elements updated to be instances of
stixCommon:InformationSourceType
.
In STIX v1.1, the Source
field was of type
stixCommon:ControlledVocabularyStringType
.
In STIX v1.1.1, the Source
field was updated to be of type
stixCommon:InformationSourceType
, a much richer data type with
many more fields.
The value of the STIX v1.1 Source
field is translated into an instance of
stixCommon:IdentityType
, where the Source
value becomes the value of
the Name
field under stixCommon:IdentityType
. The new
stixCommon:IdentityType
instance is assigned to the Identity
field
of the stixCommon:InformationSourceType
Source
field.
Example: A STIX v1.1 stixCommon:ConfidenceType
instance.
<stixCommon:Confidence>
<stixCommon:Source>Example</stixCommon:Source>
</stixCommon:Confidence>
Example: A STIX v1.1.1 stixCommon:ConfidenceType
instance.
<stixCommon:Confidence>
<stixCommon:Source>
<stixCommon:Identity>
<stixCommon:Name>Example</stixCommon:Name>
</stixCommon:Identity>
</stixCommon:Source>
</stixCommon:Confidence>
indicator:SightingType¶
When updating from STIX v1.1 to STIX v1.1.1, instances of
indicator:SightingType
must have their Source
child element updated to
be instances of stixCommon:InformationSourceType
.
In STIX v1.1, the Source
field was of type
stixCommon:StructuredTextType
.
In STIX v1.1.1, the Source
field was updated to be of type
stixCommon:InformationSourceType
, a much richer data type with
many more fields.
The value of the STIX v1.1 Source
field is translated into an instance of
stixCommon:IdentityType
, where the Source
value becomes the value of
the Name
field under stixCommon:IdentityType
. The new
stixCommon:IdentityType
instance is assigned to the Identity
field
of the stixCommon:InformationSourceType
Source
field.
Example: A STIX v1.1 indicator:SightingType
instance.
<indicator:Sighting>
<indicator:Source>Example</indicator:Source>
</indicator:Sighting>
Example: A STIX v1.1.1 indicator:SightingType
instance.
<indicator:Sighting>
<indicator:Source>
<stixCommon:Identity>
<stixCommon:Name>Foobar</stixCommon:Name>
</stixCommon:Identity>
</indicator:Source>
</indicator:Sighting>
stixCommon:CampaignReferenceType¶
When updating from STIX v1.1 to STIX v1.1.1, instances of
stixCommon:CampaignReferenceType
must be updated.
In STIX v1.1, the stixCommon:CampaignReferenceType
contained a child
Names
element, which was of type stixCommon:NamesType
.
In STIX v1.1.1, the stixCommon:CampaignReferenceType
was updated to
extend the stixCommon:GenericRelationshipType
and introduced a new
Campaign
element layer as a result.
Example: A STIX v1.1 stixCommon:CampaignReferenceType
instance.
<indicator:Related_Campaigns>
<indicator:Related_Campaign>
<stixCommon:Names>
<stixCommon:Name>Example</stixCommon:Name>
</stixCommon:Names>
</indicator:Related_Campaign>
<indicator:Related_Campaign idref='campaign-foo-1'/>
</indicator:Related_Campaigns>
Example: A STIX v1.1.1 stixCommon:CampaignReferenceType
instance.
<indicator:Related_Campaigns>
<indicator:Related_Campaign>
<stixCommon:Campaign>
<stixCommon:Names>
<stixCommon:Name>Example</stixCommon:Name>
</stixCommon:Names>
</stixCommon:Campaign>
</indicator:Related_Campaign>
<indicator:Related_Campaign>
<stixCommon:Campaign idref="campaign-foo-1>
</indicator:Related_Campaign>
</indicator:Related_Campaigns>
Controlled Vocabulary Updates¶
At a minimum, controlled vocabulary updates include updates to the
vocab_name
, vocab_reference
, and xsi:type
attributes to refer
to new data type names and versions. Instance values may be updated if
typos were fixed in new versions.
The following updates were made to default STIX controlled vocabularies,
defined by the stix_default_vocabularies.xsd
schema.
AvailabilityLossVocab-1.0` updated to ``AvailabilityLossVocab-1.1.1
.- Term
'Degredation'
corrected to'Degradation'
.
- Term
Note
Controlled Vocabulary updates can be disabled in stix-ramrod via the
ramrod.UpdateOptions
class or the --disable-vocab-update
option if using ramrod_update.py
.
Empty Optional Fields Removed¶
The following elements were required in STIX v1.1 but became optional in STIX v1.1.1. Empty instances of these fields will be stripped during the update process.
- All child nodes of the Generic Test Mechanism extension instance,
GenericTestMechanismType
.
Note
By default, stix-ramrod will remove empty instances of optional fields
which are discovered in input content. This behavior can be disabled via the
ramrod.UpdateOptions
class, or the --disable-remove-optionals
flag if using the bundled ramrod_update.py
STIX v1.0.1 to v1.1¶
STIX v1.1 was a minor release which came after STIX v1.0.1. STIX v1.1 introduced a number of new fields, data types, and extensions for capturing and characterizing cyber threat intelligence data.
The sections below describe the changes stix-ramrod performs during an upgrade from STIX v1.0.1 to v1.1
General Updates¶
The following general changes are made to STIX v1.0.1 content when updating to STIX v1.1
- The
xsi:schemaLocation
attribute updated to refer to STIX v1.1 schemas, hosted at http://stix.mitre.org/. - The
version
attribute onSTIXType
instances set to1.1
. - The
version
attribute onIncidentType
instances set to1.1
. - The
version
attribute onTTPType
instances set to1.1
. - The
version
attribute onCourseOfActionType
instances set to1.1
. - The
version
attribute onThreatActorType
instances set to1.1
. - The
version
attribute onCampaignType
instances set to1.1
. - The
version
attribute onExploitTargetType
instances set to1.1
. - The
version
attribute onIndicatorType
instances set to2.1
. - Namespace definitions for MAEC 4.0.1 Malware extension removed during
translation:
http://stix.mitre.org/extensions/Malware#MAEC4.0-1
- Namespace definitions for CAPEC 2.6.1 Attack Pattern extension removed during
translation:
http://stix.mitre.org/extensions/AP#CAPEC2.6-1
Note
CybOX v2.0.1 is tightly integrated into STIX v1.0.1. As such, any CybOX 2.0.1 content found within a STIX v1.0.1 document will be updated to CybOX 2.1. See the Updates to CybOX Content page for more details about CybOX content updates with stix-ramrod.
Untranslatable Fields¶
The following fields, data types, attributes or other structures cannot be translated to STIX v1.1. Updating content which includes these fields will require a forced update.
- Instances of MAEC 4.0.1 Malware extension
MAEC4.0InstanceType
. - Instances of CAPEC 2.6.1 Attack Pattern extension
CAPEC2.6InstanceType
. - Instances of
ttp:Malware
where all children are instances of MAEC 4.0.1 Malware extension. - Instances of
ttp:Attack_Patterns
where all children are instances of CAPEC 2.6.1 Attack Pattern extension. - Instances of
stixCommon:Date_Time
that do not have validxs:dateTime
values.
Translated Fields¶
The following fields and data types are were changed in STIX v1.1 in a manner that requires translation in order to maintain a schema-valid status.
stixCommon:Contributors¶
When updating from STIX v1.0.1 to STIX v1.1, instances of
stixCommon:ContributorsType
must be translated to instances of
stixCommon:ContributingSourceType
.
The STIX v1.0.1 ContributorsType contains a list of Contributor
elements under it which were IdentityType instances.
The STIX v1.1 ContributingSourcesType contains a list of Source
elements under it which are instances of InformationSourceType.
Because InformationSourceType has an Identity
child element which is
an instance of IdentityType
, we can perform the following transformation:
Example: A STIX v1.0.1 ContributorsType
instance.
<stixCommon:Contributors>
<stixCommon:Contributor>
<stixCommon:Name>Example</stixCommon:Name>
</stixCommon:Contributor>
<stixCommon:Contributor>
<stixCommon:Name>Another</stixCommon:Name>
</stixCommon:Contributor>
</stixCommon:Contributors>
Example: A STIX v1.1 ContributingSourceType
instance.
<stixCommon:Contributing_Sources>
<stixCommon:Source>
<stixCommon:Identity>
<stixCommon:Name>Example</stixCommon:Name>
</stixCommon:Identity>
</stixCommon:Source>
<stixCommon:Source>
<stixCommon:Identity>
<stixCommon:Name>Another</stixCommon:Name>
</stixCommon:Identity>
</stixCommon:Source>
</stixCommon:Contributing_Sources>
ttp:Exploit_Targets¶
When updating from STIX v1.0.1 to STIX v1.1, instances of
stixCommon:ExploitTargetsType
change from a flat list of
stixCommon:ExploitTargetBaseType
instances to an extension of
stixCommon:GenericRelationshipListType
.
Example: A STIX v1.0.1 ttp:Exploit_Targets
instance.
<ttp:Exploit_Targets>
<stixCommon:Exploit_Target idref='example:et-1'/>
<stixCommon:Exploit_Target idref='example:et-2'/>
</ttp:Exploit_Targets>
Example: A STIX v1.1 ttp:Exploit_Targets
instance.
<ttp:Exploit_Targets>
<ttp:Exploit_Target>
<stixCommon:Exploit_Target idref='example:et-1'/>
</ttp:Exploit_Target>
<ttp:Exploit_Target>
<stixCommon:Exploit_Target idref='example:et-2'/>
</ttp:Exploit_Target>
</ttp:Exploit_Targets>
Controlled Vocabulary Updates¶
At a minimum, controlled vocabulary updates include updates to the
vocab_name
, vocab_reference
, and xsi:type
attributes to refer
to new data type names and versions. Instance values may be updated if
typos were fixed in new versions.
The following updates were made to default STIX controlled vocabularies,
defined by the stix_default_vocabularies.xsd
schema.
MotivationVocab-1.0.1
updated toMotivationVocab-1.1
.- Term
'Policital'
corrected to'Political'
.
- Term
IndicatorTypeVocab-1.0
updated toIndicatorTypeVocab-1.1
.
Note
Controlled Vocabulary updates can be disabled in stix-ramrod via the
ramrod.UpdateOptions
class or the --disable-vocab-update
option if using ramrod_update.py
.
Empty Optional Fields Removed¶
The following elements were required in STIX v1.0.1 but became optional in STIX v1.1. Empty instances of these fields will be stripped during the update process.
marking:Controlled_Structure
marking:Marking_Structure
Note
By default, stix-ramrod will remove empty instances of optional fields
which are discovered in input content. This behavior can be disabled via the
ramrod.UpdateOptions
class, or the --disable-remove-optionals
flag if using the bundled ramrod_update.py
STIX v1.0 to v1.0.1¶
STIX v1.0.1 was a bugfix release which came after STIX v1.0. Because it is an bugfix release the number of changes is small.
The sections below describe the changes stix-ramrod performs during an upgrade from STIX v1.0 to v1.0.1
General Updates¶
The following general changes are made to STIX v1.0 content when updating to STIX v1.0.1.
- The
xsi:schemaLocation
attribute updated to refer to STIX v1.0.1 schemas, hosted at http://stix.mitre.org/. - The
version
attribute onSTIXType
instances set to1.0.1
. - The
version
attribute onIncidentType
instances set to1.0.1
. - The
version
attribute onTTPType
instances set to1.0.1
. - The
version
attribute onCourseOfActionType
instances set to1.0.1
. - The
version
attribute onThreatActorType
instances set to1.0.1
. - The
version
attribute onCampaignType
instances set to1.0.1
. - The
version
attribute onExploitTargetType
instances set to1.0.1
. - The
version
attribute onIndicatorType
instances set to2.0.1
. - Namespace definitions for MAEC 4.0 Malware extension removed during
translation:
http://stix.mitre.org/extensions/Malware#MAEC4.0-1
- Namespace definitions for CAPEC 2.5 Attack Pattern extension removed during
translation:
http://stix.mitre.org/extensions/AP#CAPEC2.5-1
Note
CybOX v2.0 is tightly integrated into STIX v1.0. As such, any CybOX 2.0 content found within a STIX v1.0 document will be updated to CybOX 2.0.1. See the Updates to CybOX Content page for more details about CybOX content updates with stix-ramrod.
Untranslatable Fields¶
The following fields, data types, attributes or other structures cannot be translated to STIX v1.0.1. Updating content which includes these fields will require a forced update.
- Instances of MAEC 4.0 Malware extension
MAEC4.0InstanceType
. - Instances of
ttp:Malware
where all children are instances of MAEC 4.0 Malware extension. - Instances of CAPEC 2.5 Attack Pattern extension
CAPEC2.5InstanceType
. - Instances of
ttp:Attack_Patterns
where all children are instances of CAPEC 2.5 Attack Pattern extension.
Controlled Vocabulary Updates¶
At a minimum, controlled vocabulary updates include updates to the
vocab_name
, vocab_reference
, and xsi:type
attributes to refer
to new data type names and versions. Instance values may be updated if
typos were fixed in new versions.
The following updates were made to default STIX controlled vocabularies,
defined by the stix_default_vocabularies.xsd
schema.
MotivationVocab-1.0
updated toMotivationVocab-1.0.1
.- Term
'Ideological - Anti-Establisment'
corrected to'Ideological - Anti-Establishment'
.
- Term
PlanningAndOperationalSupportVocab-1.0
updated toPlanningAndOperationalSupportVocab-1.0.1
.- Term
'Planning - Open-Source Intelligence (OSINT) Gethering'
corrected to'Planning - Open-Source Intelligence (OSINT) Gathering'
- Term
'Planning '
corrected to'Planning'
(trailing space removed)
- Term
Note
Controlled Vocabulary updates can be disabled in stix-ramrod via the
ramrod.UpdateOptions
class or the --disable-vocab-update
option if using ramrod_update.py
.
Empty Optional Fields Removed¶
There are no optional fields that are removed when updating from STIX v1.0 to STIX v1.0.1.