0
# TAXII2-Client
1

2
A Python client library for interacting with TAXII 2.X (Trusted Automated eXchange of Indicator Information) servers. This library enables cyber threat intelligence sharing through the standardized TAXII protocol, supporting both TAXII 2.0 and 2.1 specifications for consuming and sharing structured threat data in STIX format.
3

4
## Package Information
5

6
- **Package Name**: taxii2-client
7
- **Language**: Python
8
- **Installation**: `pip install taxii2-client`
9
- **Requirements**: Python 3.6+
10

11
## Core Imports
12

13
```python
14
from taxii2client import Server, ApiRoot, Collection, Status, as_pages
15
```
16

17
For TAXII 2.1 (default/latest):
18
```python
19
from taxii2client.v21 import Server, ApiRoot, Collection, Status, as_pages
20
```
21

22
For TAXII 2.0 (legacy):
23
```python
24
from taxii2client.v20 import Server, ApiRoot, Collection, Status, as_pages
25
```
26

27
Authentication and utilities:
28
```python
29
from taxii2client.common import TokenAuth
30
from taxii2client.exceptions import TAXIIServiceException, AccessError, ValidationError
31
```
32

33
## Basic Usage
34

35
```python
36
from taxii2client import Server, Collection
37
import json
38

39
# Connect to a TAXII server
40
server = Server(
41
    url="https://example.com/taxii2/",
42
    user="username",
43
    password="password"
44
)
45

46
# Get server information
47
print(f"Server: {server.title}")
48
print(f"Available API Roots: {len(server.api_roots)}")
49

50
# Access the default API root
51
api_root = server.default or server.api_roots[0]
52
print(f"API Root: {api_root.title}")
53

54
# List available collections
55
for collection in api_root.collections:
56
    print(f"Collection: {collection.title} (ID: {collection.id})")
57
    print(f"  Can Read: {collection.can_read}, Can Write: {collection.can_write}")
58

59
# Work with a specific collection
60
collection = api_root.collections[0]  # Get first collection
61

62
# Get objects from the collection
63
if collection.can_read:
64
    objects = collection.get_objects()
65
    print(f"Retrieved {len(objects.get('objects', []))} objects")
66
    
67
    # Get paginated results
68
    for page in as_pages(collection.get_objects, per_request=100):
69
        objects = page.get('objects', [])
70
        print(f"Page contains {len(objects)} objects")
71

72
# Add objects to collection (if allowed)
73
if collection.can_write:
74
    # STIX bundle/envelope to add
75
    envelope = {
76
        "objects": [
77
            {
78
                "type": "indicator",
79
                "id": "indicator--12345678-1234-5678-9012-123456789012",
80
                "created": "2023-01-01T00:00:00.000Z",
81
                "modified": "2023-01-01T00:00:00.000Z",
82
                "pattern": "[file:hashes.MD5 = 'd41d8cd98f00b204e9800998ecf8427e']",
83
                "labels": ["malicious-activity"]
84
            }
85
        ]
86
    }
87
    
88
    # Add objects and wait for completion
89
    status = collection.add_objects(envelope, wait_for_completion=True)
90
    print(f"Add status: {status.status}")
91
    print(f"Success count: {status.success_count}")
92
```
93

94
## Architecture
95

96
TAXII2-Client follows the TAXII protocol hierarchy:
97

98
- **Server**: Discovery endpoint providing server information and available API roots
99
- **ApiRoot**: Container for collections with version and capability information  
100
- **Collection**: Repository for STIX objects supporting read/write operations
101
- **Status**: Tracks asynchronous operation progress and results
102

103
The library supports both TAXII 2.0 and 2.1 protocols with nearly identical APIs, automatically handling protocol differences including pagination mechanisms, media types, and endpoint variations.
104

105
## Capabilities
106

107
### Server Discovery
108

109
Server-level operations for discovering TAXII services, API roots, and server capabilities. Provides the entry point for all TAXII interactions.
110

111
```python { .api }
112
class Server:
113
    def __init__(self, url, conn=None, user=None, password=None, verify=True, 
114
                 proxies=None, auth=None, cert=None): ...
115
    
116
    @property
117
    def title(self) -> str: ...
118
    @property 
119
    def description(self) -> str: ...
120
    @property
121
    def contact(self) -> str: ...
122
    @property
123
    def default(self) -> ApiRoot: ...
124
    @property
125
    def api_roots(self) -> list[ApiRoot]: ...
126
    
127
    def refresh(self) -> None: ...
128
```
129

130
[Server Discovery](./server-discovery.md)
131

132
### API Root Management
133

134
API root operations for managing collections, checking capabilities, and retrieving status information within a specific TAXII API root.
135

136
```python { .api }
137
class ApiRoot:
138
    def __init__(self, url, conn=None, user=None, password=None, verify=True,
139
                 proxies=None, auth=None, cert=None): ...
140
    
141
    @property
142
    def title(self) -> str: ...
143
    @property
144
    def description(self) -> str: ...
145
    @property
146
    def versions(self) -> list[str]: ...
147
    @property
148
    def max_content_length(self) -> int: ...
149
    @property
150
    def collections(self) -> list[Collection]: ...
151
    
152
    def refresh(self, accept=None) -> None: ...
153
    def refresh_information(self, accept=None) -> None: ...
154
    def refresh_collections(self, accept=None) -> None: ...
155
    def get_status(self, status_id, accept=None) -> Status: ...
156
```
157

158
[API Root Management](./api-root-management.md)
159

160
### Collection Operations
161

162
Collection-level operations for managing STIX objects including retrieval, addition, deletion, and manifest operations.
163

164
```python { .api }
165
class Collection:
166
    def __init__(self, url, conn=None, user=None, password=None, verify=True,
167
                 proxies=None, collection_info=None, auth=None, cert=None): ...
168
    
169
    @property
170
    def id(self) -> str: ...
171
    @property
172
    def title(self) -> str: ...
173
    @property
174
    def can_read(self) -> bool: ...
175
    @property
176
    def can_write(self) -> bool: ...
177
    
178
    def get_objects(self, accept=None, **filter_kwargs) -> dict: ...
179
    def get_object(self, obj_id, accept=None, **filter_kwargs) -> dict: ...
180
    def add_objects(self, envelope, wait_for_completion=True, poll_interval=1,
181
                   timeout=60, accept=None, content_type=None) -> Status: ...
182
    def get_manifest(self, accept=None, **filter_kwargs) -> dict: ...
183
    # TAXII 2.1 only:
184
    def delete_object(self, obj_id, accept=None, **filter_kwargs) -> dict: ...
185
    def object_versions(self, obj_id, accept=None, **filter_kwargs) -> dict: ...
186
```
187

188
[Collection Operations](./collection-operations.md)
189

190
### Status Monitoring
191

192
Status tracking for asynchronous operations including polling, completion checking, and result analysis.
193

194
```python { .api }
195
class Status:
196
    def __init__(self, url, conn=None, user=None, password=None, verify=True,
197
                 proxies=None, status_info=None, auth=None, cert=None): ...
198
    
199
    @property
200
    def id(self) -> str: ...
201
    @property
202
    def status(self) -> str: ...
203
    @property
204
    def total_count(self) -> int: ...
205
    @property
206
    def success_count(self) -> int: ...
207
    @property
208
    def failure_count(self) -> int: ...
209
    @property
210
    def pending_count(self) -> int: ...
211
    @property
212
    def successes(self) -> list: ...
213
    @property
214
    def failures(self) -> list: ...
215
    @property
216
    def pendings(self) -> list: ...
217
    
218
    def refresh(self, accept=None) -> None: ...
219
    def wait_until_final(self, poll_interval=1, timeout=60) -> None: ...
220
    def __bool__(self) -> bool: ...
221
```
222

223
[Status Monitoring](./status-monitoring.md)
224

225
### Pagination Support
226

227
Pagination utilities for handling large result sets across different TAXII versions with automatic page traversal.
228

229
```python { .api }
230
def as_pages(func, per_request=0, *args, **kwargs):
231
    """
232
    Generator for TAXII endpoints supporting pagination.
233
    
234
    Parameters:
235
    - func: Collection method supporting pagination (get_objects, get_manifest)
236
    - per_request: Items per request (0 for server default)
237
    
238
    Yields:
239
    dict: Response envelope/bundle for each page
240
    """
241
```
242

243
[Pagination Support](./pagination-support.md)
244

245
### Authentication & Connection
246

247
Authentication mechanisms and connection management including basic auth, token auth, and SSL client certificates.
248

249
```python { .api }
250
class TokenAuth:
251
    def __init__(self, key: str): ...
252
    def __call__(self, r): ...
253
```
254

255
[Authentication & Connection](./authentication-connection.md)
256

257
## Constants
258

259
```python { .api }
260
DEFAULT_USER_AGENT: str = "taxii2-client/2.3.0"
261
MEDIA_TYPE_STIX_V20: str = "application/vnd.oasis.stix+json; version=2.0"
262
MEDIA_TYPE_TAXII_V20: str = "application/vnd.oasis.taxii+json; version=2.0"
263
MEDIA_TYPE_TAXII_V21: str = "application/taxii+json;version=2.1"
264
```
265

266
## Exception Types
267

268
```python { .api }
269
class TAXIIServiceException(Exception):
270
    """Base exception for all TAXII client errors."""
271

272
class InvalidArgumentsError(TAXIIServiceException):
273
    """Invalid arguments passed to method."""
274

275
class AccessError(TAXIIServiceException):
276
    """Read/write access denied to collection."""
277

278
class ValidationError(TAXIIServiceException):
279
    """Data validation failed."""
280

281
class InvalidJSONError(TAXIIServiceException):
282
    """Invalid JSON received from server."""
283
```