markings

Functions for working with STIX 2 Data Markings.

These high level functions will operate on both object-level markings and granular markings unless otherwise noted in each of the functions.

Note

These functions are also available as methods on SDOs, SROs, and Marking Definitions. The corresponding methods on those classes are identical to these functions except that the obj parameter is omitted.

granular_markings Functions for working with STIX 2.0 granular markings.
object_markings Functions for working with STIX 2.0 object markings.
utils Utility functions for STIX 2.0 data markings.

add_markings(obj, marking, selectors=None)

Append a marking to this object.

Parameters:
  • obj – An SDO or SRO object.
  • marking – identifier or list of marking identifiers that apply to the properties selected by selectors.
  • selectors – string or list of selectors strings relative to the SDO or SRO in which the properties appear.
Raises:

InvalidSelectorError – If selectors fail validation.

Returns:

A new version of the given SDO or SRO with specified markings added.

Note

If selectors is None, operations will be performed on object level markings. Otherwise on granular markings.

clear_markings(obj, selectors=None)

Remove all markings associated with the selectors.

Parameters:
  • obj – An SDO or SRO object.
  • selectors – string or list of selectors strings relative to the SDO or SRO in which the field(s) appear(s).
Raises:
  • InvalidSelectorError – If selectors fail validation.
  • MarkingNotFoundError – If markings to remove are not found on the provided SDO or SRO.
Returns:

A new version of the given SDO or SRO with specified markings cleared.

Note

If selectors is None, operations will be performed on object level markings. Otherwise on granular markings.

get_markings(obj, selectors=None, inherited=False, descendants=False)

Get all markings associated to the field(s) specified by selectors.

Parameters:
  • obj – An SDO or SRO object.
  • selectors – string or list of selectors strings relative to the SDO or SRO in which the properties appear.
  • inherited – If True, include object level markings and granular markings inherited relative to the properties.
  • descendants – If True, include granular markings applied to any children relative to the properties.
Returns:

list – Marking identifiers that matched the selectors expression.

Note

If selectors is None, operation will be performed only on object level markings.

is_marked(obj, marking=None, selectors=None, inherited=False, descendants=False)

Check if field(s) is marked by any marking or by specific marking(s).

Parameters:
  • obj – An SDO or SRO object.
  • marking – identifier or list of marking identifiers that apply to the properties selected by selectors.
  • selectors – string or list of selectors strings relative to the SDO or SRO in which the field(s) appear(s).
  • inherited – If True, include object level markings and granular markings inherited to determine if the properties is/are marked.
  • descendants – If True, include granular markings applied to any children of the given selector to determine if the properties is/are marked.
Returns:

bool

True if selectors is found on internal SDO or SRO collection.

False otherwise.

Note

When a list of marking identifiers is provided, if ANY of the provided marking identifiers match, True is returned.

If selectors is None, operation will be performed only on object level markings.

remove_markings(obj, marking, selectors=None)

Remove a marking from this object.

Parameters:
  • obj – An SDO or SRO object.
  • marking – identifier or list of marking identifiers that apply to the properties selected by selectors.
  • selectors – string or list of selectors strings relative to the SDO or SRO in which the properties appear.
Raises:
  • InvalidSelectorError – If selectors fail validation.
  • MarkingNotFoundError – If markings to remove are not found on the provided SDO or SRO.
Returns:

A new version of the given SDO or SRO with specified markings removed.

Note

If selectors is None, operations will be performed on object level markings. Otherwise on granular markings.

set_markings(obj, marking, selectors=None)

Remove all markings associated with selectors and appends a new granular marking. Refer to clear_markings and add_markings for details.

Parameters:
  • obj – An SDO or SRO object.
  • marking – identifier or list of marking identifiers that apply to the properties selected by selectors.
  • selectors – string or list of selectors strings relative to the SDO or SRO in which the properties appear.
Returns:

A new version of the given SDO or SRO with specified markings removed and new ones added.

Note

If selectors is None, operations will be performed on object level markings. Otherwise on granular markings.