User guide — Cabby 0.1.9 documentation

# User guide

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

- Python library
- command line tool

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.

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.1')

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('test.taxiistand.com', discovery_path='/read-write-auth/services/discovery')

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

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

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

    # only SSL authentication
    client.set_auth(
        cert_file='/tmp/ssl.cert',
        key_file='/tmp/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):

    (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 /tmp/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 test \
                               --password test \
                               --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.

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

        taxii-discovery
        taxii-poll
        taxii-collections
        taxii-push
        taxii-subscription
        taxii-proxy

        e.g. docker run -ti cabby taxii-discovery --host test.taxiistand.com --use-https true --path /read-write/services/discovery

    More information available at: http://cabby.readthedocs.org

    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.