Cabby Documentation. Release EclecticIQ

Transcription

1 Cabby Documentation Release EclecticIQ Mar 29, 2018

2

3 Contents 1 Installation guide 3 2 User guide 5 3 Cabby API documentation 11 4 Contributing and developing 29 5 Changelog 31 6 License 35 Python Module Index 37 i

4 ii

5 Latest stable release is v (Changelog) 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 Contents 1

6 2 Contents

7 CHAPTER 1 Installation guide 1.1 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 (default, Oct , 16:02:00) [GCC Compatible Apple LLVM 6.0 (clang )] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> 1.2 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: 3

8 (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. 1.3 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. 4 Chapter 1. Installation guide

9 CHAPTER 2 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. 2.1 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: 5

10 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=' 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' ) (continues on next page) 6 Chapter 2. User guide

11 (continued from previous page) # or only SSL authentication client.set_auth( cert_file='/keys/ssl.cert', key_file='/keys/ssl.key' ) 2.2 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 management Poll content from a collection (Polling Service will be autodiscovered in advertised services): (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 management \ (continues on next page) 2.2. Using Cabby as a command line tool 7

12 --username test \ --password test (continued from previous page) 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 \ --poll-collection vxvault \ --inbox-path \ --inbox-collection stix-data \ --binding urn:stix.mitre.org:xml:1.1.1 Use --help to get more usage details. 2.3 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. 2.4 Docker Quickstart To ease the threshold for trying out Cabby, it is possible to use the image provided by EclecticIQ: $ docker run cabby Running this will execute the help script, giving you all the possible options: Commands to be run: e.g. taxii-discovery taxii-poll taxii-collections taxii-push taxii-subscription taxii-proxy $ docker run -ti cabby taxii-discovery \ --host test.taxiistand.com \ --use-https true \ (continues on next page) 8 Chapter 2. User guide

13 --path /read-write/services/discovery (continued from previous page) More information available at: Or you can choose to drop back into a shell by providing `bash` as the command: $ docker run -ti cabby bash Next steps See Cabby API documentation Docker Quickstart 9

14 10 Chapter 2. User guide

15 CHAPTER 3 Cabby API documentation 3.1 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, port, use_https, discovery_path values can be overridden per request with uri argument passed to a client s method. 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.client11 or cabby.client10.client 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. 11

16 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. 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 ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no Discovery servicefound cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services 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(). 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 ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found 12 Chapter 3. Cabby API documentation

17 cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t 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. set_proxies(proxies) Set proxy properties. 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. Cause requests to go through a proxy. Must be a dictionary mapping protocol names to URLs of proxies. 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 Module contents 13

18 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. uri (str) URI path to a specific Feed Management service Returns list of collections Return type list of cabby.entities.collection Raises ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services 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. 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 ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found 14 Chapter 3. Cabby API documentation

19 cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services 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. Raises 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 ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services 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. Raises 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 ValueError if URI provided is invalid or schema is not supported 3.1. Module contents 15

20 cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services 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. 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 ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services taxii_binding = 'urn:taxii.mitre.org:message:xml:1.0' unsubscribe(collection_name, subscription_id, uri=none) Unsubscribe from a subscription. 16 Chapter 3. Cabby API documentation

21 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. 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 ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services 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. Raises 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 ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened 3.1. Module contents 17

22 cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services 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. uri (str) URI path to a specific Collection Management service Returns list of collections Return type list of cabby.entities.collection Raises ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services 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. 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 18 Chapter 3. Cabby API documentation

23 Raises uri (str) URI path to a specific Inbox Service ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services 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. 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 ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no Collection Management service found cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services 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 Module contents 19

24 if uri is not provided, client will try to discover services and find Collection Management Service among them. 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 ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services 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. Raises 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 ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened 20 Chapter 3. Cabby API documentation

25 cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services 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. Raises 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 ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services 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. 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 3.1. Module contents 21

26 Raises ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services 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. 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 ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services taxii_binding = 'urn:taxii.mitre.org:message:xml:1.1' unsubscribe(collection_name, subscription_id, uri=none) Unsubscribe from a subscription. 22 Chapter 3. Cabby API documentation

27 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. 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 ValueError if URI provided is invalid or schema is not supported cabby.exceptions.httperror if HTTP error happened cabby.exceptions.unsuccessfulstatuserror if Status Message received and status_type is not SUCCESS cabby.exceptions.servicenotfounderror if no service found cabby.exceptions.ambiguousserviceserror more than one service with type specified cabby.exceptions.nouriprovidederror no URI provided and client can t discover services 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. name (str) name of the collection description (str) description message type (str) type of a collection. Supported values are TYPE_FEED and TYPE_SET available (bool) if a collection marked as available push_methods (list) availavle push methods for a collection, a list of cabby. entities.pushmethods content_bindings (list) a list of cabby.entities.contentbinding polling_services (list) a list of cabby.entities.serviceinstance subscription_methods (list) a list of cabby.entities. ServiceInstance 3.1. Module contents 23

28 receiving_inboxes (list) a list of cabby.entities.inboxservice volume (int) collection s volume 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. 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. 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. 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 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 24 Chapter 3. Cabby API documentation

29 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: PROTOCOL_HTTPS = 'urn:taxii.mitre.org:protocol: 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. 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. 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 Module contents 25

30 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. 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. 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.subscription poll_instances (list) a list of cabby.entities.serviceinstance STATUS_ACTIVE = 'ACTIVE' STATUS_PAUSED = 'PAUSED' STATUS_UNKNOWN = 'UNKNOWN' STATUS_UNSUBSCRIBED = 'UNSUBSCRIBED' class cabby.entities.subscription(response_type, content_bindings=none) Bases: cabby.entities.entity Subscription Entity. Represents TAXII Subscription. response_type (str) response type. TYPE_COUNTS Supported values are TYPE_FULL and content_bindings (list) a list of cabby.entities.contentbinding TYPE_COUNT = 'COUNT_ONLY' TYPE_FULL = 'FULL' class cabby.entities.subscriptionresponse(collection_name, message=none, subscriptions=none) Bases: cabby.entities.entity 26 Chapter 3. Cabby API documentation

31 Subscription Response entity. 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 3.1. Module contents 27

32 28 Chapter 3. Cabby API documentation

33 CHAPTER 4 Contributing and developing 4.1 Reporting issues Cabby uses Github s issue tracker. See the Cabby project page on Github. 4.2 Obtaining the source code The Cabby source code can be found on Github. See the Cabby project page on Github. 4.3 Layout The Cabby repository has the following layout: docs/ - used to build the documentation; cabby/ - source code; tests/ - tests. 4.4 Compiling from source After cloning the Github repo, just run: $ python setup.py install 29

34 4.5 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. 4.6 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. 30 Chapter 4. Contributing and developing

35 CHAPTER 5 Changelog ( ) Only include relevant files in release packages ( ) Enable client key passphrase for JWT token authentication request (pr#50) ( ) Dependencies upgraded (changes). timeout property that sets HTTP timeout added to the client class and CLI tools ( ) Support for XML huge trees added. It can be disabled with environment variable. See Configuration via environment variables ( ) Support for gzipped responses added. 31

36 ( ) Issue with unrecognized TLS key password is fixed ( ) Issue when Cabby was assuming port 80 for HTTPS URLs is fixed ( ) 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 ( ) fix for incorrect connection error handling issue, that was affecting invalid connections with tls and key password ( ) Documentation fixes ( ) Removing incorrect assumption that auth details are always present ( ) 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 ( ) Fix for XML stream parser issue related to a race condition in libxml. 32 Chapter 5. Changelog

37 ( ) Missing dependencies added to setup.py ( ) Added Python 3 compatibility. XML stream parsing for Poll Response messages. Bugfixes ( ) --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 ( ) Workaround for libtaxii issue #186 (wrapping incorrect response in Status Message) has been added. Tests improved ( ) Issue with proxy arguments being ignored is fixed. Issue with poll results print in CLI referencing wrong entity is fixed. Wording and style fixes ( ) Tidying up packaging and distribution related configuration ( ) Initial release ( ) 33

38 34 Chapter 5. Changelog

39 CHAPTER 6 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, IN- CIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSI- NESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CON- TRACT, 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 DAM- AGE. (This is the OSI approved 3-clause New BSD License.) External links Online documentation (Read the docs) Project page with source code and issue tracker (Github) Python Package Index (PyPI) page with released tarballs 35

40 EclecticIQ 36 Chapter 6. License

41 Python Module Index c cabby, 11 cabby.abstract, 11 cabby.client10, 13 cabby.client11, 17 cabby.entities, 23 cabby.exceptions, 27 37

42 38 Python Module Index

43 Index A AbstractClient (class in cabby.abstract), 11 AmbiguousServicesError, 27 C cabby (module), 11 cabby.abstract (module), 11 cabby.client10 (module), 13 cabby.client11 (module), 17 cabby.entities (module), 23 cabby.exceptions (module), 27 Client10 (class in cabby.client10), 13 Client11 (class in cabby.client11), 17 ClientException, 27 Collection (class in cabby.entities), 23 ContentBinding (class in cabby.entities), 24 ContentBlock (class in cabby.entities), 24 ContentBlockCount (class in cabby.entities), 24 create_client() (in module cabby), 11 D DetailedServiceInstance (class in cabby.entities), 24 discover_services() (cabby.abstract.abstractclient method), 12 E Entity (class in cabby.entities), 25 F fulfilment() (cabby.client10.client10 method), 13 fulfilment() (cabby.client11.client11 method), 17 G get_collections() (cabby.client10.client10 method), 14 get_collections() (cabby.client11.client11 method), 18 get_content_count() (cabby.client10.client10 method), 14 get_content_count() (cabby.client11.client11 method), 18 get_services() (cabby.abstract.abstractclient method), 12 get_subscription_status() (cabby.client10.client10 method), 14 get_subscription_status() (cabby.client11.client11 method), 19 H HTTPError, 27 I InboxDetailedService (class in cabby.entities), 25 InboxService (class in cabby.entities), 25 InvalidResponseError, 27 N NotSupportedError, 27 NoURIProvidedError, 27 P pause_subscription() (cabby.client11.client11 method), 19 poll() (cabby.client10.client10 method), 15 poll() (cabby.client11.client11 method), 20 prepare_generic_session() (cabby.abstract.abstractclient method), 13 PROTOCOL_HTTP (cabby.entities.detailedserviceinstance attribute), 25 PROTOCOL_HTTPS (cabby.entities.detailedserviceinstance attribute), 25 push() (cabby.client10.client10 method), 15 push() (cabby.client11.client11 method), 21 PushMethod (class in cabby.entities), 25 R raw (cabby.entities.entity attribute), 25 refresh_jwt_token() (cabby.abstract.abstractclient method), 13 resume_subscription() (cabby.client11.client11 method), 21 39

44 S ServiceInstance (class in cabby.entities), 26 ServiceNotFoundError, 27 services_version (cabby.client10.client10 attribute), 16 services_version (cabby.client11.client11 attribute), 22 set_auth() (cabby.abstract.abstractclient method), 13 set_proxies() (cabby.abstract.abstractclient method), 13 STATUS_ACTIVE (cabby.entities.subscription attribute), 26 STATUS_PAUSED (cabby.entities.subscription attribute), 26 STATUS_UNKNOWN (cabby.entities.subscription attribute), 26 STATUS_UNSUBSCRIBED (cabby.entities.subscription attribute), 26 subscribe() (cabby.client10.client10 method), 16 subscribe() (cabby.client11.client11 method), 22 Subscription (class in cabby.entities), 26 Subscription (class in cabby.entities), 26 SubscriptionResponse (class in cabby.entities), 26 SUPPORTED_SCHEMES (cabby.abstract.abstractclient attribute), 12 T taxii_binding (cabby.client10.client10 attribute), 16 taxii_binding (cabby.client11.client11 attribute), 22 taxii_version (cabby.abstract.abstractclient attribute), 13 TYPE_COUNT (cabby.entities.subscription attribute), 26 TYPE_FEED (cabby.entities.collection attribute), 24 TYPE_FULL (cabby.entities.subscription attribute), 26 TYPE_SET (cabby.entities.collection attribute), 24 U unsubscribe() (cabby.client10.client10 method), 16 unsubscribe() (cabby.client11.client11 method), 22 UnsuccessfulStatusError, 27 V VERSION_10 (cabby.entities.detailedserviceinstance attribute), 25 VERSION_11 (cabby.entities.detailedserviceinstance attribute), Index