​4.3​ Granular Markings

Whereas object markings apply to an entire STIX Object or Marking Definition and all its properties, granular markings allow data markings to be applied to individual portions of STIX Objects and Marking Definitions. Granular markings are specified in the granular_markings property, which is a list of granular-marking instances. Each of those instances contains a list of selectors to indicate what is marked and a reference to the marking-definition object to be applied. Granular markings can be used, for example, to indicate that the name property of an indicator should be handled as TLP:GREEN, the description property as TLP:AMBER, and the pattern property as TLP:RED.

​4.3.1​ Granular Marking Type

The granular-marking type defines how the marking-definition object referenced by the marking_ref property applies to a set of content identified by the list of selectors in the selectors property.

​4.3.1.1​ Selector Syntax

Selectors contained in the selectors list are strings that consist of multiple components that MUST be separated by the . character. Each component MUST be one of:

• A property name, e.g., description, or;
• A zero-based list index, specified as a non-negative integer in square brackets, e.g., [4]

Selectors denote path traversals: the root of each selector is the STIX Object that the granular_markings property appears in. Starting from that root, for each component in the selector, properties and list items are traversed. When the complete list has been traversed, the value of the content is considered selected.

Selectors MUST refer to properties or list items that are actually present on the marked object.

As an example, consider the following STIX Object:

{

"id": "vulnerability--ee916c28-c7a4-4d0d-ad56-a8d357f89fef",

"created": "2016-02-14T00:00:00.000Z",

"modified": "2016-02-14T00:00:00.000Z",

"type": "vulnerability",

"name": "CVE-2014-0160",

"description": "The (1) TLS...",

"external_references": [{

"source_name": "cve",

"external_id": "CVE-2014-0160"

}],

"labels": ["heartbleed", "has-logo"]

}

Valid selectors:

• description selects the description property ("The (1) TLS...").
• external_references.[0].source_name selects the source_name property of the first value of the external_references list ("cve").
• labels.[0] selects the first item contained within the labels list ("heartbleed").
• labels selects the list contained in the labels property. Due to the recursive nature of the selector, that includes all items in the list (["heartbleed", "has-logo"]).
• external_references selects the list contained in the external_references property. Due to the recursive nature of the selector, that includes all list items and all properties of those list items.

Invalid selectors:

• pattern and external_references.[3] are invalid selectors because they refer to content not present in that object.
• description.[0] is an invalid selector because the description property is a string and not a list.
• labels.name is an invalid selector because labels property is a list and not an object.

This syntax is inspired by JSONPath [Goessner 2007] and is in fact a strict subset of allowable JSONPath expressions (with the exception that the '$' to indicate the root is implicit). Care should be taken when passing selectors to JSONPath evaluators to ensure that the root of the query is the individual STIX Object. It is expected, however, that selectors can be easily evaluated in programming languages that implement list and key/value mapping types (dictionaries, hashmaps, etc.) without resorting to an external library.

Examples

This example marks the description and labels properties with the single marking definition referenced in the list.

{

...

"granular_markings": [

{

"marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",

"selectors": ["description", "labels"]

}

],

"description": "Some description",

"name": "Some name",

"labels": ["first", "second"]

}