environment

Python STIX 2.0 Environment API.

class Environment(factory=<stix2.environment.ObjectFactory object>, store=None, source=None, sink=None)

Abstract away some of the nasty details of working with STIX content.

Parameters:
  • factory (ObjectFactory, optional) – Factory for creating objects with common defaults for certain properties.
  • store (DataStore, optional) – Data store providing the source and sink for the environment.
  • source (DataSource, optional) – Source for retrieving STIX objects.
  • sink (DataSink, optional) – Destination for saving STIX objects. Invalid if store is also provided.
get(*args, **kwargs)

Retrieve the most recent version of a single STIX object by ID.

Translate get() call to the appropriate DataSource call.

Parameters:stix_id (str) – the id of the STIX object to retrieve.
Returns:stix_obj
the single most recent version of the STIX
object specified by the “id”.
all_versions(*args, **kwargs)

Retrieve all versions of a single STIX object by ID.

Translate all_versions() call to the appropriate DataSource call.

Parameters:stix_id (str) – the id of the STIX object to retrieve.
Returns:list – All versions of the specified STIX object.
query(*args, **kwargs)

Retrieve STIX objects matching a set of filters.

Translate query() call to the appropriate DataSource call.

Parameters:query (list) – a list of filters (which collectively are the query) to conduct search on.
Returns:list – The STIX objects matching the query.
creator_of(*args, **kwargs)

Retrieve the Identity refered to by the object’s created_by_ref.

Translate creator_of() call to the appropriate DataSource call.

Parameters:obj – The STIX object whose created_by_ref property will be looked up.
Returns:The STIX object’s creator, or None, if the object contains no created_by_ref property or the object’s creator cannot be found.
relationships(*args, **kwargs)

Retrieve Relationships involving the given STIX object.

Translate relationships() call to the appropriate DataSource call.

Only one of source_only and target_only may be True.

Parameters:
  • obj (STIX object OR dict OR str) – The STIX object (or its ID) whose relationships will be looked up.
  • relationship_type (str) – Only retrieve Relationships of this type. If None, all relationships will be returned, regardless of type.
  • source_only (bool) – Only retrieve Relationships for which this object is the source_ref. Default: False.
  • target_only (bool) – Only retrieve Relationships for which this object is the target_ref. Default: False.
Returns:

list – The Relationship objects involving the given STIX object.

related_to(*args, **kwargs)

Retrieve STIX Objects that have a Relationship involving the given STIX object.

Translate related_to() call to the appropriate DataSource call.

Only one of source_only and target_only may be True.

Parameters:
  • obj (STIX object OR dict OR str) – The STIX object (or its ID) whose related objects will be looked up.
  • relationship_type (str) – Only retrieve objects related by this Relationships type. If None, all related objects will be returned, regardless of type.
  • source_only (bool) – Only examine Relationships for which this object is the source_ref. Default: False.
  • target_only (bool) – Only examine Relationships for which this object is the target_ref. Default: False.
  • filters (list) – list of additional filters the related objects must match.
Returns:

list – The STIX objects related to the given STIX object.

add(*args, **kwargs)

Method for storing STIX objects.

Defines custom behavior before storing STIX objects using the appropriate method call on the associated DataSink.

Parameters:stix_objs (list) – a list of STIX objects
add_filter(*args, **kwargs)
add_filters(*args, **kwargs)
create(*args, **kwargs)

Create a STIX object using object factory defaults.

Parameters:
  • cls – the python-stix2 class of the object to be created (eg. Indicator)
  • **kwargs – The property/value pairs of the STIX object to be created
parse(*args, **kwargs)

Convert a string, dict or file-like object into a STIX object.

Parameters:
  • data (str, dict, file-like object) – The STIX 2 content to be parsed.
  • allow_custom (bool) – Whether to allow custom properties as well unknown custom objects. Note that unknown custom objects cannot be parsed into STIX objects, and will be returned as is. Default: False.
  • version (str) – Which STIX2 version to use. (e.g. “2.0”, “2.1”). If None, use latest version.
Returns:

An instantiated Python STIX object.

WARNING: ‘allow_custom=True’ will allow for the return of any supplied STIX
dict(s) that cannot be found to map to any known STIX object types (both STIX2 domain objects or defined custom STIX2 objects); NO validation is done. This is done to allow the processing of possibly unknown custom STIX objects (example scenario: I need to query a third-party TAXII endpoint that could provide custom STIX objects that I dont know about ahead of time)
set_default_created(*args, **kwargs)

Set default value for the created property.

set_default_creator(*args, **kwargs)

Set default value for the created_by_ref property.

set_default_external_refs(*args, **kwargs)

Set default external references.

set_default_object_marking_refs(*args, **kwargs)

Set default object markings.

class ObjectFactory(created_by_ref=None, created=None, external_references=None, object_marking_refs=None, list_append=True)

Easily create STIX objects with default values for certain properties.

Parameters:
  • created_by_ref (optional) – Default created_by_ref value to apply to all objects created by this factory.
  • created (optional) – Default created value to apply to all objects created by this factory.
  • external_references (optional) – Default external_references value to apply to all objects created by this factory.
  • object_marking_refs (optional) – Default object_marking_refs value to apply to all objects created by this factory.
  • list_append (bool, optional) – When a default is set for a list property like external_references or object_marking_refs and a value for that property is passed into create(), if this is set to True, that value will be added to the list alongside the default. If this is set to False, the passed in value will replace the default. Defaults to True.
create(cls, **kwargs)

Create a STIX object using object factory defaults.

Parameters:
  • cls – the python-stix2 class of the object to be created (eg. Indicator)
  • **kwargs – The property/value pairs of the STIX object to be created
set_default_created(created=None)

Set default value for the created property.

set_default_creator(creator=None)

Set default value for the created_by_ref property.

set_default_external_refs(external_references=None)

Set default external references.

set_default_object_marking_refs(object_marking_refs=None)

Set default object markings.