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:
-
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 IDservice_id
as a composite key.Parameters: - collection_name (str) – a collection name
- service_id (str) – ID of a service
Returns: collection entity
Return type:
-
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:
-
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:
-
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.