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.0, 1.1, or 2.1)
    • headers (dict) – additional headers to pass with TAXII messages
  • Returns: client instance
  • Return type: cabby.client21.Client21 or 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.

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().

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

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.

get_content_count(*args, **kwargs)

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

cabby.client21 module

HTTPS client for the OASIS TAXII 2.1 Core and Collections APIs.

class cabby.client21.ApiRoot21(client, url)

Bases: object

Core and Collections operations within one selected API root.

add_objects(collection_id, objects)

Submit an envelope or an iterable of STIX dictionaries and return the status resource.

delete_object(collection_id, object_id, *, match=None)

Delete the specified object or versions.

get_collection(collection_id)

get_collections()

get_status(status_id)

info()

manifest_pages(collection_id, **filters)

Yield manifest resources, preserving each entry and custom property.

object_pages(collection_id, object_id=None, **filters)

Yield complete envelopes, optionally for a single object ID.

version_pages(collection_id, object_id, **filters)

Yield versions resources for an object.

class cabby.client21.Client21(discovery_url, *, headers=None, timeout=30)

Bases: object

TAXII 2.1 client bound to the HTTPS origin of a discovery URL.

api_root(url)

Select an absolute HTTPS or server-relative API root on this origin.

close()

discover()

Return the discovery resource, including any advertised API roots.

set_auth(*, username=None, password=None, ca_cert=None, cert_file=None, key_file=None)

Configure HTTP Basic authentication, a trusted CA bundle or a client certificate.

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.

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.

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