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 repository - 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 the 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)

Get the collections 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)

Get a collection by name and service ID.

According to TAXII spec collection name is unique per service instance. 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
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:
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)

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

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(username, password)

Create an account.

NOTE: Additional method that is only used in the helper scripts shipped with OpenTAXII.

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.