Cabby API documentation

Module contents

Cabby, python library for interacting with TAXII servers.

cabby.create_client(host=None, port=None, discovery_path=None, use_https=False, discovery_url=None, version='1.1', headers=None)

Create a client instance (TAXII version specific).

host, port, use_https, discovery_path values can be overridden per request with uri argument passed to a client’s method.

Parameters:

  • host (str) – TAXII server hostname

  • port (int) – TAXII server port

  • discovery_path (str) – Discovery Service relative path

  • use_https (bool) – if HTTPS should be used

  • discovery_url (string) – URL to infer host, port, discovery_path, and use_https.

  • version (string) – TAXII version (1.1 or 1.0)

  • headers (dict) – additional headers to pass with TAXII messages

Returns:

client instance

Return type:

cabby.client11.Client11 or cabby.client10.Client10

cabby.abstract module

class cabby.abstract.AbstractClient(host=None, discovery_path=None, port=None, use_https=False, headers=None, timeout=None)

Bases: object

Abstract client class.

This class can not be used directly, use cabby.create_client() to create client instances.

SUPPORTED_SCHEMES = ['http', 'https']
discover_services(uri=None, cache=True)

Discover services advertised by TAXII server.

This method will send discovery request to a service, defined by uri or constructor’s connection parameters.

Parameters:

  • uri (str) – URI path to a specific TAXII service

  • cache (bool) – if discovered services should be cached

Returns:

list of TAXII services

Return type:

list of cabby.entities.DetailedServiceInstance (or cabby.entities.InboxDetailedService)

Raises:
get_services(service_type=None, service_types=None)

Get services advertised by TAXII server.

This method will try to do automatic discovery by calling discover_services().

Parameters:

  • service_type (str) – filter services by specific type. Accepted values are listed in cabby.entities.SERVICE_TYPES

  • service_types (str) – filter services by multiple types. Accepted values are listed in cabby.entities.SERVICE_TYPES

Returns:

list of service instances

Return type:

list of cabby.entities.DetailedServiceInstance (or cabby.entities.InboxDetailedService)

Raises:
prepare_generic_session()

Prepare basic generic session with configured proxies, headers, username/password (if no JWT url configured), cert file, key file and SSL verification flags.

refresh_jwt_token(session=None)

Obtain JWT token using provided JWT session, url, username and password.

set_auth(ca_cert=None, cert_file=None, key_file=None, key_password=None, username=None, password=None, jwt_auth_url=None, verify_ssl=True)

Set authentication credentials.

jwt_auth_url is required for JWT based authentication. If it is not specified but username and password are provided, client will configure Basic authentication.

SSL authentication can be combined with JWT and Basic authentication.

Parameters:

  • ca_cert (str) – a path to CA SSL certificate file

  • cert_file (str) – a path to SSL certificate file

  • key_file (str) – a path to SSL key file

  • username (str) – username, used in basic auth or JWT auth

  • password (str) – password, used in basic auth or JWT auth

  • key_password (str) – same argument as in ssl.SSLContext.load_cert_chain - may be a function to call to get the password for decrypting the private key or string/bytes/bytearray. It will only be called if the private key is encrypted and a password is necessary.

  • jwt_auth_url (str) – URL used to obtain JWT token

  • verify_ssl (bool/str) – set to False to skip checking host’s SSL certificate. Set to True to check certificate against public CAs or set to filepath to check against custom CA bundle.

set_proxies(proxies)

Set proxy properties.

Cause requests to go through a proxy. Must be a dictionary mapping protocol names to URLs of proxies.

Parameters:

proxies (dir) – dictionary mapping protocol names to URLs

taxii_version = None

cabby.client10 module

class cabby.client10.Client10(host=None, discovery_path=None, port=None, use_https=False, headers=None, timeout=None)

Bases: AbstractClient

Client implementation for TAXII Specification v1.0

Use cabby.create_client() to create client instances.

fulfilment(*args, **kwargs)

Not supported in TAXII 1.0

Raises:

cabby.exceptions.NotSupportedError –

get_collections(uri=None)

Get collections from Feed Management Service.

if uri is not provided, client will try to discover services and find Feed Management Service among them.

Parameters:

uri (str) – URI path to a specific Feed Management service

Returns:

list of collections

Return type:

list of cabby.entities.Collection

Raises:
get_content_count(*args, **kwargs)

Not supported in TAXII 1.0

Raises:

cabby.exceptions.NotSupportedError – not supported in TAXII 1.0

get_subscription_status(collection_name, subscription_id=None, uri=None)

Get subscription status from TAXII Feed Management service.

Sends a subscription request with action STATUS. If no subscription_id is provided, server will return the list of all available subscriptions for feed with a name specified in collection_name.

if uri is not provided, client will try to discover services and find Feed Management Service among them.

Parameters:

  • collection_name (str) – target feed name

  • subscription_id (str) – subscription ID (optional)

  • uri (str) – URI path to a specific Collection Management service

Returns:

subscription information response

Return type:

cabby.entities.SubscriptionResponse

Raises:
poll(collection_name, begin_date=None, end_date=None, subscription_id=None, content_bindings=None, uri=None)

Poll content from Polling Service.

if uri is not provided, client will try to discover services and find Polling Service among them.

Parameters:

  • collection_name (str) – feed to poll

  • begin_date (datetime) – ask only for content blocks created after begin_date (exclusive)

  • end_date (datetime) – ask only for content blocks created before end_date (inclusive)

  • subsctiption_id (str) – ID of the existing subscription

  • content_bindings (list) – list of stings or cabby.entities.ContentBinding objects

  • uri (str) – URI path to a specific Inbox Service

Raises:
push(content, content_binding, uri=None, timestamp=None)

Push content into Inbox Service.

if uri is not provided, client will try to discover services and find Inbox Service among them.

Content Binding subtypes and Destionation collections are not supported in TAXII Specification v1.0.

Parameters:

  • content (str) – content to push

  • content_binding (string or cabby.entities.ContentBinding) – content binding for a content

  • timestamp (datetime) – timestamp label of the content block (current UTC time by default)

  • uri (str) – URI path to a specific Inbox Service

Raises:
services_version = 'urn:taxii.mitre.org:services:1.0'
subscribe(collection_name, inbox_service=None, content_bindings=None, uri=None, count_only=False)

Create a subscription.

Sends a subscription request with action SUBSCRIBE.

if uri is not provided, client will try to discover services and find Collection Management Service among them.

Content Binding subtypes are not supported in TAXII Specification v1.0.

Parameters:

  • collection_name (str) – target feed name

  • inbox_service (cabby.entities.InboxService) – Inbox Service that will accept content pushed by TAXII Server in the context of this subscription

  • content_bindings (list) – a list of strings or cabby.entities.ContentBinding entities

  • uri (str) – URI path to a specific Collection Management service

  • count_only (bool) – IGNORED. Count Only is not supported in TAXII 1.0 and added here only for method unification purpose.

Returns:

subscription information response

Return type:

cabby.entities.SubscriptionResponse

Raises:
taxii_binding = 'urn:taxii.mitre.org:message:xml:1.0'
unsubscribe(collection_name, subscription_id, uri=None)

Unsubscribe from a subscription.

Sends a subscription request with action UNSUBSCRIBE. Subscription is identified by collection_name and subscription_id.

if uri is not provided, client will try to discover services and find Collection Management Service among them.

Parameters:

  • collection_name (str) – target feed name

  • subscription_id (str) – subscription ID

  • uri (str) – URI path to a specific TAXII service

Returns:

subscription information response

Return type:

cabby.entities.SubscriptionResponse

Raises:

cabby.client11 module

class cabby.client11.Client11(host=None, discovery_path=None, port=None, use_https=False, headers=None, timeout=None)

Bases: AbstractClient

Client implementation for TAXII Specification v1.1

Use cabby.create_client() to create client instances.

fulfilment(collection_name, result_id, part_number=1, uri=None)

Poll content from Polling Service as a part of fulfilment process.

if uri is not provided, client will try to discover services and find Polling Service among them.

Parameters:

  • collection_name (str) – collection to poll

  • result_id (str) – existing polling Result ID

  • part_number (int) – index number of a part from the result set

  • uri (str) – URI path to a specific Inbox Service

Raises:
get_collections(uri=None)

Get collections from Collection Management Service.

if uri is not provided, client will try to discover services and find Collection Management Service among them.

Parameters:

uri (str) – URI path to a specific Collection Management service

Returns:

list of collections

Return type:

list of cabby.entities.Collection

Raises:
get_content_count(collection_name, begin_date=None, end_date=None, subscription_id=None, inbox_service=None, content_bindings=None, uri=None)

Get content blocks count for a query.

if uri is not provided, client will try to discover services and find Polling Service among them.

If subscription_id provided, arguments content_bindings and inbox_service are ignored.

Parameters:

  • collection_name (str) – collection to poll

  • begin_date (datetime) – ask only for content blocks created after begin_date (exclusive)

  • end_date (datetime) – ask only for content blocks created before end_date (inclusive)

  • subsctiption_id (str) – ID of the existing subscription

  • inbox_service (cabby.entities.InboxService) – Inbox Service that will accept content pushed by TAXII Server in the context of this Poll Request

  • content_bindings (list) – list of stings or cabby.entities.ContentBinding objects

  • uri (str) – URI path to a specific Inbox Service

Raises:
Return type:

cabby.entities.ContentBlockCount

get_subscription_status(collection_name, subscription_id=None, uri=None)

Get subscription status from TAXII Collection Management service.

Sends a subscription request with action STATUS. If no subscription_id is provided, server will return the list of all available subscriptions for a collection with a name specified in collection_name.

if uri is not provided, client will try to discover services and find Collection Management Service among them.

Parameters:

  • collection_name (str) – target collection name

  • subscription_id (str) – subscription ID (optional)

  • uri (str) – URI path to a specific Collection Management service

Returns:

subscription information response

Return type:

cabby.entities.SubscriptionResponse

Raises:
pause_subscription(collection_name, subscription_id, uri=None)

Pause a subscription.

Sends a subscription request with action PAUSE. Subscription is identified by collection_name and subscription_id.

if uri is not provided, client will try to discover services and find Collection Management Service among them.

Parameters:

  • collection_name (str) – target collection name

  • subscription_id (str) – subscription ID

  • uri (str) – URI path to a specific Collection Management service

Returns:

subscription information response

Return type:

cabby.entities.SubscriptionResponse

Raises:
poll(collection_name, begin_date=None, end_date=None, subscription_id=None, inbox_service=None, content_bindings=None, uri=None)

Poll content from Polling Service.

if uri is not provided, client will try to discover services and find Polling Service among them.

If subscription_id provided, arguments content_bindings and inbox_service are ignored.

Parameters:

  • collection_name (str) – collection to poll

  • begin_date (datetime) – ask only for content blocks created after begin_date (exclusive)

  • end_date (datetime) – ask only for content blocks created before end_date (inclusive)

  • subsctiption_id (str) – ID of the existing subscription

  • inbox_service (cabby.entities.InboxService) – Inbox Service that will accept content pushed by TAXII Server in the context of this Poll Request

  • content_bindings (list) – list of stings or cabby.entities.ContentBinding objects

  • uri (str) – URI path to a specific Inbox Service

Raises:
push(content, content_binding, collection_names=None, timestamp=None, uri=None)

Push content into Inbox Service.

if uri is not provided, client will try to discover services and find Inbox Service among them.

Parameters:

  • content (str) – content to push

  • content_binding (string or cabby.entities.ContentBinding) – content binding for a content

  • collection_names (list) – destination collection names

  • timestamp (datetime) – timestamp label of the content block (current UTC time by default)

  • uri (str) – URI path to a specific Inbox Service

Raises:
resume_subscription(collection_name, subscription_id, uri=None)

Resume a subscription.

Sends a subscription request with action RESUME. Subscription is identified by collection_name and subscription_id.

if uri is not provided, client will try to discover services and find Collection Management Service among them.

Parameters:

  • collection_name (str) – target collection name

  • subscription_id (str) – subscription ID

  • uri (str) – URI path to a specific Collection Management service

Returns:

subscription information response

Return type:

cabby.entities.SubscriptionResponse

Raises:
services_version = 'urn:taxii.mitre.org:services:1.1'
subscribe(collection_name, count_only=False, inbox_service=None, content_bindings=None, uri=None)

Create a subscription.

Sends a subscription request with action SUBSCRIBE.

if uri is not provided, client will try to discover services and find Collection Management Service among them.

Parameters:

  • collection_name (str) – target collection name

  • count_only (bool) – subscribe only to counts and not full content

  • inbox_service (cabby.entities.InboxService) – Inbox Service that will accept content pushed by TAXII Server in the context of this subscription

  • content_bindings (list) – a list of strings or cabby.entities.ContentBinding entities

  • uri (str) – URI path to a specific Collection Management service

Returns:

subscription information response

Return type:

cabby.entities.SubscriptionResponse

Raises:
taxii_binding = 'urn:taxii.mitre.org:message:xml:1.1'
unsubscribe(collection_name, subscription_id, uri=None)

Unsubscribe from a subscription.

Sends a subscription request with action UNSUBSCRIBE. Subscription is identified by collection_name and subscription_id.

if uri is not provided, client will try to discover services and find Collection Management Service among them.

Parameters:

  • collection_name (str) – target collection name

  • subscription_id (str) – subscription ID

  • uri (str) – URI path to a specific TAXII service

Returns:

subscription information response

Return type:

cabby.entities.SubscriptionResponse

Raises:

cabby.entities module

class cabby.entities.Collection(name, description, type='DATA_FEED', available=None, push_methods=None, content_bindings=None, polling_services=None, subscription_methods=None, receiving_inboxes=None, volume=None)

Bases: Entity

Collection entity.

Represents TAXII Collection and TAXII Feed objects.

Parameters:
TYPE_FEED = 'DATA_FEED'
TYPE_SET = 'DATA_SET'
class cabby.entities.ContentBinding(id, subtypes=None)

Bases: Entity

Content Binding entity.

Represents TAXII Content Binding.

Parameters:

  • id (str) – Content Binding ID

  • subtypes (list) – Content Subtypes IDs

class cabby.entities.ContentBlock(content, content_binding, timestamp)

Bases: Entity

Content Block entity.

Represents TAXII Content Block.

Parameters:

  • content (str) – TAXII message payload

  • content_binding (cabby.entities.ContentBinding) – Content Binding

  • timestamp (datetime) – content block timestamp label

class cabby.entities.ContentBlockCount(count, is_partial=False)

Bases: Entity

Content Block count.

Represents an amount of content blocks in a poll query result.

Parameters:

  • count (int) – amount of content blocks in a poll query result.

  • is_partial (bool) – indicates whether the provided Record Count is the exact number of applicable records, or if the provided number is a lower bound and there may be more records than stated.

class cabby.entities.DetailedServiceInstance(type, version, protocol, address, message_bindings, available=None, message=None)

Bases: Entity

Detailed description of a generic TAXII Service instance

Parameters:

  • type (str) – service type. Supported values are in cabby.entities.SERVICE_TYPES

  • version (str) – service version. Supported values are VERSION_10 and VERSION_11

  • protocol (str) – service Protocol Binding value

  • address (str) – service network address

  • message_bindings (list) – service Message Bindings, as list of strings

  • available (bool) – if service is marked as available

  • message (str) – message attached to a service

PROTOCOL_HTTP = 'urn:taxii.mitre.org:protocol:http:1.0'
PROTOCOL_HTTPS = 'urn:taxii.mitre.org:protocol:https:1.0'
VERSION_10 = 'urn:taxii.mitre.org:services:1.0'
VERSION_11 = 'urn:taxii.mitre.org:services:1.1'
class cabby.entities.Entity

Bases: object

Generic entity.

raw = None
class cabby.entities.InboxDetailedService(content_bindings, **kwargs)

Bases: DetailedServiceInstance

Detailed description of TAXII Inbox Service.

Parameters:

  • type (str) – service type. Supported values are in cabby.entities.SERVICE_TYPES

  • version (str) – service version. Supported values are VERSION_10 and VERSION_11

  • protocol (str) – service Protocol Binding value

  • address (str) – service network address

  • message_bindings (list) – service Message Bindings, as list of strings

  • content_bindings (list) – a list of cabby.entities.ContentBinding

  • available (bool) – if service is marked as available

  • message (str) – message attached to a service

class cabby.entities.InboxService(protocol, address, message_bindings, content_bindings=None)

Bases: ServiceInstance

Inbox Service entity.

Represents TAXII Inbox Service.

Parameters:

  • protocol (str) – service Protocol Binding value

  • address (str) – service network address

  • message_bindings (list) – service Message Bindings, as list of strings

  • content_bindings (list) – a list of cabby.entities.ContentBinding

class cabby.entities.PushMethod(protocol, message_bindings)

Bases: Entity

Push Method entity.

Represents TAXII Push Method.

Parameters:

  • protocol (str) – service Protocol Binding value

  • message_bindings (list) – service Message Bindings, as list of strings

class cabby.entities.ServiceInstance(protocol, address, message_bindings)

Bases: Entity

Generic TAXII Service entity.

Parameters:

  • protocol (str) – service Protocol Binding value

  • address (str) – service network address

  • message_bindings (list) – service Message Bindings, as list of strings

class cabby.entities.Subscription(subscription_id, status='UNKNOWN', delivery_parameters=None, subscription_parameters=None, poll_instances=None)

Bases: Entity

Subscription entity.

Parameters:

  • subscription_id (str) – subscription ID

  • status (str) – subscription status. Supported values are STATUS_UNKNOWN, STATUS_ACTIVE, STATUS_PAUSED, STATUS_UNSUBSCRIBED

  • delivery_parameters (list) – a list of cabby.entities.InboxService

  • subscription_parameters (list) – a list of cabby.entities.SubscriptionParameters

  • poll_instances (list) – a list of cabby.entities.ServiceInstance

STATUS_ACTIVE = 'ACTIVE'
STATUS_PAUSED = 'PAUSED'
STATUS_UNKNOWN = 'UNKNOWN'
STATUS_UNSUBSCRIBED = 'UNSUBSCRIBED'
class cabby.entities.SubscriptionParameters(response_type, content_bindings=None)

Bases: Entity

Subscription Parameters Entity.

Represents TAXII Subscription Parameters.

Parameters:
TYPE_COUNT = 'COUNT_ONLY'
TYPE_FULL = 'FULL'
class cabby.entities.SubscriptionResponse(collection_name, message=None, subscriptions=None)

Bases: Entity

Subscription Response entity.

Parameters:

  • collection_name (str) – collection name

  • message (str) – message attached to Subscription Response

  • subscriptions (list) – a list of cabby.entities.Subscription

cabby.exceptions module

exception cabby.exceptions.AmbiguousServicesError

Bases: ClientException

exception cabby.exceptions.ClientException

Bases: Exception

exception cabby.exceptions.HTTPError(status_code)

Bases: ClientException

exception cabby.exceptions.InvalidResponseError

Bases: ClientException

exception cabby.exceptions.NoURIProvidedError

Bases: ValueError

exception cabby.exceptions.NotSupportedError(version, *args, **kwargs)

Bases: ClientException

exception cabby.exceptions.ServiceNotFoundError

Bases: ClientException

exception cabby.exceptions.UnsuccessfulStatusError(taxii_status, *args, **kwargs)

Bases: ClientException