TAXII 2 Client Library

2.3.0 · active · verified Thu Apr 16

taxii2-client is a minimal Python client library for the Trusted Automated eXchange of Indicator Information (TAXII) 2.x specification. It supports both TAXII 2.0 and 2.1, enabling interaction with TAXII servers for cyber threat intelligence (CTI) exchange, including server discovery, API root information, collection management, and object retrieval/addition. It is currently at version 2.3.0 and is maintained by OASIS Open as an OASIS TC Open Repository.

Common errors

```
taxii2client.exceptions.TAXIIServiceException: 401 Unauthorized
```
cause The client failed to authenticate with the TAXII server due to incorrect or missing credentials (username/password/API key).

fix Verify that the `user` and `password` parameters (or other authentication methods like `auth` or `cert`) passed to the `Server` constructor are correct for the TAXII server you are connecting to. Ensure environment variables for credentials are set correctly.
```
taxii2client.exceptions.AccessError: Attempt was made to read/write to a collection when the collection doesn't allow that operation.
```
cause The authenticated user lacks the necessary read or write permissions for the target TAXII collection.

fix Check the `can_read` and `can_write` attributes of the `Collection` object. Ensure the credentials used have sufficient privileges on the TAXII server for the desired operation.
```
taxii2client.exceptions.InvalidJSONError: A server endpoint gave us invalid JSON.
```
cause The TAXII server's response was not a valid JSON document, which can happen due to server errors or malformed responses.

fix Inspect the raw response content if possible (e.g., via `server._conn.get('your_url')._raw.text`) to diagnose the server's output. Contact the TAXII server administrator if the issue persists and appears server-side.
```
taxii2client.exceptions.ValidationError: Data validation failed for a property or group of properties
```
cause An operation, such as adding objects to a collection, involved data that did not conform to the expected schema or constraints (e.g., STIX format).

fix Review the data you are sending to the TAXII server to ensure it complies with the STIX specification (e.g., STIX 2.1) and any server-specific validation rules for the target collection.

Warnings

breaking Version 2.2.0 dropped support for Python versions older than 3.5. Ensure your environment is running Python 3.5 or newer.
Fix: Upgrade your Python interpreter to version 3.5 or later.
gotcha Starting with version 2.0.0, importing `taxii2client` directly will default to loading TAXII 2.1 classes (e.g., `from taxii2client.v21 import Server`). If you intend to work with TAXII 2.0, you must explicitly import from the `v20` subpackage.
Fix: Use `from taxii2client.v20 import Server` (or `ApiRoot`, `Collection`, etc.) for TAXII 2.0 compatibility.
gotcha When constructing URLs for TAXII endpoints, ensure they are correctly formatted, including trailing slashes where expected by the server. Older versions had issues with missing trailing slashes, and while fixed in the client, server-side requirements remain.
Fix: Always use fully qualified and correctly formatted URLs. For example, 'https://example.com/taxii2/' instead of 'https://example.com/taxii2'.
gotcha Attempting to read from or write to a TAXII Collection without the necessary permissions will result in an `AccessError` exception. Collections have `can_read` and `can_write` attributes.
Fix: Check `collection.can_read` or `collection.can_write` before attempting respective operations, or ensure your user credentials have the appropriate permissions on the TAXII server.

Install

pip install taxii2-client Install latest version

Imports

Server
```
from taxii2client.v21 import Server
```
Imports the TAXII 2.1 Server class by default from version 2.0.0 onwards.
Server (for v20)
```
from taxii2client.v20 import Server
```
Explicitly import for TAXII 2.0 compatibility if not using 2.1 features.
ApiRoot
```
from taxii2client.v21 import ApiRoot
```
Similarly, ApiRoot, Collection, and Status classes can be imported from v20 or v21 subpackages.

Quickstart

This quickstart connects to a TAXII 2.1 server, authenticates, retrieves available API Roots, and then lists the collections within each root. It demonstrates basic server and API root discovery. Authentication details are stored in the `Server` instance for subsequent requests.

import os
from taxii2client.v21 import Server

# Replace with your TAXII server URL and credentials
TAXII_SERVER_URL = os.environ.get('TAXII_SERVER_URL', 'https://example.com/taxii2/')
TAXII_USER = os.environ.get('TAXII_USER', 'guest')
TAXII_PASSWORD = os.environ.get('TAXII_PASSWORD', 'guest_password')

try:
    # Initialize the Server object
    server = Server(TAXII_SERVER_URL, user=TAXII_USER, password=TAXII_PASSWORD)
    print(f"Connected to TAXII Server: {server.title}")

    # Iterate through API Roots
    for api_root in server.api_roots:
        print(f"\n  API Root: {api_root.title} ({api_root.versions})")
        
        # Iterate through Collections in each API Root
        for collection in api_root.collections:
            print(f"    Collection ID: {collection.id}, Title: {collection.title}, Can Read: {collection.can_read}")

            # Example: Fetching objects from a readable collection (optional)
            if collection.can_read:
                # This is a simplified example; real-world usage might require pagination (as_pages)
                # and filtering. 'objects' attribute is lazy-loaded.
                # objects_gen = collection.get_objects(limit=10) # For paginated requests
                # for obj in objects_gen:
                #     print(f"        Object ID: {obj['id']}")
                pass

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →