API reference

This reference documents the Python classes, methods, functions, and attributes used by OpenTAXII. For protocol terminology, see the TAXII project and the TAXII 2.1 specification.

Configuration and server

Load configuration, create the Flask application, and access the server interfaces.

config

config

Attributes

Name Description
CONFIG_ENV_VAR
DEFAULT_CONFIG
DEFAULT_CONFIG_NAME
ENV_VAR_PREFIX
current_dir

Classes

Name Description
ServerConfig Class responsible for loading configuration files.
ServerConfig
config.ServerConfig(optional_env_var=CONFIG_ENV_VAR, extra_configs=None)

Class responsible for loading configuration files.

This class will load default configuration file (shipped with OpenTAXII) and apply user specified configuration file on top of default one.

Users can specify custom configuration file (YAML formatted) using enviromental variable. The variable should contain a full path to a custom configuration file.

Parameters
Name Type Description Default
optional_env_var str name of the enviromental variable CONFIG_ENV_VAR
extra_configs list list of additional config filenames None
Attributes
Name Description
ALL_VALID_OPTIONS
VALID_BASE_OPTIONS
VALID_TAXII1_OPTIONS
VALID_TAXII2_OPTIONS
VALID_TAXII_OPTIONS

Functions

Name Description
merge
merge
config.merge(d1, d2)

server.TAXIIServer

server.TAXIIServer(config)

TAXII Server class.

This is the main entrypoint for http requests. It keeps the Auth API manager instance and dispatches requests and error handling to :class:TAXII1Server and :class:TAXII2Server

Attributes

Name Description
AUTH_MANAGER_CLASS
app
auth
config
current_server
real_servers
servers

Methods

Name Description
get_endpoint Get first endpoint matching relative_path.
handle_http_exception Dispatch http exception handling to appropriate taxii* server.
handle_internal_error Dispatch internal error handling to appropriate taxii* server.
handle_request Dispatch request to appropriate taxii* server.
handle_status_exception Dispatch status exception handling to appropriate taxii* server.
handle_validation_exception Dispatch validation exception handling to appropriate taxii* server.
init_app Connect taxii1, taxii2 and auth to flask.
is_basic_auth_supported Check if basic auth is a supported feature.
raise_unauthorized Dispatch unauthorized handling to appropriate taxii* server.
get_endpoint
server.TAXIIServer.get_endpoint(relative_path)

Get first endpoint matching relative_path.

handle_http_exception
server.TAXIIServer.handle_http_exception(error)

Dispatch http exception handling to appropriate taxii* server.

handle_internal_error
server.TAXIIServer.handle_internal_error(error)

Dispatch internal error handling to appropriate taxii* server.

handle_request
server.TAXIIServer.handle_request(relative_path)

Dispatch request to appropriate taxii* server.

handle_status_exception
server.TAXIIServer.handle_status_exception(error)

Dispatch status exception handling to appropriate taxii* server.

handle_validation_exception
server.TAXIIServer.handle_validation_exception(error)

Dispatch validation exception handling to appropriate taxii* server.

init_app
server.TAXIIServer.init_app(app)

Connect taxii1, taxii2 and auth to flask.

is_basic_auth_supported
server.TAXIIServer.is_basic_auth_supported()

Check if basic auth is a supported feature.

raise_unauthorized
server.TAXIIServer.raise_unauthorized()

Dispatch unauthorized handling to appropriate taxii* server.

server.TAXII1Server

server.TAXII1Server(config)

TAXII1 Server class.

This class keeps Presistence API manager instance for TAXII1 and creates TAXII1 Service instances on request.

Parameters

Name Type Description Default
config dict OpenTAXII1 server configuration required

Attributes

Name Description
TYPE_TO_SERVICE
config
persistence

Methods

Name Description
check_allowed_methods
get_domain Get domain either from request handler or config.
get_endpoint Get first endpoint matching relative_path.
get_service Get service by ID.
get_services Get services registered with this TAXII server instance.
get_services_for_collection Get list of services with type service_type, attached
handle_internal_error Handle internal error and return appropriate response.
handle_request Handle request and return appropriate response.
handle_status_exception Handle status exception and return appropriate response.
raise_unauthorized Handle unauthorized access.
check_allowed_methods
server.TAXII1Server.check_allowed_methods()
get_domain
server.TAXII1Server.get_domain(service_id)

Get domain either from request handler or config.

get_endpoint
server.TAXII1Server.get_endpoint(relative_path)

Get first endpoint matching relative_path.

get_service
server.TAXII1Server.get_service(id)

Get service by ID.

Parameters
Name Type Description Default
id str service ID required
Returns
Name Type Description
:py:class:opentaxii.taxii.services.abstract.TAXIIService service with specified ID or None
get_services
server.TAXII1Server.get_services(service_ids=None)

Get services registered with this TAXII server instance.

Parameters
Name Type Description Default
service_ids list list of service IDs (as strings) None
Returns
Name Type Description
list of :py:class:opentaxii.taxii.services.abstract.TAXIIService list of services
get_services_for_collection
server.TAXII1Server.get_services_for_collection(collection, service_type)

Get list of services with type service_type, attached to collection collection.

Parameters
Name Type Description Default
collection opentaxii.taxii.entities.CollectionEntity collection in question required
service_type str service type, supported values are listed as keys in :py:attr:TYPE_TO_SERVICE required
Returns
Name Type Description
list of :py:class:opentaxii.taxii.services.abstract.TAXIIService # noqa list of services
handle_internal_error
server.TAXII1Server.handle_internal_error(error)

Handle internal error and return appropriate response.

handle_request
server.TAXII1Server.handle_request(endpoint)

Handle request and return appropriate response.

Process :class:TAXIIService with either :meth:_process_with_service or :meth:_process_options_request.

handle_status_exception
server.TAXII1Server.handle_status_exception(error)

Handle status exception and return appropriate response.

raise_unauthorized
server.TAXII1Server.raise_unauthorized()

Handle unauthorized access.

server.TAXII2Server

server.TAXII2Server(config)

TAXII2 server class.

Stub, implementation pending.

Attributes

Name Description
config
persistence

Methods

Name Description
api_root_handler
check_allowed_methods
check_authentication Check if account is authenticated, unless endpoint handles that itself.
check_content_length
check_headers
collection_handler
collections_handler
discovery_handler
get_endpoint
handle_http_exception Return JSON instead of HTML for HTTP errors.
handle_request
handle_validation_exception Handle validation exception and return appropriate response.
job_handler
manifest_handler
object_delete_handler
object_get_handler
object_handler
objects_get_handler
objects_handler
objects_post_handler
raise_unauthorized Handle unauthorized access.
versions_handler
api_root_handler
server.TAXII2Server.api_root_handler(api_root_id)
check_allowed_methods
server.TAXII2Server.check_allowed_methods(endpoint)
check_authentication
server.TAXII2Server.check_authentication(endpoint)

Check if account is authenticated, unless endpoint handles that itself.

check_content_length
server.TAXII2Server.check_content_length()
check_headers
server.TAXII2Server.check_headers(endpoint)
collection_handler
server.TAXII2Server.collection_handler(api_root_id, collection_id_or_alias)
collections_handler
server.TAXII2Server.collections_handler(api_root_id)
discovery_handler
server.TAXII2Server.discovery_handler()
get_endpoint
server.TAXII2Server.get_endpoint(relative_path)
handle_http_exception
server.TAXII2Server.handle_http_exception(error)

Return JSON instead of HTML for HTTP errors.

handle_request
server.TAXII2Server.handle_request(endpoint)
handle_validation_exception
server.TAXII2Server.handle_validation_exception(error)

Handle validation exception and return appropriate response.

job_handler
server.TAXII2Server.job_handler(api_root_id, job_id)
manifest_handler
server.TAXII2Server.manifest_handler(api_root_id, collection_id_or_alias)
object_delete_handler
server.TAXII2Server.object_delete_handler(
    api_root_id,
    collection_id_or_alias,
    object_id,
)
object_get_handler
server.TAXII2Server.object_get_handler(
    api_root_id,
    collection_id_or_alias,
    object_id,
)
object_handler
server.TAXII2Server.object_handler(
    api_root_id,
    collection_id_or_alias,
    object_id,
)
objects_get_handler
server.TAXII2Server.objects_get_handler(api_root_id, collection_id_or_alias)
objects_handler
server.TAXII2Server.objects_handler(api_root_id, collection_id_or_alias)
objects_post_handler
server.TAXII2Server.objects_post_handler(api_root_id, collection_id_or_alias)
raise_unauthorized
server.TAXII2Server.raise_unauthorized()

Handle unauthorized access.

versions_handler
server.TAXII2Server.versions_handler(
    api_root_id,
    collection_id_or_alias,
    object_id,
)

entities

entities

Classes

Name Description
Account Represents Account entity.
Account
entities.Account(id, username, permissions, is_admin=False, **details)

Represents Account entity.

This class holds user-specific information and is used for authorization.

The permissions are defined as follow:

  1. key: A collection identifier. For TAXII1 collection, it is a string name while it is a stringified UUID for TAXII2.

  2. value: The permission level. For TAXII1 collection, it is a string with either “read” or “modify” value. However for TAXII2, it is a list with one or both values: “read” and “write”. The reason is that TAXII2 allows to write without read access and vice versa.

Attributes
Name Description
details
id
is_admin
permissions
username

middleware.create_app

middleware.create_app(server)

Create Flask application and attach TAXII server instance server to it.

Parameters

Name Type Description Default
server opentaxii.server.TAXIIServer TAXII server instance required

Returns

Name Type Description
Flask app

TAXII 1 entities and services

Work with TAXII 1 entities and service implementations.

taxii.entities

taxii.entities

Classes

Name Description
CollectionEntity TAXII Collection entity.
ContentBindingEntity TAXII Content Binding entity.
ContentBlockEntity TAXII Content Block entity.
InboxMessageEntity TAXII Inbox Message Entity
PollRequestParametersEntity TAXII Poll Request Parameters entity.
ResultSetEntity TAXII Result Set entity.
ServiceEntity TAXII Service entity.
SubscriptionEntity TAXII Subscription entity.
SubscriptionParameters TAXII Subscription Parameters entity.
CollectionEntity
taxii.entities.CollectionEntity(
    name,
    id=None,
    description=None,
    type=TYPE_FEED,
    volume=None,
    accept_all_content=False,
    supported_content=None,
    available=True,
)

TAXII Collection entity.

Parameters
Name Type Description Default
id str collection id None
name str collection name required
description str description for the collection None
type :attr:TYPE_FEED | :attr:TYPE_SET collection type TYPE_FEED
accept_all_content bool if collection accepts all content types False
supported_content list list of the supported content bindings as a list of :class:ContentBindingEntity instances None
available bool if collection is available True
Attributes
Name Description
TYPE_FEED
TYPE_SET
accept_all_content
available
description
id
name
supported_content
type
volume
Methods
Name Description
can_modify
can_read
get_matching_bindings
is_content_supported

can_modify

taxii.entities.CollectionEntity.can_modify(account)

can_read

taxii.entities.CollectionEntity.can_read(account)

get_matching_bindings

taxii.entities.CollectionEntity.get_matching_bindings(requested_bindings)

is_content_supported

taxii.entities.CollectionEntity.is_content_supported(content_binding)
ContentBindingEntity
taxii.entities.ContentBindingEntity(binding, subtypes=None)

TAXII Content Binding entity.

Parameters
Name Type Description Default
binding str content binding ID required
subtypes list list of subtype ids None
Attributes
Name Description
binding
subtypes
ContentBlockEntity
taxii.entities.ContentBlockEntity(
    content,
    timestamp_label,
    content_binding=None,
    id=None,
    message=None,
    inbox_message_id=None,
)

TAXII Content Block entity.

Parameters
Name Type Description Default
id str content block ID None
content str payload required
timestamp_label datetime content block timestamp required
content_binding ContentBindingEntity content binding None
message str message attached to the content block None
inbox_message_id str internal ID of the inbox message entity None
Attributes
Name Description
content
content_binding
id
inbox_message_id
message
timestamp_label
InboxMessageEntity
taxii.entities.InboxMessageEntity(
    message_id,
    original_message,
    content_block_count,
    service_id,
    id=None,
    result_id=None,
    destination_collections=None,
    record_count=None,
    partial_count=False,
    subscription_collection_name=None,
    subscription_id=None,
    exclusive_begin_timestamp_label=None,
    inclusive_end_timestamp_label=None,
)

TAXII Inbox Message Entity

Parameters
Name Type Description Default
message_id str TAXII message ID required
original_message str XML serialized original TAXII message required
content_block_count int how many content blocks this message contains required
service_id str ID of the Inbox Service that received the message required
id str internal ID of the inbox message entity None
result_id str ID of the Result Set part of which this message delivers None
destination_collections list a list of destination collections, as a list of strings None
record_count int how many items left in the Result Set this message is part of None
partial_count bool if the record count is partial False
subscription_id str ID of a subscription None
subscription_collection_name str collection name of the subscription None
exclusive_begin_timestamp_label datetime subscription’s exclusive begin timestamp label None
inclusive_begin_timestamp_label datetime subscription’s inclusive begin timestamp label required
Attributes
Name Description
content_block_count
destination_collections
exclusive_begin_timestamp_label
id
inclusive_end_timestamp_label
message_id
original_message
partial_count
record_count
result_id
service_id
subscription_collection_name
subscription_id
PollRequestParametersEntity
taxii.entities.PollRequestParametersEntity(
    response_type=SubscriptionParameters.FULL,
    content_bindings=None,
)

TAXII Poll Request Parameters entity.

Note: allow_asynch and delivery_parameters fields are not supported

Parameters
Name Type Description Default
response_type str response type, supported values are :attr:FULL and :attr:COUNT_ONLY SubscriptionParameters.FULL
content_bindings list list of :class:ContentBindingEntity instances None
ResultSetEntity
taxii.entities.ResultSetEntity(
    id,
    collection_id,
    content_bindings=None,
    timeframe=None,
)

TAXII Result Set entity.

Parameters
Name Type Description Default
id str ID of a Result Set required
collection_id str ID of a collection required
content_bindings list list of :class:ContentBindingEntity instances None
timeframe tuple a timeframe of the Result Set in a form of (begin, end) None
Attributes
Name Description
collection_id
content_bindings
id
timeframe
ServiceEntity
taxii.entities.ServiceEntity(type, properties, id=None)

TAXII Service entity.

Parameters
Name Type Description Default
type str service type, supported values are listed as keys in :py:attr:opentaxii.server.TAXIIServer.TYPE_TO_SERVICE required
properties dict a dictionary with service-specific properties required
id str service ID None
Attributes
Name Description
id
properties
type
SubscriptionEntity
taxii.entities.SubscriptionEntity(
    service_id,
    collection_id,
    subscription_id=None,
    status=ACTIVE,
    poll_request_params=None,
)

TAXII Subscription entity.

Parameters
Name Type Description Default
service_id str ID of a service required
collection_id str ID of a collection required
subscription_id str ID of a subscription None
status str subscription status, supported values are: :attr:ACTIVE, :attr:PAUSED, :attr:UNSUBSCRIBED ACTIVE
poll_request_params PollRequestParametersEntity Poll Request Parameters entity None
Attributes
Name Description
ACTIVE
PAUSED
UNSUBSCRIBED
collection_id
params
service_id
status
subscription_id
SubscriptionParameters
taxii.entities.SubscriptionParameters(response_type=FULL, content_bindings=None)

TAXII Subscription Parameters entity.

Note: query formats specification is not supported

Parameters
Name Type Description Default
response_type str response type, supported values are :attr:FULL and :attr:COUNT_ONLY FULL
content_bindings list list of :class:ContentBindingEntity instances None
Attributes
Name Description
COUNT_ONLY
FULL
content_bindings
response_type

Functions

Name Description
deserialize_content_bindings
deserialize_content_bindings
taxii.entities.deserialize_content_bindings(supported_content)

taxii.services.abstract

taxii.services.abstract

Classes

Name Description
TAXIIService Generic TAXII Service class.
TAXIIService
taxii.services.abstract.TAXIIService(
    id,
    server,
    address,
    description=None,
    path=None,
    protocol_bindings=None,
    available=True,
    authentication_required=False,
)

Generic TAXII Service class.

This class implements common methods for all TAXII services.

Parameters
Name Type Description Default
id str service ID required
address str service address as absolute URL required
description str service description None
protocol_bindings list list of supported protocol bindings as a list of strings None
available bool if the service is available True
authentication_required bool if authentication required False
path str relative path if service is configured in the server None
Attributes
Name Description
address
authentication_required
available
description
id
log
path
server
supported_message_bindings
supported_protocol_bindings
Methods
Name Description
generate_id
get_absolute_address
get_message_handler
process
to_service_instances

generate_id

taxii.services.abstract.TAXIIService.generate_id()

get_absolute_address

taxii.services.abstract.TAXIIService.get_absolute_address(binding)

get_message_handler

taxii.services.abstract.TAXIIService.get_message_handler(message)

process

taxii.services.abstract.TAXIIService.process(headers, message)

to_service_instances

taxii.services.abstract.TAXIIService.to_service_instances(version)

taxii.services.discovery

taxii.services.discovery

Classes

Name Description
DiscoveryService
DiscoveryService
taxii.services.discovery.DiscoveryService(services=None, **kwargs)
Attributes
Name Description
advertised_services
handlers
service_type
Methods
Name Description
set_advertised_services

set_advertised_services

taxii.services.discovery.DiscoveryService.set_advertised_services(services)

taxii.services.inbox

taxii.services.inbox

Classes

Name Description
InboxService
InboxService
taxii.services.inbox.InboxService(
    accept_all_content=False,
    destination_collection_required=False,
    supported_content=None,
    **kwargs,
)
Attributes
Name Description
accept_all_content
destination_collection_required
handlers
service_type
supported_content
Methods
Name Description
get_destination_collections
get_supported_content
is_content_supported
to_service_instances
validate_destination_collection_names

get_destination_collections

taxii.services.inbox.InboxService.get_destination_collections()

get_supported_content

taxii.services.inbox.InboxService.get_supported_content(version)

is_content_supported

taxii.services.inbox.InboxService.is_content_supported(
    content_binding,
    version=None,
)

to_service_instances

taxii.services.inbox.InboxService.to_service_instances(version)

validate_destination_collection_names

taxii.services.inbox.InboxService.validate_destination_collection_names(
    name_list,
    in_response_to,
)

taxii.services.poll

taxii.services.poll

Attributes

Name Description
DEFAULT_MAX_RESULT_COUNT
DEFAULT_MAX_RESULT_SIZE
log

Classes

Name Description
PollService
PollService
taxii.services.poll.PollService(
    subscription_required=False,
    max_result_size=-1,
    max_result_count=-1,
    **kwargs,
)
Attributes
Name Description
can_push
handlers
max_result_count
max_result_size
service_type
subscription_required
wait_time
Methods
Name Description
create_result_set
get_collection
get_content_blocks
get_content_blocks_count
get_offset_limit
get_result_set
get_subscription

create_result_set

taxii.services.poll.PollService.create_result_set(
    collection,
    content_bindings=None,
    timeframe=None,
)

get_collection

taxii.services.poll.PollService.get_collection(name)

get_content_blocks

taxii.services.poll.PollService.get_content_blocks(
    collection,
    timeframe=None,
    content_bindings=None,
    part_number=1,
)

get_content_blocks_count

taxii.services.poll.PollService.get_content_blocks_count(
    collection,
    timeframe=None,
    content_bindings=None,
)

get_offset_limit

taxii.services.poll.PollService.get_offset_limit(part_number)

get_result_set

taxii.services.poll.PollService.get_result_set(result_set_id)

get_subscription

taxii.services.poll.PollService.get_subscription(subscription_id)

taxii.services.collection_management

taxii.services.collection_management

Classes

Name Description
CollectionManagementService
CollectionManagementService
taxii.services.collection_management.CollectionManagementService(
    subscription_supported=True,
    subscription_message=None,
    **kwargs,
)
Attributes
Name Description
advertised_collections
handlers
service_type
subscription_handlers
subscription_message
subscription_supported
Methods
Name Description
create_subscription
get_collection
get_polling_services
get_push_methods
get_receiving_inbox_services
get_subscription
get_subscription_services
get_subscriptions
update_subscription

create_subscription

taxii.services.collection_management.CollectionManagementService.create_subscription(
    subscription,
)

get_collection

taxii.services.collection_management.CollectionManagementService.get_collection(
    name,
)

get_polling_services

taxii.services.collection_management.CollectionManagementService.get_polling_services(
    collection,
)

get_push_methods

taxii.services.collection_management.CollectionManagementService.get_push_methods(
    collection,
)

get_receiving_inbox_services

taxii.services.collection_management.CollectionManagementService.get_receiving_inbox_services(
    collection,
)

get_subscription

taxii.services.collection_management.CollectionManagementService.get_subscription(
    subscription_id,
)

get_subscription_services

taxii.services.collection_management.CollectionManagementService.get_subscription_services(
    collection,
)

get_subscriptions

taxii.services.collection_management.CollectionManagementService.get_subscriptions(
)

update_subscription

taxii.services.collection_management.CollectionManagementService.update_subscription(
    subscription,
)

TAXII 2 entities and validation

Work with TAXII 2 resources and request validation.

taxii2.entities

taxii2.entities

Taxii2 entities.

Classes

Name Description
ApiRoot TAXII2 API Root entity.
Collection TAXII2 Collection entity.
Job TAXII2 Job entity, called a “status resource” in taxii2 docs.
JobDetail TAXII2 JobDetail entity, part of “status resource” in taxii2 docs.
JobDetails
ManifestRecord TAXII2 ManifestRecord entity.
STIXObject TAXII2 STIXObject entity.
VersionRecord TAXII2 VersionRecord entity.
ApiRoot
taxii2.entities.ApiRoot(id, default, title, description, is_public)

TAXII2 API Root entity.

Parameters
Name Type Description Default
id uuid.UUID id of this API root required
default bool indicator of default api root, should only be True once required
title str human readable plain text name used to identify this API Root required
description Optional[str] human readable plain text description for this API Root required
is_public bool whether this is a publicly readable API root required
Attributes
Name Description
default
description
id
is_public
title
Collection
taxii2.entities.Collection(
    id,
    api_root_id,
    title,
    description,
    alias,
    is_public,
    is_public_write,
)

TAXII2 Collection entity.

Parameters
Name Type Description Default
id uuid.UUID id of this collection required
api_root_id uuid.UUID id of the :class:ApiRoot this collection belongs to required
title str human readable plain text name used to identify this collection required
description str human readable plain text description for this collection required
alias Optional[str] human readable collection name that can be used on systems to alias a collection id required
is_public bool whether this is a publicly readable collection required
is_public_write bool whether this is a publicly writable collection required
Attributes
Name Description
alias
api_root_id
description
id
is_public
is_public_write
title
Methods
Name Description
can_read Determine if account is allowed to read from this collection.
can_write Determine if account is allowed to write to this collection.

can_read

taxii2.entities.Collection.can_read(account)

Determine if account is allowed to read from this collection.

can_write

taxii2.entities.Collection.can_write(account)

Determine if account is allowed to write to this collection.

Job
taxii2.entities.Job(
    id,
    api_root_id,
    status,
    request_timestamp,
    completed_timestamp=None,
    total_count=0,
    success_count=0,
    failure_count=0,
    pending_count=0,
    details=None,
)

TAXII2 Job entity, called a “status resource” in taxii2 docs.

Parameters
Name Type Description Default
id uuid.UUID id of this job required
api_root_id uuid.UUID id of the :class:ApiRoot this collection belongs to required
status str status of this job required
request_timestamp datetime the datetime of the request that this status resource is monitoring required
completed_timestamp Optional[datetime] the datetime of the completion of this job (used for cleanup) None
total_count int the total number of stix objects in this job 0
success_count int the number of successful stix objects in this job 0
failure_count int the number of failed stix objects in this job 0
pending_count int the number of pending stix objects in this job 0
details Optional[JobDetails] the details per status of this job None
Attributes
Name Description
api_root_id
completed_timestamp
details
failure_count
id
pending_count
request_timestamp
status
success_count
total_count
Methods
Name Description
as_taxii2_dict Turn this object into a taxii2 dict.

as_taxii2_dict

taxii2.entities.Job.as_taxii2_dict()

Turn this object into a taxii2 dict.

JobDetail
taxii2.entities.JobDetail(id, job_id, stix_id, version, message, status)

TAXII2 JobDetail entity, part of “status resource” in taxii2 docs.

Parameters
Name Type Description Default
id uuid.UUID id of this job detail required
job_id uuid.UUID id of the job this detail belongs to required
stix_id str id of the :class:STIXObject this detail tracks required
version datetime the version of this object required
message str message indicating more information about the object being created, its pending state, or why the object failed to be created. required
status str status of this job required
Attributes
Name Description
id
job_id
message
status
stix_id
version
Methods
Name Description
as_taxii2_dict Turn this object into a taxii2 dict.

as_taxii2_dict

taxii2.entities.JobDetail.as_taxii2_dict()

Turn this object into a taxii2 dict.

JobDetails
taxii2.entities.JobDetails()
Attributes
Name Description
failure
pending
success
ManifestRecord
taxii2.entities.ManifestRecord(id, date_added, version, spec_version)

TAXII2 ManifestRecord entity.

This is a cut-down version of :class:STIXObject, for efficiency.

Parameters
Name Type Description Default
id str id of this stix object required
date_added datetime the date and time this object was added required
version datetime the version of this object required
spec_version str stix version this object matches required
Attributes
Name Description
date_added
id
spec_version
version
STIXObject
taxii2.entities.STIXObject(
    id,
    collection_id,
    type,
    spec_version,
    date_added,
    version,
    serialized_data,
)

TAXII2 STIXObject entity.

Parameters
Name Type Description Default
id str id of this stix object required
collection_id uuid.UUID id of the :class:Collection this stix object belongs to required
type str type of this stix object required
spec_version str stix version this object matches required
date_added datetime the date and time this object was added required
version datetime the version of this object required
serialized_data dict the payload of this object required
Attributes
Name Description
collection_id
date_added
id
serialized_data
spec_version
type
version
VersionRecord
taxii2.entities.VersionRecord(date_added, version)

TAXII2 VersionRecord entity.

This is a cut-down version of :class:STIXObject, for efficiency.

Parameters
Name Type Description Default
date_added datetime the date and time this object was added required
version datetime the version of this object required
Attributes
Name Description
date_added
version

taxii2.validation

taxii2.validation

Taxii2 validation functions.

Classes

Name Description
DeleteFilterParamsSchema Schema for the object delete endpoint filters.
ListFilterParamsSchema Schema for the object list endpoint filters.
ObjectFilterParamsSchema Schema for the object endpoint filters.
PersistenceApiMxin Store persistence api on schema instance, to reference in Taxii2Next
Taxii2DateTime Taxii2 formatting compliant datetime field.
Taxii2Filter General taxii2 filter implementation.
Taxii2Next Implemenatation of the taxii2 next query param.
Taxii2VersionFilter Taxii2 compliant version filter.
VersionFilterParamsSchema Schema for the versions endpoint filters.
DeleteFilterParamsSchema
taxii2.validation.DeleteFilterParamsSchema()

Schema for the object delete endpoint filters.

Attributes
Name Description
match_spec_version
match_version
ListFilterParamsSchema
taxii2.validation.ListFilterParamsSchema(persistence_api, *args, **kwargs)

Schema for the object list endpoint filters.

Attributes
Name Description
added_after
limit
match_id
match_spec_version
match_type
match_version
next_kwargs
ObjectFilterParamsSchema
taxii2.validation.ObjectFilterParamsSchema(persistence_api, *args, **kwargs)

Schema for the object endpoint filters.

Attributes
Name Description
added_after
limit
match_spec_version
match_version
next_kwargs
PersistenceApiMxin
taxii2.validation.PersistenceApiMxin(persistence_api, *args, **kwargs)

Store persistence api on schema instance, to reference in Taxii2Next

Attributes
Name Description
persistence_api
Taxii2DateTime
taxii2.validation.Taxii2DateTime()

Taxii2 formatting compliant datetime field.

Attributes
Name Description
DEFAULT_FORMAT
Taxii2Filter
taxii2.validation.Taxii2Filter()

General taxii2 filter implementation.

Taxii2Next
taxii2.validation.Taxii2Next()

Implemenatation of the taxii2 next query param.

Taxii2VersionFilter
taxii2.validation.Taxii2VersionFilter()

Taxii2 compliant version filter.

VersionFilterParamsSchema
taxii2.validation.VersionFilterParamsSchema(persistence_api, *args, **kwargs)

Schema for the versions endpoint filters.

Attributes
Name Description
added_after
limit
match_spec_version
next_kwargs

Functions

Name Description
validate_delete_filter_params Validate and load filter params for the delete endpoint.
validate_envelope Validate if json_data is a valid taxii2 envelope.
validate_list_filter_params Validate and load filter params for the list endpoint.
validate_object_filter_params Validate and load filter params for the object endpoint.
validate_versions_filter_params Validate and load filter params for the versions endpoint.
validate_delete_filter_params
taxii2.validation.validate_delete_filter_params(filter_params)

Validate and load filter params for the delete endpoint.

validate_envelope
taxii2.validation.validate_envelope(json_data, allow_custom=False)

Validate if json_data is a valid taxii2 envelope.

Parameters
Name Type Description Default
json_data Union[str, bytes] the data to check required
allow_custom bool if true, allow non-standard stix types False
validate_list_filter_params
taxii2.validation.validate_list_filter_params(filter_params, persistence_api)

Validate and load filter params for the list endpoint.

validate_object_filter_params
taxii2.validation.validate_object_filter_params(filter_params, persistence_api)

Validate and load filter params for the object endpoint.

validate_versions_filter_params
taxii2.validation.validate_versions_filter_params(
    filter_params,
    persistence_api,
)

Validate and load filter params for the versions endpoint.

Persistence, authentication, and signals

Extend storage and authentication or subscribe to server signals.

persistence.api

persistence.api

Classes

Name Description
OpenTAXII2PersistenceAPI Abstract class that represents OpenTAXII Persistence API.
OpenTAXIIPersistenceAPI Abstract class that represents OpenTAXII Persistence API.
OpenTAXII2PersistenceAPI
persistence.api.OpenTAXII2PersistenceAPI()

Abstract class that represents OpenTAXII Persistence API.

Stub, pending implementation.

Methods
Name Description
add_objects
delete_object
get_api_root
get_api_roots Parse provided next_param into kwargs to be used to filter stix objects.
get_collection
get_collections
get_job_and_details
get_manifest
get_next_param Get value for next based on :class:Dict instance.
get_object Get single object from database.
get_objects
get_versions Get all versions of single object from database.
init_app
parse_next_param Parse provided next_param into kwargs to be used to filter stix objects.

add_objects

persistence.api.OpenTAXII2PersistenceAPI.add_objects(
    api_root_id,
    collection_id,
    objects,
)

delete_object

persistence.api.OpenTAXII2PersistenceAPI.delete_object(
    collection_id,
    object_id,
    match_version=None,
    match_spec_version=None,
)

get_api_root

persistence.api.OpenTAXII2PersistenceAPI.get_api_root(api_root_id)

get_api_roots

persistence.api.OpenTAXII2PersistenceAPI.get_api_roots()

Parse provided next_param into kwargs to be used to filter stix objects.

get_collection

persistence.api.OpenTAXII2PersistenceAPI.get_collection(
    api_root_id,
    collection_id_or_alias,
)

get_collections

persistence.api.OpenTAXII2PersistenceAPI.get_collections(api_root_id)

get_job_and_details

persistence.api.OpenTAXII2PersistenceAPI.get_job_and_details(
    api_root_id,
    job_id,
)

get_manifest

persistence.api.OpenTAXII2PersistenceAPI.get_manifest(
    collection_id,
    limit=None,
    added_after=None,
    next_kwargs=None,
    match_id=None,
    match_type=None,
    match_version=None,
    match_spec_version=None,
)

get_next_param

persistence.api.OpenTAXII2PersistenceAPI.get_next_param(kwargs)

Get value for next based on :class:Dict instance.

Parameters

Name Type Description Default
class:Dict kwargs: The dict to base the next param on required

Returns

Name Type Description
str The value to use as next param

get_object

persistence.api.OpenTAXII2PersistenceAPI.get_object(
    collection_id,
    object_id,
    limit=None,
    added_after=None,
    next_kwargs=None,
    match_version=None,
    match_spec_version=None,
)

Get single object from database.

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

get_objects

persistence.api.OpenTAXII2PersistenceAPI.get_objects(
    collection_id,
    limit=None,
    added_after=None,
    next_kwargs=None,
    match_id=None,
    match_type=None,
    match_version=None,
    match_spec_version=None,
)

get_versions

persistence.api.OpenTAXII2PersistenceAPI.get_versions(
    collection_id,
    object_id,
    limit=None,
    added_after=None,
    next_kwargs=None,
    match_spec_version=None,
)

Get all versions of single object from database.

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

init_app

persistence.api.OpenTAXII2PersistenceAPI.init_app(app)

parse_next_param

persistence.api.OpenTAXII2PersistenceAPI.parse_next_param(next_param)

Parse provided next_param into kwargs to be used to filter stix objects.

OpenTAXIIPersistenceAPI
persistence.api.OpenTAXIIPersistenceAPI()

Abstract class that represents OpenTAXII Persistence API.

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

Methods
Name Description
attach_collection_to_services Attach collection to the services.
create_collection Create a collection.
create_content_block Create a content block.
create_inbox_message Create an inbox message.
create_result_set Create a result set.
create_service Create a service.
create_subscription Create a subscription.
delete_collection Delete collection.
delete_content_blocks Delete content blocks in a specified collection with
delete_service Delete service. To implement in subclass
get_collection Get a collection by name and service ID.
get_collections Get the collections. If service_id is provided, return collection
get_content_blocks Get the content blocks associated with a collection.
get_content_blocks_count Get a count of the content blocks associated with a collection.
get_domain Get configured domain needed to create absolute URLs.
get_result_set Get a result set entity by ID.
get_services Get configured services.
get_subscription Get a subscription entity by ID.
get_subscriptions Get the subscriptions attached to/created via a service.
init_app
set_collection_services Set collection’s services. To implement in subclass
update_collection Update collection.
update_service Update service. To implement in subclass
update_subscription Update a subscription status.

attach_collection_to_services

persistence.api.OpenTAXIIPersistenceAPI.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

Name Type Description Default
collection_id str collection entity in question required
service_ids list collection entity in question required

Returns

Name Type Description
:py:class:opentaxii.taxii.entities.CollectionEntity updated collection entity, with ID field not None

create_collection

persistence.api.OpenTAXIIPersistenceAPI.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

Name Type Description Default
collection_entity opentaxii.taxii.entities.CollectionEntity collection entity in question required

Returns

Name Type Description
:py:class:opentaxii.taxii.entities.CollectionEntity updated collection entity, with ID field not None

create_content_block

persistence.api.OpenTAXIIPersistenceAPI.create_content_block(
    content_block_entity,
    collection_ids=None,
    service_id=None,
)

Create a content block.

Parameters

Name Type Description Default
content_block_entity content block in question required
collection_ids list a list of collection IDs as strings None
service_id str ID of an inbox service via which content block was created None

Returns

Name Type Description
:py:class:opentaxii.taxii.entities.ContentBlockEntity updated content block entity

create_inbox_message

persistence.api.OpenTAXIIPersistenceAPI.create_inbox_message(
    inbox_message_entity,
)

Create an inbox message.

Parameters

Name Type Description Default
inbox_message_entity inbox message entity in question required

Returns

Name Type Description
:py:class:opentaxii.taxii.entities.InboxMessageEntity updated inbox message entity

create_result_set

persistence.api.OpenTAXIIPersistenceAPI.create_result_set(result_set_entity)

Create a result set.

Parameters

Name Type Description Default
result_set_entity opentaxii.taxii.entities.ResultSetEntity result set entity in question required

Returns

Name Type Description
:py:class:opentaxii.taxii.entities.ResultSetEntity updated result set entity

create_service

persistence.api.OpenTAXIIPersistenceAPI.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

Name Type Description Default
service_entity opentaxii.taxii.entities.ServiceEntity service entity in question required

Returns

Name Type Description
:py:class:opentaxii.taxii.entities.ServiceEntity updated service entity, with ID field not None

create_subscription

persistence.api.OpenTAXIIPersistenceAPI.create_subscription(subscription_entity)

Create a subscription.

Parameters

Name Type Description Default
subscription_entity subscription entity in question. required

Returns

Name Type Description
:py:class:opentaxii.taxii.entities.SubscriptionEntity updated subscription entity

delete_collection

persistence.api.OpenTAXIIPersistenceAPI.delete_collection(collection_name)

Delete collection.

Parameters

Name Type Description Default
collection_id int id of a collection object required

delete_content_blocks

persistence.api.OpenTAXIIPersistenceAPI.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

Name Type Description Default
collection_name str collection name required
start_time datetime exclusive beginning of a timeframe required
end_time datetime inclusive end of a timeframe None
with_messages bool delete related inbox messages False

delete_service

persistence.api.OpenTAXIIPersistenceAPI.delete_service(service_id)

Delete service. To implement in subclass

get_collection

persistence.api.OpenTAXIIPersistenceAPI.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

Name Type Description Default
collection_name str a collection name required
service_id str ID of a service None

Returns

Name Type Description
:py:class:opentaxii.taxii.entities.CollectionEntity collection entity

get_collections

persistence.api.OpenTAXIIPersistenceAPI.get_collections(service_id=None)

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

Parameters

Name Type Description Default
service_id str ID of a service in question None

Returns

Name Type Description
list of :py:class:opentaxii.taxii.entities.CollectionEntity list of collection entities.

get_content_blocks

persistence.api.OpenTAXIIPersistenceAPI.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

Name Type Description Default
collection_id str ID fo a collection in question required
start_time datetime start of a time frame None
end_time datetime end of a time frame None
bindings list list of :py:class:opentaxii.taxii.entities.ContentBindingEntity None
offset int result set offset 0
limit int result set max size 10

Returns

Name Type Description
list of :py:class:opentaxii.taxii.entities.ContentBlockEntity content blocks list

get_content_blocks_count

persistence.api.OpenTAXIIPersistenceAPI.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

Name Type Description Default
collection_id str ID fo a collection in question required
start_time datetime start of a time frame None
end_time datetime end of a time frame None
bindings list list of :py:class:opentaxii.taxii.entities.ContentBindingEntity None

Returns

Name Type Description
int content block count

get_domain

persistence.api.OpenTAXIIPersistenceAPI.get_domain(service_id)

Get configured domain needed to create absolute URLs.

Returns None by default.

Parameters

Name Type Description Default
service_id str ID of a service required

get_result_set

persistence.api.OpenTAXIIPersistenceAPI.get_result_set(result_set_id)

Get a result set entity by ID.

Parameters

Name Type Description Default
result_set_id str ID of a result set. required

Returns

Name Type Description
:py:class:opentaxii.taxii.entities.ResultSetEntity result set entity

get_services

persistence.api.OpenTAXIIPersistenceAPI.get_services(collection_id=None)

Get configured services.

Parameters

Name Type Description Default
collection_id str get only services assigned to collection with provided ID None

Returns

Name Type Description
list of :py:class:opentaxii.taxii.entities.ServiceEntity list of service entities.

get_subscription

persistence.api.OpenTAXIIPersistenceAPI.get_subscription(subscription_id)

Get a subscription entity by ID.

Parameters

Name Type Description Default
subscription_id str ID of a subscription required

Returns

Name Type Description
:py:class:opentaxii.taxii.entities.SubscriptionEntity subscription entity

get_subscriptions

persistence.api.OpenTAXIIPersistenceAPI.get_subscriptions(service_id)

Get the subscriptions attached to/created via a service.

Parameters

Name Type Description Default
service_id str ID of a service required

Returns

Name Type Description
list of :py:class:opentaxii.taxii.entities.SubscriptionEntity list of subscription entities

init_app

persistence.api.OpenTAXIIPersistenceAPI.init_app(app)

set_collection_services

persistence.api.OpenTAXIIPersistenceAPI.set_collection_services(
    collection_id,
    service_ids,
)

Set collection’s services. To implement in subclass

update_collection

persistence.api.OpenTAXIIPersistenceAPI.update_collection(collection_entity)

Update collection.

Parameters

Name Type Description Default
collection_entity opentaxii.taxii.entities.CollectionEntity collection entity object required

Returns

Name Type Description
:py:class:opentaxii.taxii.entities.CollectionEntity updated collection entity

update_service

persistence.api.OpenTAXIIPersistenceAPI.update_service(obj)

Update service. To implement in subclass

update_subscription

persistence.api.OpenTAXIIPersistenceAPI.update_subscription(subscription_entity)

Update a subscription status.

Parameters

Name Type Description Default
subscription_entity subscription entity in question required

Returns

Name Type Description
:py:class:opentaxii.taxii.entities.SubscriptionEntity updated subscription entity

persistence.sqldb.api

persistence.sqldb.api

Classes

Name Description
SQLDatabaseAPI SQL database implementation of OpenTAXII Persistence API.
SQLDatabaseAPI
persistence.sqldb.api.SQLDatabaseAPI(
    db_connection,
    create_tables=False,
    **engine_parameters,
)

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
Name Type Description Default
db_connection str a string that indicates database dialect and connection arguments that will be passed directly to :func:~sqlalchemy.engine.create_engine method. required
create_tables=False bool if True, tables will be created in the DB. required
engine_parameters=None if defined, these arguments would be passed to sqlalchemy.create_engine required
Attributes
Name Description
BASEMODEL
Methods
Name Description
create_collection
create_content_block
create_inbox_message
create_result_set
create_service
create_subscription
delete_collection
delete_content_blocks
delete_service
get_collection
get_collections
get_content_blocks
get_content_blocks_count
get_result_set
get_service
get_services
get_subscription
get_subscriptions
set_collection_services
update_collection
update_service
update_subscription

create_collection

persistence.sqldb.api.SQLDatabaseAPI.create_collection(entity)

create_content_block

persistence.sqldb.api.SQLDatabaseAPI.create_content_block(
    entity,
    collection_ids=None,
    service_id=None,
)

create_inbox_message

persistence.sqldb.api.SQLDatabaseAPI.create_inbox_message(entity)

create_result_set

persistence.sqldb.api.SQLDatabaseAPI.create_result_set(entity)

create_service

persistence.sqldb.api.SQLDatabaseAPI.create_service(entity)

create_subscription

persistence.sqldb.api.SQLDatabaseAPI.create_subscription(entity)

delete_collection

persistence.sqldb.api.SQLDatabaseAPI.delete_collection(collection_name)

delete_content_blocks

persistence.sqldb.api.SQLDatabaseAPI.delete_content_blocks(
    collection_name,
    start_time,
    end_time=None,
    with_messages=False,
)

delete_service

persistence.sqldb.api.SQLDatabaseAPI.delete_service(service_id)

get_collection

persistence.sqldb.api.SQLDatabaseAPI.get_collection(name, service_id=None)

get_collections

persistence.sqldb.api.SQLDatabaseAPI.get_collections(service_id=None)

get_content_blocks

persistence.sqldb.api.SQLDatabaseAPI.get_content_blocks(
    collection_id=None,
    start_time=None,
    end_time=None,
    bindings=None,
    offset=0,
    limit=None,
)

get_content_blocks_count

persistence.sqldb.api.SQLDatabaseAPI.get_content_blocks_count(
    collection_id=None,
    start_time=None,
    end_time=None,
    bindings=None,
)

get_result_set

persistence.sqldb.api.SQLDatabaseAPI.get_result_set(result_set_id)

get_service

persistence.sqldb.api.SQLDatabaseAPI.get_service(service_id)

get_services

persistence.sqldb.api.SQLDatabaseAPI.get_services(collection_id=None)

get_subscription

persistence.sqldb.api.SQLDatabaseAPI.get_subscription(subscription_id)

get_subscriptions

persistence.sqldb.api.SQLDatabaseAPI.get_subscriptions(service_id)

set_collection_services

persistence.sqldb.api.SQLDatabaseAPI.set_collection_services(
    collection_id,
    service_ids,
)

update_collection

persistence.sqldb.api.SQLDatabaseAPI.update_collection(entity)

update_service

persistence.sqldb.api.SQLDatabaseAPI.update_service(obj)

update_subscription

persistence.sqldb.api.SQLDatabaseAPI.update_subscription(entity)

auth.api

auth.api

Classes

Name Description
OpenTAXIIAuthAPI Abstract class that represents OpenTAXII Authentication API.
OpenTAXIIAuthAPI
auth.api.OpenTAXIIAuthAPI()

Abstract class that represents OpenTAXII Authentication API.

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

Methods
Name Description
authenticate Authenticate a user.
create_account Create an account.
delete_account
get_account Get account for auth token.
get_accounts
init_app
update_account Update an account.

authenticate

auth.api.OpenTAXIIAuthAPI.authenticate(username, password)

Authenticate a user.

Parameters

Name Type Description Default
username str username required
password str password required

Returns

Name Type Description
str | None auth token

create_account

auth.api.OpenTAXIIAuthAPI.create_account(username, password, is_admin=False)

Create an account.

delete_account

auth.api.OpenTAXIIAuthAPI.delete_account(username)

get_account

auth.api.OpenTAXIIAuthAPI.get_account(token)

Get account for auth token.

Parameters

Name Type Description Default
token str auth token required

get_accounts

auth.api.OpenTAXIIAuthAPI.get_accounts()

init_app

auth.api.OpenTAXIIAuthAPI.init_app(app)

update_account

auth.api.OpenTAXIIAuthAPI.update_account(obj, password=None)

Update an account.

Parameters

Name Type Description Default
obj AccountEntity an ipdated user entity (old one matched by username) required
password str | None a new password None

auth.sqldb.api

auth.sqldb.api

Classes

Name Description
SQLDatabaseAPI
SQLDatabaseAPI
auth.sqldb.api.SQLDatabaseAPI(
    db_connection,
    create_tables=False,
    secret=None,
    token_ttl_secs=None,
    **engine_parameters,
)
Attributes
Name Description
BASEMODEL
secret
token_ttl_secs
Methods
Name Description
authenticate
create_account
delete_account
get_account
get_accounts
update_account

authenticate

auth.sqldb.api.SQLDatabaseAPI.authenticate(username, password)

create_account

auth.sqldb.api.SQLDatabaseAPI.create_account(username, password, is_admin=False)

delete_account

auth.sqldb.api.SQLDatabaseAPI.delete_account(username)

get_account

auth.sqldb.api.SQLDatabaseAPI.get_account(token)

get_accounts

auth.sqldb.api.SQLDatabaseAPI.get_accounts()

update_account

auth.sqldb.api.SQLDatabaseAPI.update_account(obj, password=None)

signals

signals

Attributes

Name Description
CONTENT_BLOCK_CREATED
INBOX_MESSAGE_CREATED
SUBSCRIPTION_CREATED