5.1. Bundle
Type Name:
bundle
|
Status:
Review
MVP:
Yes
|
A
bundle is a wrapper object used to group a collection of TLOs together to enable them to be transported
within or outside of a TAXII connection. A bundle is not a standard TLO itself and is only used to group STIX objects for transportation. It can be thought of as an envelope, enabling the delivery of the objects it contains. It does not have any of the TLO
Common Properties other than the type and
id fields.
bundle should not be treated as a persistent object.
5.1.1. Properties
Property Name
|
Type
|
Description
|
type (required)
|
string
|
Indicates that this object is a STIX Bundle. The value of this field
MUST be bundle
|
id (required)
|
identifier
|
An identifier for this bundle. The
id field for the bundle is designed to help tools that may need it for processing, but tools are not required to
store or track it. Consuming tools should not rely on the presence of this field.
|
spec_version
(required)
|
spec-version-enum
|
The version of the STIX specification used to represent the content in this bundle. This enables non-TAXII transports or other transports without their
own content identification mechanisms to know the version of STIX content.
|
attack_patterns
(optional)
|
list
of type
attack-pattern
|
Specifies a set of one or more Attack Patterns.
|
campaigns
(optional)
|
list of type campaign
|
Specifies a set of one or more Campaigns.
|
courses_of_action (optional)
|
list of type
course-of-action
|
Specifies a set of one or more Courses of Action that could be taken in regard to one of more cyber threats.
|
identities
(optional)
|
list of type
identity
|
Specifies a set of one or more identities of individuals or organizations.
|
indicators (optional)
|
list of type
indicator
|
Specifies a set of one or more cyber threat Indicators.
|
malware
(optional)
|
list
of type
malware
|
Specifies a set of one or more Malware TTPs.
|
marking_definitions
(optional)
|
list
of type
marking-definition
|
Specifies a set of one or more Marking Definitions.
|
observations (optional)
|
list of type
observation
|
Specifies a set of one or more cyber observations.
|
relationships
(optional)
|
list of type
relationship
|
Specifies a set of one or more relationships between TLOs.
|
reports
(optional)
|
list of type
report
|
Specifies a set of one or more reports.
|
sightings
(optional)
|
list of type
sighting
|
Specifies a set of one or more sightings.
|
threat_actors
(optional)
|
list of type
threat-actor
|
Specifies a set of one or more Threat Actors.
|
5.1.2. Relationships
NONE. This object is not a TLO and cannot have any relationships to it or from it.
5.1.3. Examples
{
"type": "bundle",
"spec_version": "2.0”,
"indicators": [
{
"type": "indicator",
"id": "indicator--8e2e2d2b-17d4-4cbf-938f-98ee46b3cd3f",
"created_by_ref": "source--f431f809-377b-45e0-aa1c-6a4751cae5ff",
"created_time": "2016-04-29T14:09:00.123456Z",
"revision": 1,
"modified_time: "2016-04-29T14:09:00.123456Z",
"object_marking_refs": ["marking-definition--089a6ecb-cc15-43cc-9494-767639779123"],
"title": "Poison Ivy Malware",
"description": "This file is part of Poison Ivy",
"pattern": "file-object.hashes.md5 = '3773a88f65a5e780c8dff9cdc3a056f3'"
}
],
"marking_definitions": [
{
"type": "marking-definition",
"id": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
"created_time": "2016-02-19T09:11:01Z",
"definition_type": "tlp",
"definition": {
"tlp": "GREEN"
}
}
]
}
Versioning (Excerpt from TLO Common Properties Table)
version (required)
|
number
|
The
version property indicates the version of this object. This field’s value
MUST be an integer (whole number) greater than or equal to 1 and less than or equal to 999,999,999. Higher numbers indicate later versions of the object. Object creators
MUST increase the revision number (SHOULD increment it by exactly 1) when creating a new version of an object.
|
created_time (required)
|
timestamp
|
The
created_time property represents the time at which the first version of this object was created. The object creator
SHOULD use the time it deems most appropriate as the time the object was created.
The
created_time property
SHOULD be the same across all versions of the object unless the created_time was corrected by some version.
|
modified_time (required)
|
timestamp
|
The
modified_time property represents the time that this particular version of the object was created. The object creator
SHOULD use the time it deems most appropriate as the time this version of the object was created. The
modified_time for a given object version
MUST be greater than or equal to the created_time.
|
revoked
(optional)
|
boolean
|
The
revoked property indicates whether the object series has been revoked. Revoked objects are no longer considered
worthwhile intelligence. Revoking an object is permanent; future versions of the object with this
id
MUST NOT be created.
|
version_comment (optional)
|
string
|
A comment outlining why the new version of this object was created.
|
6.4. Versioning
STIX content is versioned using the
version,
version_comment,
revoked,
created_time, and
modified_time properties. See the properties table in section
TODO [add reference] for full definitions and normative usage of the individual properties; this section describes the broader
versioning process and normative rules for performing versioning and revocation.
STIX objects can be versioned in order to update, add, or remove information. All STIX representations of objects are actually representations of a version
of that object, identified in the version field. Higher values in the
version field indicate later versions of the object. STIX Objects have a single object creator: only the entity
that generates the id for the object and creates the first version is permitted to create subsequent versions.
Only the object creator (the entity that generated the id field of the object) is permitted to create new versions
of a STIX object. Producers other than the object creator MUST NOT create new versions of that object.
Individual versions of STIX Objects are immutable: representations of a given version of an object (identified by the object's
id and its
version)
MUST, in all representations, always have the same set of properties and the same values for each property. In order to change the value of any property, or to add or remove properties, the
version number
MUST be increased to indicate a new version.
Objects can also be revoked, which is an indication that they are no longer considered worthwhile intelligence. As with issuing a new version, only the
object creator (the entity that generated the id field of the object) is permitted to create new versions of a
STIX object). A value of true in the
revoked field indicates that an object has been revoked. Revocation is permanent: once an object is marked as revoked,
later versions of that object MUST NOT be created. The change to the revoked field to indicate that an object is revoked is an update to object, and therefore the revoked object
MUST have an updated version and
modified_time.
6.4.1. Versioning Timestamps
Non-Normative Section
There are two timestamps used to indicate when STIX Objects were created and modified:
created_time and
modified_time. The
created_time field indicates the time the first version of the object was created. The
modified_time field indicates the time the current version of the object (indicated by the value of the
version field) was created. For both
created_time and
modified_time, object creators may use any time that best represents when they want to say the object was created
and modified. Some creators might use the time the representation was created in their own database; other creators might use the time the object was first shared externally, and others might use a user-tunable value.
6.4.2. New Version or New Object?
Non-Normative Section
Eventually an implementation will encounter a case where a decision must be made regarding whether a change is a version of an existing object or is different
enough that it is a new object. This is generally considered a data quality problem and therefore this specification does not provide any normative text.
However, to assist implementers and promote consistency across implementations, some rules of thumb are provided. Any time a change indicates a
material change to the meaning of the object (say, a different malware or a different actor), a new object with a different
id should be used. The creator should also think about references to the object when deciding if a change is material.
If the change would invalidate the references to the object, then the change is material and a new object
id should be used.
(examples are snipped for brevity, see original document)
Object Markings (Excerpt from TLO Common Properties Table)
object_marking_refs (optional)
|
list
of type
identifier
|
The list of
marking-definition objects to be applied to this object. When multiple markings of the same type
appear in this list, the markings appearing later have precedence over those appearing earlier.
|
6.5. Object-Level Markings
Data markings provide the ability for producers to convey to consumers how they may use and share the
marked data that they receive. Object-level data markings define how markings are applied to TLOs.
Object-level markings are contained in the
object_marking_refs field, which is an optional list of ID references (of type
identifier) that resolve to objects of type
marking-definition. The markings referenced by the
object_marking_refs field and defined in the
marking-definition object apply to that TLO and all of its fields. If a consumer cannot resolve all
of the ID references contained in the object_marking_refs property the consumer
MUST reject that TLO.
6.5.1. Precedence
Multiple marking definitions of the same type can appear in the
object_marking_refs list. If this occurs, markings appearing later in the list have precedence over those appearing
earlier. For example, a TLP marking appearing at position 3 in the list has precedence over a TLP marking appearing at position 2, but not a copyright marking appearing at position 1. Different types of marking definitions will have different behaviors when
multiple instances are applied; that behavior is defined in the marking definition type itself.
The marking definition extensions, which define how data is marked using a particular approach (e.g., TLP), define the behavior when one marking overrides another.
6.5.2. Interoperability
Producers
MAY create object-level data markings. Producers MUST ensure that all markings they do create comply with the functional and data marking requirements defined in this document.
Consumers
MUST be aware of object-level data markings contained in the object_marking_refs field. Consumers that are
unable to comply with the object-level data markings rules defined in this section
MUST reject all TLOs that contain the object_marking_refs field.
6.5.3. Examples
This example marks the indicator with the marking definition referenced by the ID.
{
...
"type": "indicator",
"id": "indicator--089a6ecb-cc15-43cc-9494-767639779235",
"object_marking_refs": ["marking-definition--089a6ecb-cc15-43cc-9494-767639779123"],
...
}