0
# STIX Domain Objects (SDOs)
1

2
STIX Domain Objects represent higher-level cyber threat intelligence concepts including threat actors, attack patterns, malware, indicators, campaigns, and other strategic threat intelligence. These objects form the core building blocks for expressing cyber threat information in a standardized format.
3

4
## Capabilities
5

6
### Threat Intelligence Objects
7

8
Core objects for representing threat intelligence entities and their characteristics.
9

10
```python { .api }
11
class AttackPattern:
12
    """
13
    Attack patterns describe methods adversaries use to compromise targets.
14
    
15
    Required Properties:
16
    - name (str): Name of the attack pattern
17
    
18
    Optional Properties:
19
    - description (str): Description of the attack pattern
20
    - external_references (list): External references (e.g., MITRE ATT&CK)
21
    - kill_chain_phases (list): Kill chain phases where pattern is used
22
    """
23

24
class ThreatActor:
25
    """
26
    Threat actors represent individuals, groups, or organizations conducting attacks.
27
    
28
    Required Properties:
29
    - name (str): Name of the threat actor
30
    - threat_actor_types (list): Types of threat actor
31
    
32
    Optional Properties:
33
    - aliases (list): Alternative names
34
    - description (str): Description of the threat actor
35
    - sophistication (str): Sophistication level
36
    - resource_level (str): Resource level
37
    - primary_motivation (str): Primary motivation
38
    - secondary_motivations (list): Secondary motivations
39
    - personal_motivations (list): Personal motivations
40
    - goals (list): Goals of the threat actor
41
    """
42

43
class IntrusionSet:
44
    """
45
    Intrusion sets represent grouped activities conducted by threat actors.
46
    
47
    Required Properties:
48
    - name (str): Name of the intrusion set
49
    
50
    Optional Properties:
51
    - description (str): Description of activities
52
    - aliases (list): Alternative names
53
    - first_seen (timestamp): First observation time
54
    - last_seen (timestamp): Last observation time
55
    - goals (list): Goals of the intrusion set
56
    - resource_level (str): Resource level
57
    - primary_motivation (str): Primary motivation
58
    - secondary_motivations (list): Secondary motivations
59
    """
60

61
class Campaign:
62
    """
63
    Campaigns represent series of malicious activities or attacks.
64
    
65
    Required Properties:
66
    - name (str): Name of the campaign
67
    
68
    Optional Properties:
69
    - description (str): Description of the campaign
70
    - aliases (list): Alternative names
71
    - first_seen (timestamp): Campaign start time
72
    - last_seen (timestamp): Campaign end time
73
    - objective (str): Campaign objective
74
    """
75
```
76

77
Usage examples:
78

79
```python
80
from stix2 import AttackPattern, ThreatActor, Campaign
81

82
# Create attack pattern
83
attack_pattern = AttackPattern(
84
    name="Spear Phishing Attachment",
85
    description="Adversaries may send spear phishing emails with malicious attachments",
86
    external_references=[
87
        {
88
            "source_name": "mitre-attack",
89
            "external_id": "T1566.001",
90
            "url": "https://attack.mitre.org/techniques/T1566/001/"
91
        }
92
    ],
93
    kill_chain_phases=[
94
        {
95
            "kill_chain_name": "mitre-attack",
96
            "phase_name": "initial-access"
97
        }
98
    ]
99
)
100

101
# Create threat actor
102
threat_actor = ThreatActor(
103
    name="APT1",
104
    threat_actor_types=["nation-state"],
105
    aliases=["Comment Crew", "PLA Unit 61398"],
106
    sophistication="advanced",
107
    resource_level="government",
108
    primary_motivation="organizational-gain"
109
)
110

111
# Create campaign
112
campaign = Campaign(
113
    name="Operation Aurora",
114
    description="Cyber attack campaign targeting Google and other companies",
115
    first_seen="2009-12-01T00:00:00.000Z",
116
    last_seen="2010-01-12T00:00:00.000Z"
117
)
118
```
119

120
### Malware and Tools
121

122
Objects for representing malicious software and legitimate tools used by adversaries.
123

124
```python { .api }
125
class Malware:
126
    """
127
    Malware represents malicious software used by adversaries.
128
    
129
    Required Properties:
130
    - name (str): Name of the malware
131
    - malware_types (list): Types of malware
132
    
133
    Optional Properties:
134
    - is_family (bool): Whether this represents a malware family
135
    - aliases (list): Alternative names
136
    - description (str): Description of the malware
137
    - first_seen (timestamp): First observation time
138
    - last_seen (timestamp): Last observation time
139
    - operating_system_refs (list): Supported operating systems
140
    - architecture_execution_envs (list): Execution environments
141
    - implementation_languages (list): Programming languages used
142
    - capabilities (list): Malware capabilities
143
    """
144

145
class Tool:
146
    """
147
    Tools represent legitimate software used by adversaries.
148
    
149
    Required Properties:
150
    - name (str): Name of the tool
151
    - tool_types (list): Types of tool
152
    
153
    Optional Properties:
154
    - aliases (list): Alternative names
155
    - description (str): Description of the tool
156
    - tool_version (str): Version of the tool
157
    - kill_chain_phases (list): Kill chain phases where tool is used
158
    """
159

160
class MalwareAnalysis:
161
    """
162
    Malware analysis captures results of analyzing malware samples.
163
    
164
    Required Properties:
165
    - product (str): Analysis product/tool used
166
    - result (str): Result of the analysis
167
    
168
    Optional Properties:
169
    - version (str): Analysis tool version
170
    - host_vm_ref (str): Reference to analysis environment
171
    - operating_system_ref (str): Reference to operating system
172
    - installed_software_refs (list): Installed software references
173
    - configuration_version (str): Configuration version
174
    - modules (list): Analysis modules used
175
    - analysis_engine_version (str): Analysis engine version
176
    - analysis_definition_version (str): Analysis definition version
177
    - submitted (timestamp): Submission time
178
    - analysis_started (timestamp): Analysis start time  
179
    - analysis_ended (timestamp): Analysis end time
180
    - av_result (str): Antivirus result
181
    - sample_refs (list): Sample references
182
    """
183
```
184

185
Usage examples:
186

187
```python
188
from stix2 import Malware, Tool, MalwareAnalysis
189

190
# Create malware object
191
malware = Malware(
192
    name="Poison Ivy",
193
    malware_types=["remote-access-trojan"],
194
    aliases=["Pivy", "PIVY"],
195
    description="Remote access trojan that allows attackers to control infected systems",
196
    is_family=True,
197
    capabilities=["remote-machine-access", "anti-detection", "data-theft"]
198
)
199

200
# Create tool object  
201
tool = Tool(
202
    name="PowerShell",
203
    tool_types=["execution"],
204
    description="Windows PowerShell command-line shell and scripting language",
205
    kill_chain_phases=[
206
        {
207
            "kill_chain_name": "mitre-attack",
208
            "phase_name": "execution"
209
        }
210
    ]
211
)
212

213
# Create malware analysis
214
analysis = MalwareAnalysis(
215
    product="ClamAV",
216
    result="malicious",
217
    analysis_engine_version="0.103.2",
218
    analysis_definition_version="26123",
219
    submitted="2021-04-23T10:30:00.000Z",
220
    av_result="Trojan.Win32.PoisonIvy"
221
)
222
```
223

224
### Indicators and Observables
225

226
Objects for representing indicators of compromise and observed data.
227

228
```python { .api }
229
class Indicator:
230
    """
231
    Indicators contain detection patterns for suspicious or malicious activity.
232
    
233
    Required Properties:
234
    - indicator_types (list): Types of indicator
235
    - pattern (str): Detection pattern 
236
    - pattern_type (str): Pattern language type ("stix")
237
    
238
    Optional Properties:
239
    - name (str): Name of the indicator
240
    - description (str): Description of the indicator
241
    - pattern_version (str): Pattern language version
242
    - valid_from (timestamp): Validity start time
243
    - valid_until (timestamp): Validity end time
244
    - kill_chain_phases (list): Kill chain phases
245
    """
246

247
class ObservedData:
248
    """
249
    Observed data conveys raw information observed on networks or systems.
250
    
251
    Required Properties:
252
    - first_observed (timestamp): First observation time
253
    - last_observed (timestamp): Last observation time
254
    - number_observed (int): Number of times observed
255
    - objects (dict): Observed cyber observables
256
    
257
    Optional Properties:
258
    - object_refs (list): References to observed objects
259
    """
260
```
261

262
Usage examples:
263

264
```python
265
from stix2 import Indicator, ObservedData
266

267
# Create indicator
268
indicator = Indicator(
269
    name="Malicious file hash",
270
    indicator_types=["malicious-activity"],
271
    pattern_type="stix",
272
    pattern="[file:hashes.MD5 = 'd41d8cd98f00b204e9800998ecf8427e']",
273
    valid_from="2021-04-23T10:30:00.000Z"
274
)
275

276
# Create observed data
277
observed_data = ObservedData(
278
    first_observed="2021-04-23T10:30:00.000Z",
279
    last_observed="2021-04-23T10:35:00.000Z", 
280
    number_observed=1,
281
    objects={
282
        "0": {
283
            "type": "file",
284
            "hashes": {
285
                "MD5": "d41d8cd98f00b204e9800998ecf8427e"
286
            },
287
            "name": "malware.exe"
288
        }
289
    }
290
)
291
```
292

293
### Other Domain Objects
294

295
Additional domain objects for comprehensive threat intelligence representation.
296

297
```python { .api }
298
class Identity:
299
    """
300
    Identities represent individuals, organizations, or groups.
301
    
302
    Required Properties:
303
    - name (str): Name of the identity
304
    - identity_class (str): Class of identity
305
    
306
    Optional Properties:
307
    - description (str): Description
308
    - roles (list): Roles performed by identity
309
    - sectors (list): Industry sectors
310
    - contact_information (str): Contact information
311
    """
312

313
class Vulnerability:
314
    """
315
    Vulnerabilities represent flaws in software, firmware, or hardware.
316
    
317
    Required Properties:
318
    - name (str): Name of the vulnerability
319
    
320
    Optional Properties:
321
    - description (str): Description of the vulnerability
322
    - external_references (list): External references (e.g., CVE)
323
    """
324

325
class CourseOfAction:
326
    """
327
    Courses of action represent preventive or corrective actions.
328
    
329
    Required Properties:
330
    - name (str): Name of the course of action
331
    
332
    Optional Properties:
333
    - description (str): Description of the action
334
    - action_type (str): Type of action
335
    - os_execution_envs (list): Operating system environments
336
    - action_bin (str): Executable binary content
337
    - action_reference (str): Reference to external action
338
    """
339

340
class Report:
341
    """
342
    Reports aggregate and contextualize STIX domain objects.
343
    
344
    Required Properties:
345
    - name (str): Name of the report
346
    - published (timestamp): Publication time
347
    - object_refs (list): References to reported objects
348
    
349
    Optional Properties:
350
    - description (str): Description of the report
351
    - report_types (list): Types of report
352
    """
353

354
class Grouping:
355
    """
356
    Groupings explicitly assert that referenced objects are related.
357
    
358
    Required Properties:
359
    - context (str): Context for the grouping
360
    - object_refs (list): References to grouped objects
361
    
362
    Optional Properties:
363
    - name (str): Name of the grouping
364
    - description (str): Description of the grouping
365
    """
366

367
class Location:
368
    """
369
    Locations represent geographic areas.
370
    
371
    Optional Properties:
372
    - name (str): Name of the location
373
    - description (str): Description
374
    - latitude (float): Latitude coordinate
375
    - longitude (float): Longitude coordinate
376
    - precision (float): Coordinate precision
377
    - region (str): Geographic region
378
    - country (str): Country name/code
379
    - administrative_area (str): Administrative area
380
    - city (str): City name
381
    - street_address (str): Street address
382
    - postal_code (str): Postal code
383
    """
384

385
class Note:
386
    """
387
    Notes contain additional information about STIX objects.
388
    
389
    Required Properties:
390
    - content (str): Content of the note
391
    - object_refs (list): References to annotated objects
392
    
393
    Optional Properties:
394
    - abstract (str): Abstract of the note
395
    - authors (list): Authors of the note
396
    """
397

398
class Opinion:
399
    """
400
    Opinions represent assessments of STIX objects.
401
    
402
    Required Properties:
403
    - opinion (str): Opinion value
404
    - object_refs (list): References to assessed objects
405
    
406
    Optional Properties:
407
    - explanation (str): Explanation of the opinion
408
    - authors (list): Authors of the opinion
409
    """
410

411
class Infrastructure:
412
    """
413
    Infrastructure represents systems used by adversaries.
414
    
415
    Required Properties:
416
    - name (str): Name of the infrastructure
417
    - infrastructure_types (list): Types of infrastructure
418
    
419
    Optional Properties:
420
    - description (str): Description
421
    - aliases (list): Alternative names
422
    - kill_chain_phases (list): Kill chain phases
423
    - first_seen (timestamp): First observation time
424
    - last_seen (timestamp): Last observation time
425
    """
426

427
class Incident:
428
    """
429
    Incidents represent actual security incidents.
430
    
431
    Required Properties:
432
    - name (str): Name of the incident
433
    
434
    Optional Properties:
435
    - description (str): Description of the incident
436
    """
437
```
438

439
## Custom Domain Objects
440

441
Create custom domain objects for organization-specific needs:
442

443
```python
444
from stix2 import CustomObject
445

446
# Define custom SDO
447
@CustomObject('x-custom-threat', [
448
    ('name', stix2.properties.StringProperty(required=True)),
449
    ('threat_level', stix2.properties.StringProperty()),
450
])
451
class CustomThreat:
452
    pass
453

454
# Create instance
455
custom_threat = CustomThreat(
456
    name="Custom Threat Type",
457
    threat_level="high"
458
)
459
```