utils

Utility functions and classes for the STIX2 library.

class Precision

Timestamp format precisions.

ANY = 1
MILLISECOND = 3
SECOND = 2
class PrecisionConstraint

Timestamp precision constraints. These affect how the Precision values are applied when formatting a timestamp.

These constraints don’t really make sense with the ANY precision, so they have no effect in that case.

EXACT = 1
MIN = 2
class STIXTypeClass

Represents different classes of STIX type.

SCO = 1
SDO = 0
SRO = 2
class STIXdatetime

Bundle a datetime with some format-related metadata, so that JSON serialization has the info it needs to produce compliant timestamps.

deduplicate(stix_obj_list)

Deduplicate a list of STIX objects to a unique set.

Reduces a set of STIX objects to unique set by looking at ‘id’ and ‘modified’ fields - as a unique object version is determined by the combination of those fields

Note: Be aware, as can be seen in the implementation of deduplicate(),that if the “stix_obj_list” argument has multiple STIX objects of the same version, the last object version found in the list will be the one that is returned.

Parameters:stix_obj_list (list) – list of STIX objects (dicts)
Returns:A list with a unique set of the passed list of STIX objects.
detect_spec_version(stix_dict)

Given a dict representing a STIX object, try to detect what spec version it is likely to comply with.

Parameters:stix_dict – A dict with some STIX content. Must at least have a “type” property.
Returns:A STIX version in “X.Y” format
format_datetime(dttm)

Convert a datetime object into a valid STIX timestamp string.

  1. Convert to timezone-aware
  2. Convert to UTC
  3. Format in ISO format
  4. Ensure correct precision a. Add subsecond value if warranted, according to precision settings
  5. Add “Z”
get_class_hierarchy_names(obj)

Given an object, return the names of the class hierarchy.

get_timestamp()

Return a STIX timestamp of the current date and time.

get_type_from_id(stix_id)
is_marking(value, stix_version='2.1')

Determine whether the given object, type, or ID is/is for an marking definition of the given STIX version. If value is a type or ID, this just checks whether the type is “marking-definition”. If a mapping, simple STIX version inference is additionally done on the value, and the result is checked against stix_version. It does not attempt to fully validate the value.

Parameters:
  • value – A STIX object, object ID, or type as a string.
  • stix_version – A STIX version as a string
Returns:

True if the value is/is for a marking definition, False otherwise.
is_object(value, stix_version='2.1')

Determine whether an object, type, or ID is/is for any STIX object. This includes all SDOs, SCOs, meta-objects, and bundle. If value is a type or ID, this just checks whether the type was registered in the given STIX version. If a mapping, simple STIX version inference is additionally done on the value, and the result is checked against stix_version. It does not attempt to fully validate the value.

Parameters:
  • value – A mapping with a “type” property, or a STIX ID or type as a string
  • stix_version – A STIX version as a string
Returns:

True if the type of the given value is a valid STIX type with respect to the given STIX version; False if not
is_sco(value, stix_version='2.1')

Determine whether the given object, type, or ID is/is for an SCO of the given STIX version. If value is a type or ID, this just checks whether the type was registered as an SCO in the given STIX version. If a mapping, simple STIX version inference is additionally done on the value, and the result is checked against stix_version. It does not attempt to fully validate the value.

Parameters:
  • value – A mapping with a “type” property, or a STIX ID or type as a string
  • stix_version – A STIX version as a string
Returns:

True if the type of the given value is an SCO type of the given version; False if not
is_sdo(value, stix_version='2.1')

Determine whether the given object, type, or ID is/is for an SDO of the given STIX version. If value is a type or ID, this just checks whether the type was registered as an SDO in the given STIX version. If a mapping, simple STIX version inference is additionally done on the value, and the result is checked against stix_version. It does not attempt to fully validate the value.

Parameters:
  • value – A mapping with a “type” property, or a STIX ID or type as a string
  • stix_version – A STIX version as a string
Returns:

True if the type of the given value is an SDO type of the given version; False if not
is_sro(value, stix_version='2.1')

Determine whether the given object, type, or ID is/is for an SRO of the given STIX version. If value is a type or ID, this just checks whether the type is “sighting” or “relationship”. If a mapping, simple STIX version inference is additionally done on the value, and the result is checked against stix_version. It does not attempt to fully validate the value.

Parameters:
  • value – A mapping with a “type” property, or a STIX ID or type as a string
  • stix_version – A STIX version as a string
Returns:

True if the type of the given value is an SRO type of the given version; False if not
is_stix_type(value, stix_version='2.1', *types)

Determine whether the type of the given value satisfies the given constraints. ‘types’ must contain STIX types as strings, and/or the STIXTypeClass enum values. STIX types imply an exact match constraint; STIXTypeClass enum values imply a more general constraint, that the object or type be in that class of STIX type. These constraints are implicitly OR’d together.

Parameters:
  • value – A mapping with a “type” property, or a STIX ID or type as a string
  • stix_version – A STIX version as a string
  • types – A sequence of STIX type strings or STIXTypeClass enum values
Returns:

True if the object or type satisfies the constraints; False if not
parse_into_datetime(value, precision=<Precision.ANY: 1>, precision_constraint=<PrecisionConstraint.EXACT: 1>)

Parse a value into a valid STIX timestamp object. Also, optionally adjust precision of fractional seconds. This allows alignment with JSON serialization requirements, and helps ensure we’re not using extra precision which would be lost upon JSON serialization. The precision info will be embedded in the returned object, so that JSON serialization will format it correctly.

Parameters:
  • value – A datetime.datetime or datetime.date instance, or a string
  • precision – A precision value: either an instance of the Precision enum, or a string naming one of the enum values (case-insensitive)
  • precision_constraint – A precision constraint value: either an instance of the PrecisionConstraint enum, or a string naming one of the enum values (case-insensitive)
Returns:

A STIXdatetime instance, which is a datetime but also carries the precision info necessary to properly JSON-serialize it.
to_enum(value, enum_type, enum_default=None)

Detect and convert strings to enums and None to a default enum. This allows use of strings and None in APIs, while enforcing the enum type: if you use a string, it must name a valid enum value. This implementation is case-insensitive.

Parameters:
  • value – A value to be interpreted as an enum (string, Enum instance, or None). If an Enum instance, it must be an instance of enum_type.
  • enum_type – The enum type which strings will be interpreted against
  • enum_default – The default enum to use if value is None. Must be an instance of enum_type, or None. If None, you are disallowing a default and requiring that value be non-None.
Returns:

An instance of enum_type
Raises:
  • TypeError – If value was neither an instance of enum_type, None, nor a string
  • KeyError – If value was a string which couldn’t be interpreted as an enum value from enum_type