Cabby

Cabby is Python TAXII client implementation from EclecticIQ.

TAXII (Trusted Automated eXchange of Indicator Information) is a collection of specifications defining a set of services and message exchanges used for sharing cyber threat intelligence information between parties. Check TAXII homepage to get more information.

Cabby is designed from the ground up to act as a Python library and as a command line tool, it’s key features are:

  • Rich feature set: supports all TAXII services according to TAXII specification (v1.0 and v1.1).
  • Version agnostic: abstracts specific implementation details and returns version agnostic entities.
  • Stream parsing: heavy TAXII Poll Response messages are parsed on the fly, reducing memory footprint and time until first content block is available.

Documentation contents

Installation guide

Install Python

OpenTAXII works with both latest Python version (3.4) and version 2.7. You can install Python with your operating system’s package manager or download it directly here.

You can verify that Python is installed by typing python from your shell; you should see something like:

$ python
Python 2.7.8 (default, Oct 19 2014, 16:02:00)
[GCC 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.54)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>

Install Cabby

To sandbox the project and protect system-wide python it is recommended to install Cabby into a virtual environment (virtualenv):

Create a virtual environment named venv:

$ virtualenv venv

Where venv is a directory to place the new environment.

Activate this environment:

$ . venv/bin/activate
(venv) $

You can now install the latest Cabby release from the Python Package Index (PyPI) using pip:

(venv) $ pip install cabby

Note

Since Cabby has libtaxii as a dependency, the system libraries libtaxii requires need to be installed. Check libtaxii documentation for the details.

To install Cabby from source files: download a tarball, unpack it and install it manually with python setup.py install.

Versioning

Releases of Cabby are given major.minor.revision version numbers, where major and minor correspond to the roadmap EclecticIQ has. The revision number is used to indicate a bug fix only release.

Next steps

Continue with the User guide to see how to use Cabby.

User guide

This user guide gives an overview of Cabby. It covers:

  • using Cabby as a library
  • using Cabby as a command line tool
  • configuration via environment variables
  • Docker quickstart guide

Note: this document assumes basic familiarity with TAXII specifications. Visit the TAXII homepage for more information about its features.

Using Cabby as a Python library

Below a few examples of how to use the Cabby in your code. We use test server instance hosted by TAXIIstand in examples.

Create a client:

from cabby import create_client

client = create_client(
    'test.taxiistand.com',
    use_https=True,
    discovery_path='/read-write/services/discovery')

Discover advertised services:

services = client.discover_services()
for service in services:
    print('Service type={s.type}, address={s.address}'
          .format(s=service))

Poll content from a collection:

content_blocks = client.poll(collection_name='all-data')

for block in content_blocks:
    print(block.content)

Fetch the collections from Collection Management Serice (or Feed Management Service):

collections = client.get_collections(
    uri='https://test.taxiistand.com/read-write/services/collection-management')

Push content into Inbox Service:

content = '<some>content-text</some>'
binding = 'urn:stix.mitre.org:xml:1.1.1'

client.push(
    content, binding, uri='/read-write/services/inbox/default')

To force client to use TAXII 1.0 specifications, initiate it with a specific version argument value:

from cabby import create_client

client = create_client('open.taxiistand.com', version='1.0')

Note

Cabby client instances configured for TAXII 1.0 or TAXII 1.1 we will have slightly different method signatures (see Cabby API documentation for details).

Authentication methods

It is possible to set authentication parameters for TAXII requests:

from cabby import create_client

client = create_client(
    'secure.taxiiserver.com',
    discovery_path='/services/discovery')

# basic authentication
client.set_auth(username='john', password='p4ssw0rd')

# or JWT based authentication
client.set_auth(
    username='john',
    password='p4ssw0rd',
    jwt_auth_url='/management/auth'
)

# or basic authentication with SSL
client.set_auth(
    username='john',
    password='p4ssw0rd',
    cert_file='/keys/ssl.cert',
    key_file='/keys/ssl.key'
)

# or only SSL authentication
client.set_auth(
    cert_file='/keys/ssl.cert',
    key_file='/keys/ssl.key'
)

Using Cabby as a command line tool

During installation Cabby adds a family of the command line tools prefixed with taxii- to your path:

Discover services:

(venv) $ taxii-discovery \
              --host test.taxiistand.com \
              --path /read-only/services/discovery \
              --https

Fetch the collections list from Collection Management Service:

(venv) $ taxii-collections \
             --path https://test.taxiistand.com/read-only/services/collection-management
Poll content from a collection (Polling Service will be autodiscovered in advertised services).
To get output ready to use in taxii-push, use --dest-dir argument and loop over the output files to push them one-by-one.
(venv) $ $ taxii-poll \
               --host test.taxiistand.com \
               --https --collection single-binding-slow \
               --discovery /read-only/services/discovery

Push content into Inbox Service:

(venv) $ taxii-push \
             --host test.taxiistand.com \
             --https \
             --discovery /read-write/services/discovery \
             --content-file /intel/stix/stuxnet.stix.xml \
             --binding "urn:stix.mitre.org:xml:1.1.1" \
             --subtype custom-subtype

Create a subscription:

(venv) $ taxii-subscription \
             --host test.taxiistand.com \
             --https \
             --path /read-write/services/collection-management \
             --action subscribe \
             --collection collection-A

Fetch the collections from a service protected by Basic authentication:

(venv) $ taxii-collections \
             --path https://test.taxiistand.com/read-write-auth/services/collection-management \
             --username test \
             --password test

Fetch the collections from a service protected by JWT authentication:

(venv) $ taxii-collections \
             --host test.taxiistand.com \
             --https \
             --path /read-write-auth/services/collection-management \
             --username guest \
             --password guest \
             --jwt-auth /management/auth

Copy content blocks from one server to another:

(venv) $ taxii-proxy \
             --poll-path https://open.taxiistand.com/services/poll \
             --poll-collection vxvault \
             --inbox-path https://test.taxiistand.com/read-write/services/inbox-stix \
             --inbox-collection stix-data \
             --binding urn:stix.mitre.org:xml:1.1.1

Use --help to get more usage details.

Configuration via environment variables

  • CABBY_NO_HUGE_TREES: by default Cabby enables support for huge trees in lxml lib (see lxml manual). This disables security restrictions and enables support for very deep trees and very long text content. To disable this, set CABBY_NO_HUGE_TREES environment variable to any value.

Docker Quickstart

To ease the threshold for trying out Cabby, it is possible to use the image provided by EclecticIQ:

$ docker run --rm cabby bash

This will show you some helpful information on what commands are available, and then give you an interactive shell to play around in.

Next steps

See Cabby API documentation.

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: cabby.abstract.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: 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_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: 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 (list) – 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.ContentBlockCount(count, is_partial=False)

Bases: cabby.entities.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: 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_COUNT = '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: Exception

exception cabby.exceptions.HTTPError(status_code)

Bases: cabby.exceptions.ClientException

exception cabby.exceptions.InvalidResponseError

Bases: cabby.exceptions.ClientException

exception cabby.exceptions.NoURIProvidedError

Bases: ValueError

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

Bases: cabby.exceptions.ClientException

exception cabby.exceptions.ServiceNotFoundError

Bases: cabby.exceptions.ClientException

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

Bases: cabby.exceptions.ClientException

Contributing and developing

Reporting issues

Cabby uses Github’s issue tracker. See the Cabby project page on Github.

Obtaining the source code

The Cabby source code can be found on Github. See the Cabby project page on Github.

Layout

The Cabby repository has the following layout:

  • docs/ - used to build the documentation;
  • cabby/ - source code;
  • tests/ - tests.

Compiling from source

After cloning the Github repo, just run:

$ python setup.py install

Running the tests

Almost all Cabby code is covered by the unit tests. Cabby uses py.test and tox for running tests. Type tox -r or py.test to run the unit tests.

Generating the documentation

The documentation is written in ReStructuredText (reST) format and processed using Sphinx. To build HTML documentation, go to docs and type make html.

Next steps

Continue to License.

Changelog

0.1.24 (unreleased)

  • Allow HTTPS authentication with certificates for taxii-proxy

0.1.23 (2020-11-18)

  • Only transparently refresh JWT token when using JWT auth (pr#78)

0.1.22 (2020-11-09)

  • Fix bug where JWT would not be used if client.jwt_token is set directly (pr#76, pr#77)

0.1.21 (2020-11-09)

  • Refresh JWT and retry request once on UNAUTHORIZED status message
  • Add discovery_url argument to create_client function

0.1.20 (2018-03-29)

  • Only include relevant files in release packages.

0.1.19 (2018-03-29)

  • Enable client key passphrase for JWT token authentication request (pr#50)

0.1.18 (2017-06-19)

  • Dependencies upgraded (changes).
  • timeout property that sets HTTP timeout added to the client class and CLI tools (thanks @joarleymoraes).

0.1.17 (2017-04-03)

0.1.16 (2016-10-31)

  • Support for gzipped responses added.

0.1.15 (2016-10-19)

  • Issue with unrecognized TLS key password is fixed.

0.1.14 (2016-10-19)

  • Issue when Cabby was assuming port 80 for HTTPS URLs is fixed.

0.1.13 (2016-10-18)

  • Cabby will always return content block body as bytes.
  • JWT token caching added.
  • Added support for local TLS CA files.
  • --port option in CLI commands gets a higher priority than port extracted from provided --path.
  • Docker file moved to alpine as a base, shaving off 520MB from the total size of the container.

0.1.12 (2016-06-13)

  • fix for incorrect connection error handling issue, that was affecting invalid connections with tls and key password.

0.1.11 (2016-04-27)

  • Documentation fixes.

0.1.10 (2015-12-29)

  • Removing incorrect assumption that auth details are always present.

0.1.9 (2015-12-04)

  • Own implementation of TAXII transport logic added, using Requests library for most of the requests.
  • Added taxii-proxy CLI command to allow funneling of data from one taxii server to another.
  • Various bug fixes.

0.1.7 (2015-09-18)

  • Fix for XML stream parser issue related to a race condition in libxml.

0.1.6 (2015-08-11)

  • Missing dependencies added to setup.py.

0.1.5 (2015-08-10)

  • Added Python 3 compatibility.
  • XML stream parsing for Poll Response messages.
  • Bugfixes.

0.1.4 (2015-07-24)

  • --bindings option added for taxii-poll CLI command.
  • Pagination issue, triggered during processing of paged Poll response, was fixed.
  • CLI datetime parameters have UTC timezone by default.
  • JWT based authentication method added.
  • Multiple naming, style and bug fixes.

0.1.3 (2015-04-08)

  • Workaround for libtaxii issue #186 (wrapping incorrect response in Status Message) has been added.
  • Tests improved.

0.1.2 (2015-03-31)

  • Issue with proxy arguments being ignored is fixed.
  • Issue with poll results print in CLI referencing wrong entity is fixed.
  • Wording and style fixes.

0.1.1 (2015-03-26)

  • Tidying up packaging and distribution related configuration.

0.1.0 (2015-03-26)

  • Initial release.

License

Copyright © 2016, EclecticIQ

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

(This is the OSI approved 3-clause “New BSD License”.)

External links