cabby package

Submodules

cabby.abstract module

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

Bases: object

Abstract client class.

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

NO_PROXY = 'noproxy'
PROXY_TYPE_CHOICES = ['http', 'https']
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:
set_auth(cert_file=None, key_file=None, username=None, password=None)

Set authentication credentials.

Authentication types can be combined. It is possible to use only SSL authentication, only basic authentication, or basic authentication over SSL.

Parameters:
  • cert_file (str) – a path to SSL certificate file
  • key_file (str) – a path to SSL key file
  • username (str) – basic authentication username
  • password (str) – basic authentication password
set_proxy(proxy_url, proxy_type=None)

Set proxy properties.

Parameters:
  • proxy_url (str) – proxy address formated as an URL or NO_PROXY to force client not to use proxy.
  • proxy_type (str) – one of the values from PROXY_TYPE_CHOICES

cabby.client10 module

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

Bases: cabby.abstract.AbstractClient

Client implementation for TAXII Specification v1.0

Use cabby.create_client() to create client instances.

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_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)

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
Returns:

subscription information response

Return type:

cabby.entities.SubscriptionResponse

Raises:
taxii_version = '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)

Bases: cabby.abstract.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_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, count_only=False, 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.

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)
  • count_only (bool) – ask only for counts and not full content
  • 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, collections_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_version = '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.converters module

cabby.converters.to_collection_entities(collections, version)
cabby.converters.to_collection_entity(collection, version)
cabby.converters.to_content_binding_entities(raw_bindings)
cabby.converters.to_content_binding_entity(raw_binding)
cabby.converters.to_content_block_entity(block)
cabby.converters.to_detailed_service_instance_entity(service)
cabby.converters.to_subscription_entity(subscription, version)
cabby.converters.to_subscription_response_entity(raw_response, version)

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: cabby.entities.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: cabby.entities.Entity

Content Binding entity.

Represents TAXII Content Binding.

Parameters:
  • id (str) – Content Binding ID
  • subtypes (str) – Content Subtypes IDs
class cabby.entities.ContentBlock(content, content_binding, timestamp)

Bases: cabby.entities.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.DetailedServiceInstance(type, version, protocol, address, message_bindings, available=None, message=None)

Bases: cabby.entities.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: cabby.entities.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: cabby.entities.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: cabby.entities.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: cabby.entities.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: cabby.entities.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: cabby.entities.Entity

Subscription Parameters Entity.

Represents TAXII Subscription Parameters.

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

Bases: cabby.entities.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: cabby.exceptions.ClientException

exception cabby.exceptions.ClientException

Bases: exceptions.Exception

exception cabby.exceptions.NoURIProvidedError

Bases: exceptions.ValueError

exception cabby.exceptions.ServiceNotFoundError

Bases: cabby.exceptions.ClientException

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

Bases: cabby.exceptions.ClientException

cabby.exceptions.dict_to_pairs(d)
cabby.exceptions.status_to_message(status)

cabby.utils module

cabby.utils.configure_client_auth(tclient, cert_file=None, key_file=None, username=None, password=None)
cabby.utils.get_utc_now()
cabby.utils.pack_content_binding(content_binding, version)
cabby.utils.pack_content_bindings(content_bindings, version)

Module contents

Cabby, python library for interacting with TAXII servers.

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

Create a client instance (TAXII version specific).

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

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
  • 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 or cabby.Client10