0
# STIX2
1

2
Python APIs for serializing and de-serializing STIX 2 JSON content, along with higher-level APIs for common tasks including data markings, versioning, and resolving STIX IDs across multiple data sources. STIX (Structured Threat Information Expression) is a standardized language for cyber threat intelligence enabling organizations to share, store, and analyze cyber threat information in a consistent manner.
3

4
## Package Information
5

6
- **Package Name**: stix2
7
- **Language**: Python
8
- **Installation**: `pip install stix2`
9
- **Requirements**: Python 3.6+
10
- **Documentation**: https://stix2.readthedocs.io/
11

12
## Core Imports
13

14
```python
15
import stix2
16
```
17

18
Common imports for specific functionality:
19

20
```python
21
from stix2 import parse, Indicator, Malware, AttackPattern
22
from stix2 import FileSystemStore, MemoryStore
23
from stix2 import add_markings, get_markings
24
```
25

26
## Basic Usage
27

28
### Creating STIX Objects
29

30
```python
31
from stix2 import Indicator, Malware, AttackPattern
32

33
# Create an indicator
34
indicator = Indicator(
35
    name="File hash for malware variant",
36
    indicator_types=["malicious-activity"],
37
    pattern_type="stix",
38
    pattern="[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']"
39
)
40

41
# Create a malware object
42
malware = Malware(
43
    name="Poison Ivy",
44
    malware_types=["remote-access-trojan"]
45
)
46

47
# Create an attack pattern
48
attack_pattern = AttackPattern(
49
    name="Spear Phishing",
50
    external_references=[
51
        {
52
            "source_name": "mitre-attack",
53
            "external_id": "T1566.001"
54
        }
55
    ]
56
)
57
```
58

59
### Parsing and Serializing STIX Content
60

61
```python
62
from stix2 import parse
63

64
# Parse STIX JSON into Python objects
65
stix_json = '''
66
{
67
    "type": "indicator",
68
    "spec_version": "2.1",
69
    "id": "indicator--01234567-89ab-cdef-0123-456789abcdef",
70
    "created": "2018-04-23T18:07:56.000Z",
71
    "modified": "2018-04-23T18:07:56.000Z",
72
    "name": "File hash for malware variant",
73
    "indicator_types": ["malicious-activity"],
74
    "pattern_type": "stix",
75
    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']"
76
}
77
'''
78

79
indicator = parse(stix_json)
80
print(indicator.name)  # "File hash for malware variant"
81

82
# Serialize STIX object to JSON
83
json_output = indicator.serialize(pretty=True)
84
```
85

86
### Data Storage and Retrieval
87

88
```python
89
from stix2 import MemoryStore, FileSystemStore, Indicator
90

91
# Create in-memory data store
92
memory_store = MemoryStore()
93

94
# Add objects to store
95
indicator = Indicator(
96
    name="Example Indicator",
97
    indicator_types=["malicious-activity"],
98
    pattern_type="stix",
99
    pattern="[file:hashes.md5 = 'abc123']"
100
)
101
memory_store.add(indicator)
102

103
# Query objects
104
results = memory_store.query([stix2.Filter('type', '=', 'indicator')])
105

106
# File system store
107
fs_store = FileSystemStore("/path/to/stix/data")
108
fs_store.add(indicator)
109
```
110

111
## Architecture
112

113
The STIX2 library is organized around several key concepts:
114

115
- **STIX Domain Objects (SDOs)**: Core cyber threat intelligence objects like Indicator, Malware, AttackPattern, ThreatActor
116
- **STIX Relationship Objects (SROs)**: Relationship and Sighting objects that connect SDOs
117
- **STIX Cyber Observable Objects (SCOs)**: Observable cyber artifacts like File, IPv4Address, DomainName
118
- **Data Stores**: Pluggable backends for storing and retrieving STIX objects (Memory, FileSystem, TAXII)
119
- **Environment**: Configurable context for object creation and parsing
120
- **Markings**: Data marking and classification system for access control
121

122
## Capabilities
123

124
### STIX Object Creation and Parsing
125

126
Core functionality for creating STIX objects from scratch and parsing existing STIX JSON content into Python objects. Supports all STIX 2.0 and 2.1 specification objects including validation and automatic property generation.
127

128
```python { .api }
129
def parse(data, allow_custom=False, version=None):
130
    """Parse STIX JSON data into Python objects."""
131

132
def parse_observable(data, _valid_refs=None, allow_custom=False, version=None):
133
    """Parse STIX Cyber Observable Objects."""
134
```
135

136
[Object Creation and Parsing](./object-creation.md)
137

138
### STIX Domain Objects (SDOs)
139

140
STIX Domain Objects represent higher-level cyber threat intelligence concepts including threat actors, attack patterns, malware, indicators, campaigns, and other strategic threat intelligence.
141

142
```python { .api }
143
class AttackPattern: ...
144
class Campaign: ...
145
class CourseOfAction: ...
146
class Identity: ...
147
class Indicator: ...
148
class IntrusionSet: ...
149
class Malware: ...
150
class ObservedData: ...
151
class Report: ...
152
class ThreatActor: ...
153
class Tool: ...
154
class Vulnerability: ...
155
```
156

157
[STIX Domain Objects](./stix-domain-objects.md)
158

159
### STIX Cyber Observable Objects (SCOs)
160

161
STIX Cyber Observable Objects represent observable cyber artifacts such as files, network addresses, processes, registry keys, and other technical indicators that can be observed in cyber operations.
162

163
```python { .api }
164
class File: ...
165
class IPv4Address: ...
166
class IPv6Address: ...
167
class DomainName: ...
168
class URL: ...
169
class EmailAddress: ...
170
class NetworkTraffic: ...
171
class Process: ...
172
class Software: ...
173
class UserAccount: ...
174
```
175

176
[STIX Cyber Observable Objects](./stix-observables.md)
177

178
### Data Storage and Retrieval
179

180
Flexible data store backends for persisting and querying STIX objects including in-memory storage, file system storage, and TAXII server integration with comprehensive filtering and search capabilities.
181

182
```python { .api }
183
class MemoryStore: ...
184
class FileSystemStore: ...
185
class TAXIICollectionStore: ...
186
class CompositeDataSource: ...
187
class Filter: ...
188
```
189

190
[Data Storage](./data-storage.md)
191

192
### Object Relationships and Links
193

194
STIX Relationship Objects and utilities for creating and managing connections between STIX objects, including relationships, sightings, and reference resolution across multiple data sources.
195

196
```python { .api }
197
class Relationship: ...
198
class Sighting: ...
199
```
200

201
[Relationships](./relationships.md)
202

203
### Data Markings and Access Control
204

205
Comprehensive data marking system for applying access control, handling restrictions, and managing classification levels on STIX objects using both object-level and granular markings.
206

207
```python { .api }
208
def add_markings(obj, marking, selectors=None): ...
209
def clear_markings(obj, selectors=None, marking_ref=True, lang=True): ...
210
def get_markings(obj, selectors=None, inherited=False, descendants=False, marking_ref=True, lang=True): ...
211
def is_marked(obj, marking=None, selectors=None, inherited=False, descendants=False): ...
212
def remove_markings(obj, marking, selectors=None): ...
213
def set_markings(obj, marking, selectors=None, marking_ref=True, lang=True): ...
214
```
215

216
[Data Markings](./markings.md)
217

218
### Object Versioning and Evolution
219

220
Version management system for creating new versions of STIX objects, tracking changes over time, and handling object revocation with proper timestamp and identifier management.
221

222
```python { .api }
223
def new_version(stix_obj, **kwargs): ...
224
def revoke(stix_obj): ...
225
```
226

227
[Versioning](./versioning.md)
228

229
### Pattern Matching and Expressions
230

231
Comprehensive pattern expression system for STIX indicator patterns including observation expressions, boolean logic, comparison operations, and temporal qualifiers for complex threat detection rules.
232

233
```python { .api }
234
class ObservationExpression: ...
235
class AndBooleanExpression: ...
236
class OrBooleanExpression: ...
237
class EqualityComparisonExpression: ...
238
class ObjectPath: ...
239
```
240

241
[Pattern Matching](./pattern-matching.md)
242

243
### Utilities and Type Checking
244

245
Utility functions for working with STIX objects including type checking, timestamp handling, object deduplication, confidence scale conversions, and specification version detection.
246

247
```python { .api }
248
def is_sdo(value, stix_version="2.1"): ...
249
def is_sco(value, stix_version="2.1"): ...
250
def is_sro(value, stix_version="2.1"): ...
251
def get_timestamp(): ...
252
def deduplicate(stix_obj_list): ...
253
def none_low_med_high_to_value(scale_value): ...
254
def value_to_none_low_medium_high(confidence_value): ...
255
```
256

257
[Utilities](./utilities.md)
258

259
### STIX Equivalence and Similarity
260

261
Semantic equivalence and similarity algorithms for STIX objects, graphs, and patterns implementing the STIX Semantic Equivalence Committee Note specifications for intelligent content comparison.
262

263
```python { .api }
264
def object_equivalence(obj1, obj2, threshold=70, **kwargs): ...
265
def object_similarity(obj1, obj2, **kwargs): ...
266
def graph_equivalence(ds1, ds2, threshold=70, **kwargs): ...
267
def graph_similarity(ds1, ds2, **kwargs): ...
268
def equivalent_patterns(pattern1, pattern2, stix_version="2.1"): ...
269
```
270

271
[STIX Equivalence](./equivalence.md)