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
- 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
- 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 configured services.
- Parameters
collection_id (str) – get only services assigned to collection with provided ID
- Returns
list of service entities.
- Return type
- 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
- 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 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
- update_collection(collection_entity)
Update collection.
- Parameters
collection_entity (opentaxii.taxii.entities.CollectionEntity) – collection entity object
- Returns
updated collection entity
- Return type
- 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
- 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
- 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
- create_subscription(subscription_entity)
Create a subscription.
- Parameters
subscription_entity (opentaxii.taxii.entities.SubscriptionEntity) – subscription entity in question.
- Returns
updated subscription entity
- Return type
- get_subscription(subscription_id)
Get a subscription entity by ID.
- Parameters
subscription_id (str) – ID of a subscription
- Returns
subscription entity
- Return type
- 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
- 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
- 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
- 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
- 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
- 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 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
- update_collection(entity)
Update collection.
- Parameters
collection_entity (opentaxii.taxii.entities.CollectionEntity) – collection entity object
- Returns
updated collection entity
- Return type
- 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
- 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
- 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
- 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
- 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
- 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
- get_subscription(subscription_id)
Get a subscription entity by ID.
- Parameters
subscription_id (str) – ID of a subscription
- Returns
subscription entity
- Return type
- 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
- update_subscription(entity)
Update a subscription status.
- Parameters
subscription_entity (opentaxii.taxii.entities.SubscriptionEntity) – subscription entity in question
- Returns
updated subscription entity
- Return type
- create_subscription(entity)
Create a subscription.
- Parameters
subscription_entity (opentaxii.taxii.entities.SubscriptionEntity) – subscription entity in question.
- Returns
updated subscription entity
- Return type
- 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.