Install & Compatibility
Where this runs
tested against v2.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.693s · 24.3MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.3s · import 0.597s · 25MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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}")
Debug
Known issues
breakingVersion 2.2.0 dropped support for Python versions older than 3.5. Ensure your environment is running Python 3.5 or newer.fixUpgrade your Python interpreter to version 3.5 or later.
affects: >=2.2.0
gotchaStarting 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.fixUse `from taxii2client.v20 import Server` (or `ApiRoot`, `Collection`, etc.) for TAXII 2.0 compatibility.
affects: >=2.0.0
gotchaWhen 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.fixAlways use fully qualified and correctly formatted URLs. For example, 'https://example.com/taxii2/' instead of 'https://example.com/taxii2'.
affects: <=0.5.0 (client-side fix), all versions (server-side dependency)
gotchaAttempting 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.fixCheck `collection.can_read` or `collection.can_write` before attempting respective operations, or ensure your user credentials have the appropriate permissions on the TAXII server.
affects: All versions
Errors
Common errors & fixes
taxii2client.exceptions.TAXIIServiceException: 401 Unauthorized
The client failed to authenticate with the TAXII server due to incorrect or missing credentials (username/password/API key).
fixVerify 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.
The authenticated user lacks the necessary read or write permissions for the target TAXII collection.
fixCheck 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.
The TAXII server's response was not a valid JSON document, which can happen due to server errors or malformed responses.
fixInspect 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
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).
fixReview 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.
Upgrade
Version history
2.3.0latest on PyPI · released Mar 12, 2021
Audit
Dependencies
No dependency data recorded yet.