API Reference

This section of documentation contains information on all of the classes and functions in the taxii2client API, as given by the package’s docstrings.

Python TAXII 2.0 Client API

exception taxii2client.AccessError

Bases: taxii2client.TAXIIServiceException

Attempt was made to read/write to a collection when the collection doesn’t allow that operation.

class taxii2client.ApiRoot(url, conn=None, user=None, password=None, verify=True, proxies=None)

Bases: taxii2client._TAXIIEndpoint

Information about a TAXII API Root.

This class corresponds to the Get API Root Information (section 4.2) and Get Collections (section 5.1) endpoints, and contains the information found in the corresponding API Root Resource (section 4.2.1) and Collections Resource (section 5.1.1).

As obtained from a Server, each ApiRoot instance gets its own connection pool(s). Collections returned by instances of this class share the same pools as the instance, so closing one closes all. Also, the same username/password is used to connect to them, as was used for this ApiRoot. If either of these is undesirable, Collection instances may be created manually.

collections
custom_properties
description
get_status(status_id, accept='application/vnd.oasis.taxii+json; version=2.0')
max_content_length
refresh(accept='application/vnd.oasis.taxii+json; version=2.0')

Update the API Root’s information and list of Collections

refresh_collections(accept='application/vnd.oasis.taxii+json; version=2.0')

Update the list of Collections contained by this API Root.

This invokes the Get Collections endpoint.

refresh_information(accept='application/vnd.oasis.taxii+json; version=2.0')

Update the properties of this API Root.

This invokes the Get API Root Information endpoint.

title
versions
class taxii2client.Collection(url, conn=None, user=None, password=None, verify=True, proxies=None, collection_info=None)

Bases: taxii2client._TAXIIEndpoint

Information about a TAXII Collection.

This class represents the Get a Collection endpoint (section 5.2), and contains the information returned in the Collection Resource (section 5.2.1).

Methods on this class can be used to invoke the following endpoints:
  • Get Objects (section 5.3)
  • Add Objects (section 5.4)
  • Get an Object (section 5.5)
  • Get Object Manifests (section 5.6)

As obtained from an ApiRoot, an instance of this class shares connection(s) with all other collections obtained from the same ApiRoot, as well as the ApiRoot instance itself. Closing one will close them all. If this is undesirable, you may manually create Collection instances.

add_objects(bundle, wait_for_completion=True, poll_interval=1, timeout=60, accept='application/vnd.oasis.taxii+json; version=2.0', content_type='application/vnd.oasis.stix+json; version=2.0')

Implement the Add Objects endpoint (section 5.4)

Add objects to the collection. This may be performed either synchronously or asynchronously. To add asynchronously, set wait_for_completion to False. If False, the latter two args are unused. If the caller wishes to monitor the status of the addition, it may do so in its own way. To add synchronously, set wait_for_completion to True, and optionally set the poll and timeout intervals. After initiating the addition, the caller will block, and the TAXII “status” service will be polled until the timeout expires, or the operation completes.

Parameters:
  • bundle – A STIX bundle with the objects to add (string, dict, binary)
  • wait_for_completion (bool) – Whether to wait for the add operation to complete before returning
  • poll_interval (int) – If waiting for completion, how often to poll the status service (seconds)
  • timeout (int) – If waiting for completion, how long to poll until giving up (seconds). Use <= 0 to wait forever
  • accept (str) – media type to include in the Accept: header.
  • content_type (str) – media type to include in the Content-Type: header.
Returns:

If wait_for_completion is False, a Status object corresponding to the initial status data returned from the service, is returned. The status may not yet be complete at this point.

If wait_for_completion is True, a Status object corresponding to the completed operation is returned if it didn’t time out; otherwise a Status object corresponding to the most recent data obtained before the timeout, is returned.
can_read
can_write
custom_properties
description
get_manifest(accept='application/vnd.oasis.taxii+json; version=2.0', **filter_kwargs)

Implement the Get Object Manifests endpoint (section 5.6).

get_object(obj_id, version=None, accept='application/vnd.oasis.stix+json; version=2.0')

Implement the Get an Object endpoint (section 5.5)

get_objects(accept='application/vnd.oasis.stix+json; version=2.0', **filter_kwargs)

Implement the Get Objects endpoint (section 5.3)

id
media_types
objects_url
refresh(accept='application/vnd.oasis.taxii+json; version=2.0')

Update Collection information

title
exception taxii2client.InvalidArgumentsError

Bases: taxii2client.TAXIIServiceException

Invalid arguments were passed to a method.

exception taxii2client.InvalidJSONError

Bases: taxii2client.TAXIIServiceException

A server endpoint gave us invalid JSON

class taxii2client.Server(url, conn=None, user=None, password=None, verify=True, proxies=None)

Bases: taxii2client._TAXIIEndpoint

Information about a server hosting a Discovery service.

This class corresponds to the Server Discovery endpoint (section 4.1) and the Discovery Resource returned from that endpoint (section 4.1.1).

ApiRoot instances obtained from an instance of this class are created with the same username/password as was used in this instance. If that’s incorrect, an ApiRoot instance may be created directly with the desired username and password. Also, they use separate connection pools so that they can be independent: closing one won’t close others, and closing this server object won’t close any of the ApiRoot objects (which may refer to different hosts than was used for discovery).

api_roots
contact
custom_properties
default
description
refresh()

Update the Server information and list of API Roots

title
class taxii2client.Status(url, conn=None, user=None, password=None, verify=True, proxies=None, status_info=None)

Bases: taxii2client._TAXIIEndpoint

TAXII Status Resource.

This class represents the Get Status endpoint (section 4.3) and also contains the information about the Status Resource (section 4.3.1)

custom_properties
refresh(accept='application/vnd.oasis.taxii+json; version=2.0')

Updates Status information

wait_until_final(poll_interval=1, timeout=60)

It will poll the URL to grab the latest status resource in a given timeout and time interval.

Parameters:
  • poll_interval (int) – how often to poll the status service.
  • timeout (int) – how long to poll the URL until giving up. Use <= 0 to wait forever
exception taxii2client.TAXIIServiceException

Bases: Exception

Base class for exceptions raised by this library.

exception taxii2client.ValidationError

Bases: taxii2client.TAXIIServiceException

Data validation failed for a property or group of properties