0
# Object Creation and Parsing
1
2
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 with validation, automatic property generation, and custom content handling.
3
4
## Capabilities
5
6
### JSON Parsing
7
8
Parse STIX JSON data into Python objects with validation and spec version detection.
9
10
```python { .api }
11
def parse(data, allow_custom=False, version=None):
12
"""
13
Parse STIX JSON data into Python objects.
14
15
Parameters:
16
- data (str or dict): STIX JSON string or dictionary
17
- allow_custom (bool): Allow custom STIX content (default: False)
18
- version (str): STIX specification version ("2.0" or "2.1")
19
20
Returns:
21
STIX Python object corresponding to the JSON data
22
23
Raises:
24
ParseError: If JSON data is invalid or malformed
25
CustomContentError: If custom content detected and not allowed
26
"""
27
```
28
29
Usage example:
30
31
```python
32
from stix2 import parse
33
34
# Parse STIX JSON string
35
stix_json = '''
36
{
37
"type": "malware",
38
"spec_version": "2.1",
39
"id": "malware--162d917e-766f-4611-b5d6-652791454fca",
40
"created": "2018-04-23T18:07:56.000Z",
41
"modified": "2018-04-23T18:07:56.000Z",
42
"name": "Poison Ivy",
43
"malware_types": ["remote-access-trojan"]
44
}
45
'''
46
47
malware_obj = parse(stix_json)
48
print(malware_obj.name) # "Poison Ivy"
49
print(malware_obj.malware_types) # ["remote-access-trojan"]
50
51
# Parse dictionary
52
stix_dict = {
53
"type": "indicator",
54
"name": "File hash indicator",
55
"indicator_types": ["malicious-activity"],
56
"pattern_type": "stix",
57
"pattern": "[file:hashes.md5 = 'abc123']"
58
}
59
60
indicator_obj = parse(stix_dict)
61
```
62
63
### Observable Parsing
64
65
Parse STIX Cyber Observable Objects with reference validation.
66
67
```python { .api }
68
def parse_observable(data, _valid_refs=None, allow_custom=False, version=None):
69
"""
70
Parse STIX Cyber Observable Objects.
71
72
Parameters:
73
- data (str or dict): SCO JSON string or dictionary
74
- _valid_refs (list): Valid object references for validation
75
- allow_custom (bool): Allow custom observables (default: False)
76
- version (str): STIX specification version ("2.0" or "2.1")
77
78
Returns:
79
STIX Cyber Observable Object
80
81
Raises:
82
ParseError: If observable data is invalid
83
InvalidObjRefError: If object references are invalid
84
"""
85
```
86
87
Usage example:
88
89
```python
90
from stix2 import parse_observable
91
92
# Parse file observable
93
file_json = '''
94
{
95
"type": "file",
96
"hashes": {
97
"MD5": "d41d8cd98f00b204e9800998ecf8427e",
98
"SHA-1": "da39a3ee5e6b4b0d3255bfef95601890afd80709"
99
},
100
"name": "empty.txt",
101
"size": 0
102
}
103
'''
104
105
file_obj = parse_observable(file_json)
106
print(file_obj.name) # "empty.txt"
107
print(file_obj.hashes) # {"MD5": "d41d8cd98f00b204e9800998ecf8427e", ...}
108
109
# Parse IP address observable
110
ip_dict = {
111
"type": "ipv4-addr",
112
"value": "192.168.1.1"
113
}
114
115
ip_obj = parse_observable(ip_dict)
116
print(ip_obj.value) # "192.168.1.1"
117
```
118
119
### Object Serialization
120
121
All STIX objects have built-in serialization methods for converting back to JSON.
122
123
```python { .api }
124
# Available on all STIX objects
125
def serialize(self, pretty=False, ensure_ascii=True, encoding='utf-8'):
126
"""
127
Serialize STIX object to JSON string.
128
129
Parameters:
130
- pretty (bool): Pretty-print JSON with indentation
131
- ensure_ascii (bool): Escape non-ASCII characters
132
- encoding (str): Character encoding for output
133
134
Returns:
135
str: JSON representation of the STIX object
136
"""
137
```
138
139
Usage example:
140
141
```python
142
from stix2 import Indicator
143
144
indicator = Indicator(
145
name="Malicious IP",
146
indicator_types=["malicious-activity"],
147
pattern_type="stix",
148
pattern="[ipv4-addr:value = '192.168.1.100']"
149
)
150
151
# Serialize to compact JSON
152
json_compact = indicator.serialize()
153
154
# Serialize to pretty-printed JSON
155
json_pretty = indicator.serialize(pretty=True)
156
print(json_pretty)
157
```
158
159
### Dictionary Conversion
160
161
Internal utility for converting dictionaries to STIX objects.
162
163
```python { .api }
164
def dict_to_stix2(stix_dict, allow_custom=False, version=None):
165
"""
166
Convert dictionary to STIX object.
167
168
Parameters:
169
- stix_dict (dict): Dictionary representation of STIX object
170
- allow_custom (bool): Allow custom content
171
- version (str): STIX specification version
172
173
Returns:
174
STIX Python object
175
"""
176
```
177
178
## Error Handling
179
180
### ParseError
181
182
Raised when STIX JSON data cannot be parsed due to syntax errors, missing required properties, or invalid structure.
183
184
```python
185
from stix2 import parse, ParseError
186
187
try:
188
invalid_json = '{"type": "invalid-type"}'
189
obj = parse(invalid_json)
190
except ParseError as e:
191
print(f"Parse error: {e}")
192
```
193
194
### CustomContentError
195
196
Raised when custom STIX content is detected but not allowed.
197
198
```python
199
from stix2 import parse, CustomContentError
200
201
try:
202
custom_json = '{"type": "x-custom-object", "name": "test"}'
203
obj = parse(custom_json, allow_custom=False)
204
except CustomContentError as e:
205
print(f"Custom content error: {e}")
206
```
207
208
## Version Handling
209
210
The library supports both STIX 2.0 and 2.1 specifications:
211
212
```python
213
# Parse as STIX 2.0
214
obj_v20 = parse(stix_json, version="2.0")
215
216
# Parse as STIX 2.1 (default)
217
obj_v21 = parse(stix_json, version="2.1")
218
219
# Auto-detect version from spec_version property
220
obj_auto = parse(stix_json) # Uses spec_version from JSON
221
```