datastore

Python STIX2 DataStore API.

filesystem Python STIX2 FileSystem Source/Sink
filters Filters for Python STIX2 DataSources, DataSinks, DataStores
memory Python STIX2 Memory Source/Sink
taxii Python STIX2 TAXIICollection Source/Sink

exception DataSourceError(message, root_exception=None)

General DataSource error instance, used primarily for wrapping lower level errors

Parameters:
  • message (str) – error message
  • root_exception (Exception) – Exception instance of root exception in the case that DataSourceError is wrapping a lower level or other exception
class CompositeDataSource

Controller for all the attached DataSources.

A user can have a single CompositeDataSource as an interface to a set of DataSources. When an API call is made to the CompositeDataSource, it is delegated to each of the (real) DataSources that are attached to it.

DataSources can be attached to CompositeDataSource for a variety of reasons, e.g. common filters, organization, less API calls.

data_sources

A dictionary of DataSource objects; to be controlled and used by the Data Source Controller object.

Type:list
add_data_source(data_source)

Attach a DataSource to CompositeDataSource instance

Parameters:data_source (DataSource) – a stix2.DataSource to attach to the CompositeDataSource
add_data_sources(data_sources)

Attach list of DataSources to CompositeDataSource instance

Parameters:data_sources (list) – stix2.DataSources to attach to CompositeDataSource
all_versions(stix_id, _composite_filters=None)

Retrieve all versions of a STIX object by STIX ID.

Federated all_versions retrieve method - iterates through all DataSources defined in “data_sources”.

A composite data source will pass its attached filters to each configured data source, pushing filtering to them to handle.

Parameters:
  • stix_id (str) – id of the STIX objects to retrieve.
  • _composite_filters (FilterSet) – a collection of filters passed from a CompositeDataSource (i.e. if this CompositeDataSource is attached to a parent CompositeDataSource), not user supplied.
Returns:

list – The STIX objects that have the specified id.

get(stix_id, _composite_filters=None)

Retrieve STIX object by STIX ID

Federated retrieve method, iterates through all DataSources defined in the “data_sources” parameter. Each data source has a specific API retrieve-like function and associated parameters. This function does a federated retrieval and consolidation of the data returned from all the STIX data sources.

A composite data source will pass its attached filters to each configured data source, pushing filtering to them to handle.

Parameters:
  • stix_id (str) – the id of the STIX object to retrieve.
  • _composite_filters (FilterSet) – a collection of filters passed from a CompositeDataSource (i.e. if this CompositeDataSource is attached to another parent CompositeDataSource), not user supplied.
Returns:

stix_obj – The STIX object to be returned.

get_all_data_sources()
has_data_sources()
query(query=None, _composite_filters=None)

Retrieve STIX objects that match a query.

Federate the query to all DataSources attached to the Composite Data Source.

Parameters:
  • query (list) – list of filters to search on.
  • _composite_filters (FilterSet) – a collection of filters passed from a CompositeDataSource (i.e. if this CompositeDataSource is attached to a parent CompositeDataSource), not user supplied.
Returns:

list – The STIX objects to be returned.

related_to(*args, **kwargs)

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

Only one of source_only and target_only may be True.

Federated related objects method - iterates through all DataSources defined in “data_sources”.

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.

relationships(*args, **kwargs)

Retrieve Relationships involving the given STIX object.

Only one of source_only and target_only may be True.

Federated relationships retrieve method - iterates through all DataSources defined in “data_sources”.

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.

remove_data_source(data_source_id)

Remove DataSource from the CompositeDataSource instance

Parameters:data_source_id (str) – DataSource IDs.
remove_data_sources(data_source_ids)

Remove DataSources from the CompositeDataSource instance

Parameters:data_source_ids (list) – DataSource IDs
class DataSink

An implementer will create a concrete subclass from this class for the specific DataSink.

id

A unique UUIDv4 to identify this DataSink.

Type:str
add(stix_objs)

Method for storing STIX objects.

Implement: Specific data sink API calls, processing, functionality required for adding data to the sink

Parameters:stix_objs (list) – a list of STIX objects (where each object is a STIX object)
class DataSource

An implementer will create a concrete subclass from this class for the specific DataSource.

id

A unique UUIDv4 to identify this DataSource.

Type:str
filters

A collection of filters attached to this DataSource.

Type:FilterSet
all_versions(stix_id)

Implement: Similar to get() except returns list of all object versions of the specified “id”. In addition, implement the specific data source API calls, processing, functionality required for retrieving data from the data source.

Parameters:stix_id (str) – The id of the STIX 2.0 object to retrieve. Should return a list of objects, all the versions of the object specified by the “id”.
Returns:list – All versions of the specified STIX object.
creator_of(obj)

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

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.
get(stix_id)

Implement: Specific data source API calls, processing, functionality required for retrieving data from the data source

Parameters:stix_id (str) – the id of the STIX 2.0 object to retrieve. Should return a single object, the most recent version of the object specified by the “id”.
Returns:stix_obj – The STIX object.
query(query=None)

Implement: The specific data source API calls, processing, functionality required for retrieving query from the data source

Parameters:query (list) – a list of filters (which collectively are the query) to conduct search on.
Returns:list – The STIX objects that matched the query.
related_to(obj, relationship_type=None, source_only=False, target_only=False, filters=None)

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

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.

relationships(obj, relationship_type=None, source_only=False, target_only=False)

Retrieve Relationships involving the given STIX object.

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.

class DataStoreMixin(source=None, sink=None)

Provides mechanisms for storing and retrieving STIX data. The specific behavior can be customized by subclasses.

Parameters:
  • source (DataSource) – An existing DataSource to use as this DataStore’s DataSource component
  • sink (DataSink) – An existing DataSink to use as this DataStore’s DataSink component
id

A unique UUIDv4 to identify this DataStore.

Type:str
source

An object that implements DataSource class.

Type:DataSource
sink

An object that implements DataSink class.

Type:DataSink
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
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.
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.
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”.
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.
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.

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.

make_id()