Version: 1.1.111.dev0

Getting Started

This page gives an introduction to libtaxii and how to use it. Please note that this page is being actively worked on and feedback is welcome.

Modules

The libtaxii library contains the following modules:

  • libtaxii - Contains version info and some methods for getting TAXII Messages from HTTP responses. (Implemented in libtaxii/__init__.py)
  • libtaxii.clients. - TAXII HTTP and HTTPS clients. (Implemented in libtaxii/clients.py)
  • libtaxii.common - Contains functions and classes useful for all versions of TAXII
  • libtaxii.constants - Contains constants for TAXII
  • libtaxii.messages_10 - Creating, handling, and parsing TAXII 1.0 messages. (Implemented in libtaxii/messages_10.py)
  • libtaxii.messages_11 - Creating, handling, and parsing TAXII 1.1 messages. (Implemented in libtaxii/messages_11.py)
  • libtaxii.taxii_default_query - Creating, handling and parsing TAXII Default Queries. (Implemented in libtaxii/taxii_default_query.py) New in libtaxii 1.1.100.
  • libtaxii.validation - Common data validation functions used across libtaxii. (Implemented in libtaxii/validation.py)

TAXII Messages Module Structure

In the TAXII message modules (libtaxii.messages_10 and libtaxii.messages_11), there is a class corresponding to each type of TAXII message. For example, there is a DiscoveryRequest class for the Discovery Request message:

import libtaxii.messages_11 as tm11
discovery_request = tm11.DiscoveryRequest( ... )

For types that can been used across multiple messages (e.g., a Content Block can exist in both Poll Response and Inbox Message), the corresponding class (ContentBlock) is (and always has always been) defined at the module level.

content_block = tm11.ContentBlock( ... )

Other types that are used exclusively within a particular TAXII message type were previously defined as nested classes on the corresponding message class; however, they are now defined at the top level of the module. For example, a Service Instance is only used in a Discovery Response message, so the class representing a Service Instance, now just ServiceInstance, was previously DiscoveryResponse.ServiceInstance. The latter name still works for backward compatibilty reasons, but is deprecated and may be removed in the future.

service_instance = tm11.ServiceInstance( ... )
service_instance = tm11.DiscoveryRequest.ServiceInstance( ... )

See the API Documentation for proper constructor arguments for each type above.

TAXII Message Serialization and Deserialization

Each class in the message modules has serialization and deserialization methods for XML Strings, Python dictionaries, and LXML ElementTrees. All serialization methods (to_*()) are instance methods called on specific objects (e.g., discovery_request.to_xml()). Deserialization methods (from_*()) are class methods and should be called on the class itself (e.g., tm11.DiscoveryRequest.from_xml(xml_string)).

Each class in messages.py defines the following:

  • from_xml(xml_string) - Creates an instance of the class from an XML String.
  • to_xml() - Creates the XML representation of an instance of a class.
  • from_dict(dictionary) - Creates an instance of the class from a Python dictionary.
  • to_dict() - Creates the Python dictionary representation of an instance of a class.
  • from_etree(lxml_etree) - Creates an instance of the class from an LXML Etree.
  • to_etree() - Creates the LXML Etree representation of an instance of a class.

To create a TAXII Message from XML:

xml_string = '<taxii:Discovery_Response ... />'  # Note: Invalid XML
discovery_response = tm11.DiscoveryResponse.from_xml(xml_string)

To create an XML string from a TAXII Message:

new_xml_string = discovery_response.to_xml()

The same approach can be used for Python dictionaries:

msg_dict = { ... }  # Note: Invalid dictionary syntax
discovery_response = tm11.DiscoveryResponse.from_dict(msg_dict)
new_dict = discovery_response.to_dict()

and for LXML ElementTrees:

msg_etree = etree.Element( ... )  # Note: Invalid Element constructor
discovery_response = tm11.DiscoveryResponse.from_etree(msg_etree)
new_etree = discovery_response.to_etree()

Schema Validating TAXII Messages

You can use libtaxii to Schema Validate XML, etree, and file representations of TAXII Messages. XML Schema validation cannot be performed on a TAXII Message Python object, since XML Schema validation can only be performed on XML.

A full code example of XML Schema validation can be found in API Documentation

TAXII Clients

The libtaxii.clients module defines a single class HttpClient capable of invoking TAXII services over both HTTP and HTTPS. The client is a fairly straighforward wrapper around Python’s builtin httplib and supports the use of of both HTTP Basic and TLS Certificate authentication.

Example usage of clients:

import libtaxii as t
import libtaxii.clients as tc
import libtaxii.messages_11 as tm11
from libtaxii.constants import *

client = tc.HttpClient()
client.set_auth_type(tc.HttpClient.AUTH_BASIC)
client.set_use_https(True)
client.set_auth_credentials({'username': 'MyUsername', 'password': 'MyPassword'})

discovery_request = tm11.DiscoveryRequest(tm11.generate_message_id())
discovery_xml = discovery_request.to_xml()

http_resp = client.call_taxii_service2('example.com', '/pollservice/', VID_TAXII_XML_11, discovery_xml)
taxii_message = t.get_message_from_http_response(http_resp, discovery_request.message_id)
print taxii_message.to_xml()