Public code-level APIs — OpenTAXII 0.1.6 documentation

# 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.

  `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: | 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)

    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.

  `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.