User guide — Cabby 0.1.12a1 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. 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):

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

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