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 :doc:`Cabby API documentation<api>` 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