Public code-level APIs

This page describes OpenTAXII’s public code-level APIs.

Overview

OpenTAXII ships with code-level APIs that can be extended by users. Built-in implementations use SQL database as a backend (everything that SQLAlchemy supports).

Additionaly, OpenTAXII supports anychronous notifications and users can attach custom listeners to the specific events.

Custom API implementations

It is possible to attach custom API implementations to OpenTAXII.

Custom API class should inherit base class (opentaxii.persistence.api.OpenTAXIIPersistenceAPI for Persistence API and opentaxii.auth.api.OpenTAXIIAuthAPI for Authentication API) and implement all defined methods.

Class constructor can accept any parameters. These parameters (as well as API class full name) have to be set in OpenTAXII configuration file. See example configuration for exact syntax. OpenTAXII will load the class from the PYTHONPATH and create API instance during server’s start up procedure.

OpenTAXII APIs are documented below.

Custom signal listeners

Users can attach custom listeners for the events OpenTAXII emits. See Signals to find a list of supported signals.

To attach custom signals, specify full module name as a value for hooks field in OpenTAXII configuration file. Note that the module needs to be in OpenTAXII’s PYTHONPATH.

Example of the implementation is provided in OpenTAXII GitHub repo - examples/hooks.py.

Persistence API

Persistence API takes care of all CRUD operations with entities and wraps backend storage layer.

See Configuration page for the details about how to attach custom implementation of Persistence API.

class opentaxii.persistence.api.OpenTAXIIPersistenceAPI

Bases: object

Abstract class that represents OpenTAXII Persistence API.

This class defines required methods that need to exist in a specific Persistence API implementation.

init_app(app)

create_service(service_entity)

Create a service.

NOTE: Additional data management method that is not used in TAXII server logic but only in helper scripts.

Parameters: service_entity (opentaxii.taxii.entities.ServiceEntity) – service entity in question
Returns: updated service entity, with ID field not None
Return type: opentaxii.taxii.entities.ServiceEntity

create_collection(collection_entity)

Create a collection.

NOTE: Additional data management method that is not used in TAXII server logic but only in helper scripts.

Parameters: collection_entity (opentaxii.taxii.entities.CollectionEntity) – collection entity in question
Returns: updated collection entity, with ID field not None
Return type: opentaxii.taxii.entities.CollectionEntity

attach_collection_to_services(collection_id, service_ids)

Attach collection to the services.

NOTE: Additional data management method that is not used in TAXII server logic but only in helper scripts.

Parameters

collection_id (str) – collection entity in question
service_ids (list) – collection entity in question

Returns

updated collection entity, with ID field not None

Return type

opentaxii.taxii.entities.CollectionEntity

get_services(collection_id=None)

Get configured services.

Parameters: collection_id (str) – get only services assigned to collection with provided ID
Returns: list of service entities.
Return type: list of opentaxii.taxii.entities.ServiceEntity

get_collections(service_id=None)

Get the collections. If service_id is provided, return collection attached to a service.

Parameters: service_id (str) – ID of a service in question
Returns: list of collection entities.
Return type: list of opentaxii.taxii.entities.CollectionEntity

get_collection(collection_name, service_id=None)

Get a collection by name and service ID.

Collection name is unique globally, so can be used as a key. Method retrieves collection entity using collection name collection_name and service ID service_id as a composite key.

Parameters

collection_name (str) – a collection name
service_id (str) – ID of a service

Returns

collection entity

Return type

opentaxii.taxii.entities.CollectionEntity

update_collection(collection_entity)

Update collection.

Parameters: collection_entity (opentaxii.taxii.entities.CollectionEntity) – collection entity object
Returns: updated collection entity
Return type: opentaxii.taxii.entities.CollectionEntity

delete_collection(collection_name)

Delete collection.

Parameters: collection_id (int) – id of a collection object

create_inbox_message(inbox_message_entity)

Create an inbox message.

Parameters: inbox_message_entity (opentaxii.taxii.entities.InboxMessageEntity) – inbox message entity in question
Returns: updated inbox message entity
Return type: opentaxii.taxii.entities.InboxMessageEntity

create_content_block(content_block_entity, collection_ids=None, service_id=None)

Create a content block.

Parameters

content_block_entity (opentaxii.taxii.entities.ContentBlockEntity) – content block in question
collection_ids (list) – a list of collection IDs as strings
service_id (str) – ID of an inbox service via which content block was created

Returns

updated content block entity

Return type

opentaxii.taxii.entities.ContentBlockEntity

get_content_blocks_count(collection_id, start_time=None, end_time=None, bindings=None)

Get a count of the content blocks associated with a collection.

Parameters

collection_id (str) – ID fo a collection in question
start_time (datetime) – start of a time frame
end_time (datetime) – end of a time frame
bindings (list) – list of opentaxii.taxii.entities.ContentBindingEntity

Returns

content block count

Return type

int

get_content_blocks(collection_id, start_time=None, end_time=None, bindings=None, offset=0, limit=10)

Get the content blocks associated with a collection.

Parameters

collection_id (str) – ID fo a collection in question
start_time (datetime) – start of a time frame
end_time (datetime) – end of a time frame
bindings (list) – list of opentaxii.taxii.entities.ContentBindingEntity
offset (int) – result set offset
limit (int) – result set max size

Returns

content blocks list

Return type

list of opentaxii.taxii.entities.ContentBlockEntity

create_result_set(result_set_entity)

Create a result set.

Parameters: result_set_entity (opentaxii.taxii.entities.ResultSetEntity) – result set entity in question
Returns: updated result set entity
Return type: opentaxii.taxii.entities.ResultSetEntity

get_result_set(result_set_id)

Get a result set entity by ID.

Parameters: result_set_id (str) – ID of a result set.
Returns: result set entity
Return type: opentaxii.taxii.entities.ResultSetEntity

create_subscription(subscription_entity)

Create a subscription.

Parameters: subscription_entity (opentaxii.taxii.entities.SubscriptionEntity) – subscription entity in question.
Returns: updated subscription entity
Return type: opentaxii.taxii.entities.SubscriptionEntity

get_subscription(subscription_id)

Get a subscription entity by ID.

Parameters: subscription_id (str) – ID of a subscription
Returns: subscription entity
Return type: opentaxii.taxii.entities.SubscriptionEntity

get_subscriptions(service_id)

Get the subscriptions attached to/created via a service.

Parameters: service_id (str) – ID of a service
Returns: list of subscription entities
Return type: list of opentaxii.taxii.entities.SubscriptionEntity

update_subscription(subscription_entity)

Update a subscription status.

Parameters: subscription_entity (opentaxii.taxii.entities.SubscriptionEntity) – subscription entity in question
Returns: updated subscription entity
Return type: opentaxii.taxii.entities.SubscriptionEntity

get_domain(service_id)

Get configured domain needed to create absolute URLs.

Returns None by default.

Parameters: service_id (str) – ID of a service

delete_content_blocks(collection_name, start_time, end_time=None, with_messages=False)

Delete content blocks in a specified collection with timestamp label in a specified time frame.

Parameters

collection_name (str) – collection name
start_time (datetime) – exclusive beginning of a timeframe
end_time (datetime) – inclusive end of a timeframe
with_messages (bool) – delete related inbox messages

class opentaxii.persistence.api.OpenTAXII2PersistenceAPI

Bases: object

Abstract class that represents OpenTAXII Persistence API.

Stub, pending implementation.

static get_next_param(self, kwargs: Dict) → str

Get value for next based on Dict instance.

:param Dict kwargs: The dict to base the next param on

Returns: The value to use as next param
Return type: str

static parse_next_param(next_param: str) → Dict: Parse provided next_param into kwargs to be used to filter stix objects.

get_api_roots() → List[opentaxii.taxii2.entities.ApiRoot]: Parse provided next_param into kwargs to be used to filter stix objects.

get_api_root(api_root_id: str) → Optional[opentaxii.taxii2.entities.ApiRoot]

get_job_and_details(api_root_id: str, job_id: str) → Optional[opentaxii.taxii2.entities.Job]

get_collections(api_root_id: str) → List[opentaxii.taxii2.entities.Collection]

get_collection(api_root_id: str, collection_id_or_alias: str) → Optional[opentaxii.taxii2.entities.Collection]

get_manifest(collection_id: str, limit: Optional[int] = None, added_after: Optional[datetime.datetime] = None, next_kwargs: Optional[Dict] = None, match_id: Optional[List[str]] = None, match_type: Optional[List[str]] = None, match_version: Optional[List[str]] = None, match_spec_version: Optional[List[str]] = None) → Tuple[List[opentaxii.taxii2.entities.ManifestRecord], bool]

get_objects(collection_id: str, limit: Optional[int] = None, added_after: Optional[datetime.datetime] = None, next_kwargs: Optional[Dict] = None, match_id: Optional[List[str]] = None, match_type: Optional[List[str]] = None, match_version: Optional[List[str]] = None, match_spec_version: Optional[List[str]] = None) → Tuple[List[opentaxii.taxii2.entities.STIXObject], bool, Optional[str]]

add_objects(api_root_id: str, collection_id: str, objects: List[Dict]) → opentaxii.taxii2.entities.Job

get_object(collection_id: str, object_id: str, limit: Optional[int] = None, added_after: Optional[datetime.datetime] = None, next_kwargs: Optional[Dict] = None, match_version: Optional[List[str]] = None, match_spec_version: Optional[List[str]] = None) → Tuple[Optional[List[opentaxii.taxii2.entities.STIXObject]], bool, Optional[str]]

Get single object from database.

Should return None when object matching object_id doesn’t exist.

delete_object(collection_id: str, object_id: str, match_version: Optional[List[str]] = None, match_spec_version: Optional[List[str]] = None) → None

get_versions(collection_id: str, object_id: str, limit: Optional[int] = None, added_after: Optional[datetime.datetime] = None, next_kwargs: Optional[Dict] = None, match_spec_version: Optional[List[str]] = None) → Tuple[List[opentaxii.taxii2.entities.VersionRecord], bool]

Get all versions of single object from database.

Should return None when object matching object_id doesn’t exist.

The persistence API is backed by the sqldb api.

class opentaxii.persistence.sqldb.api.SQLDatabaseAPI(db_connection, create_tables=False, **engine_parameters)

Bases: opentaxii.common.sqldb.BaseSQLDatabaseAPI, opentaxii.persistence.api.OpenTAXIIPersistenceAPI

SQL database implementation of OpenTAXII Persistence API.

Implementation will work with any DB supported by SQLAlchemy package.

Note: this implementation ignores context.account and does not have any access rules.

Parameters

db_connection (str) – a string that indicates database dialect and connection arguments that will be passed directly to create_engine() method.
create_tables=False (bool) – if True, tables will be created in the DB.
engine_parameters=None – if defined, these arguments would be passed to sqlalchemy.create_engine

BASEMODEL: alias of sqlalchemy.orm.decl_api.Model

get_services(collection_id=None)

Get configured services.

Parameters: collection_id (str) – get only services assigned to collection with provided ID
Returns: list of service entities.
Return type: list of opentaxii.taxii.entities.ServiceEntity

get_service(service_id)

update_service(obj)

create_service(entity)

Create a service.

NOTE: Additional data management method that is not used in TAXII server logic but only in helper scripts.

Parameters: service_entity (opentaxii.taxii.entities.ServiceEntity) – service entity in question
Returns: updated service entity, with ID field not None
Return type: opentaxii.taxii.entities.ServiceEntity

get_collections(service_id=None)

Get the collections. If service_id is provided, return collection attached to a service.

Parameters: service_id (str) – ID of a service in question
Returns: list of collection entities.
Return type: list of opentaxii.taxii.entities.CollectionEntity

get_collection(name, service_id=None)

Get a collection by name and service ID.

Collection name is unique globally, so can be used as a key. Method retrieves collection entity using collection name collection_name and service ID service_id as a composite key.

Parameters

collection_name (str) – a collection name
service_id (str) – ID of a service

Returns

collection entity

Return type

opentaxii.taxii.entities.CollectionEntity

update_collection(entity)

Update collection.

Parameters: collection_entity (opentaxii.taxii.entities.CollectionEntity) – collection entity object
Returns: updated collection entity
Return type: opentaxii.taxii.entities.CollectionEntity

delete_collection(collection_name)

Delete collection.

Parameters: collection_id (int) – id of a collection object

delete_service(service_id)

get_content_blocks_count(collection_id=None, start_time=None, end_time=None, bindings=None)

Get a count of the content blocks associated with a collection.

Parameters

collection_id (str) – ID fo a collection in question
start_time (datetime) – start of a time frame
end_time (datetime) – end of a time frame
bindings (list) – list of opentaxii.taxii.entities.ContentBindingEntity

Returns

content block count

Return type

int

get_content_blocks(collection_id=None, start_time=None, end_time=None, bindings=None, offset=0, limit=None)

Get the content blocks associated with a collection.

Parameters

collection_id (str) – ID fo a collection in question
start_time (datetime) – start of a time frame
end_time (datetime) – end of a time frame
bindings (list) – list of opentaxii.taxii.entities.ContentBindingEntity
offset (int) – result set offset
limit (int) – result set max size

Returns

content blocks list

Return type

list of opentaxii.taxii.entities.ContentBlockEntity

create_collection(entity)

Create a collection.

NOTE: Additional data management method that is not used in TAXII server logic but only in helper scripts.

Parameters: collection_entity (opentaxii.taxii.entities.CollectionEntity) – collection entity in question
Returns: updated collection entity, with ID field not None
Return type: opentaxii.taxii.entities.CollectionEntity

set_collection_services(collection_id, service_ids)

create_inbox_message(entity)

Create an inbox message.

Parameters: inbox_message_entity (opentaxii.taxii.entities.InboxMessageEntity) – inbox message entity in question
Returns: updated inbox message entity
Return type: opentaxii.taxii.entities.InboxMessageEntity

create_content_block(entity, collection_ids=None, service_id=None)

Create a content block.

Parameters

content_block_entity (opentaxii.taxii.entities.ContentBlockEntity) – content block in question
collection_ids (list) – a list of collection IDs as strings
service_id (str) – ID of an inbox service via which content block was created

Returns

updated content block entity

Return type

opentaxii.taxii.entities.ContentBlockEntity

create_result_set(entity)

Create a result set.

Parameters: result_set_entity (opentaxii.taxii.entities.ResultSetEntity) – result set entity in question
Returns: updated result set entity
Return type: opentaxii.taxii.entities.ResultSetEntity

get_result_set(result_set_id)

Get a result set entity by ID.

Parameters: result_set_id (str) – ID of a result set.
Returns: result set entity
Return type: opentaxii.taxii.entities.ResultSetEntity

get_subscription(subscription_id)

Get a subscription entity by ID.

Parameters: subscription_id (str) – ID of a subscription
Returns: subscription entity
Return type: opentaxii.taxii.entities.SubscriptionEntity

get_subscriptions(service_id)

Get the subscriptions attached to/created via a service.

Parameters: service_id (str) – ID of a service
Returns: list of subscription entities
Return type: list of opentaxii.taxii.entities.SubscriptionEntity

update_subscription(entity)

Update a subscription status.

Parameters: subscription_entity (opentaxii.taxii.entities.SubscriptionEntity) – subscription entity in question
Returns: updated subscription entity
Return type: opentaxii.taxii.entities.SubscriptionEntity

create_subscription(entity)

Create a subscription.

Parameters: subscription_entity (opentaxii.taxii.entities.SubscriptionEntity) – subscription entity in question.
Returns: updated subscription entity
Return type: opentaxii.taxii.entities.SubscriptionEntity

delete_content_blocks(collection_name, start_time, end_time=None, with_messages=False)

Delete content blocks in a specified collection with timestamp label in a specified time frame.

Parameters

collection_name (str) – collection name
start_time (datetime) – exclusive beginning of a timeframe
end_time (datetime) – inclusive end of a timeframe
with_messages (bool) – delete related inbox messages

Authentication API

Authentication API represents an authority for authentication-related queries.

See Configuration page for the details about how to attach custom implementation of Authentication API.

class opentaxii.auth.api.OpenTAXIIAuthAPI

Bases: object

Abstract class that represents OpenTAXII Authentication API.

This class defines required methods that need to exist in a specific Authentication API implementation.

init_app(app)

authenticate(username, password)

Authenticate a user.

Parameters

username (str) – username
password (str) – password

Returns

auth token

Return type

string

get_account(token)

Get account for auth token.

Parameters: token (str) – auth token
Returns: an account entity
Return type: opentaxii.entities.Account

create_account(account, password)

Create an account.

Parameters

username (str) – username
password (str) – password
is_admin (cool) – is a new user admin?

Returns

an account entity

Return type

opentaxii.entities.Account

update_account(obj, password=None)

Update an account.

Parameters

obj (AccountEntity) – an ipdated user entity (old one matched by username)
password (str) – a new password

Returns

an account entity

Return type

opentaxii.entities.Account

get_accounts()

delete_account(username)

The authentication API is backed by the sqldb api.

class opentaxii.auth.sqldb.api.SQLDatabaseAPI(db_connection, create_tables=False, secret=None, token_ttl_secs=None, **engine_parameters)

Bases: opentaxii.common.sqldb.BaseSQLDatabaseAPI, opentaxii.auth.api.OpenTAXIIAuthAPI

Naive SQL database implementation of OpenTAXII Auth API.

Implementation will work with any DB supported by SQLAlchemy package.

Parameters

db_connection (str) – a string that indicates database dialect and connection arguments that will be passed directly to create_engine() method.
create_tables=False (bool) – if True, tables will be created in the DB.
secret (str) – secret string used for token generation
token_ttl_secs (int) – TTL for JWT token, in seconds.
engine_parameters=None – if defined, these arguments would be passed to sqlalchemy.create_engine

BASEMODEL: alias of sqlalchemy.orm.decl_api.Base

authenticate(username, password)

Authenticate a user.

Parameters

username (str) – username
password (str) – password

Returns

auth token

Return type

string

create_account(username, password, is_admin=False)

Create an account.

Parameters

username (str) – username
password (str) – password
is_admin (cool) – is a new user admin?

Returns

an account entity

Return type

opentaxii.entities.Account

get_account(token)

Get account for auth token.

Parameters: token (str) – auth token
Returns: an account entity
Return type: opentaxii.entities.Account

delete_account(username)

get_accounts()

update_account(obj, password=None)

Update an account.

Parameters

obj (AccountEntity) – an ipdated user entity (old one matched by username)
password (str) – a new password

Returns

an account entity

Return type

opentaxii.entities.Account

Signals

Signals provide the ability for the user’s code to receive asynchronous notification for predefined signals.

See Custom signal listeners chapter for the details about how to attach listeners for the signals.

opentaxii.signals.CONTENT_BLOCK_CREATED = Instance of a signal singleton. Signal emitted when new content block is created.: A named generic notification emitter.

opentaxii.signals.INBOX_MESSAGE_CREATED = Instance of a signal singleton. Signal emitted when new inbox message is created.: A named generic notification emitter.

opentaxii.signals.SUBSCRIPTION_CREATED = Instance of a signal singleton. Signal emitted when new subscription is created.: A named generic notification emitter.