0
# STIX 2.0 Data Access and Querying
1

2
Core functionality for loading, querying, and analyzing MITRE ATT&CK data using the STIX 2.0 format. The `MitreAttackData` class provides comprehensive access to all ATT&CK objects and their relationships through 90+ specialized methods for filtering, searching, and relationship mapping.
3

4
## Capabilities
5

6
### Data Loading and Initialization
7

8
Load ATT&CK data from various sources including local files, URLs, or default datasets.
9

10
```python { .api }
11
class MitreAttackData:
12
    def __init__(self, stix_filepath: str | None = None, src: stix2.MemoryStore | None = None):
13
        """
14
        Central class for querying, analyzing, and mapping relationships between STIX 2.0 objects in the MITRE ATT&CK framework.
15
        
16
        Args:
17
            stix_filepath (str | None, optional): Filepath to a STIX 2.0 bundle. Mutually exclusive with src.
18
            src (stix2.MemoryStore | None, optional): A STIX 2.0 bundle already loaded into memory. Mutually exclusive with stix_filepath.
19
            
20
        Raises:
21
            TypeError: If neither or both of stix_filepath and src are provided, or if stix_filepath is not a string.
22
        """
23
```
24

25
Usage example:
26
```python
27
from mitreattack.stix20 import MitreAttackData
28
from mitreattack.attackToExcel import get_stix_data
29

30
# Method 1: Load data first, then create MitreAttackData
31
data_store = get_stix_data("enterprise-attack")
32
attack_data = MitreAttackData(src=data_store)
33

34
# Method 2: Load from local file
35
attack_data = MitreAttackData(stix_filepath="/path/to/enterprise-attack.json")
36

37
# Method 3: Load specific version
38
data_store = get_stix_data("enterprise-attack", version="14.1")
39
attack_data = MitreAttackData(src=data_store)
40
```
41

42
### Object Retrieval by Type
43

44
Get all objects of specific ATT&CK types with optional filtering.
45

46
```python { .api }
47
def get_matrices(self, remove_revoked_deprecated: bool = False) -> list[Matrix]:
48
    """Retrieve all matrix objects."""
49

50
def get_tactics(self, remove_revoked_deprecated: bool = False) -> list[Tactic]:
51
    """Retrieve all tactic objects."""
52

53
def get_techniques(self, include_subtechniques: bool = True, remove_revoked_deprecated: bool = False) -> list[Technique]:
54
    """Retrieve all technique objects."""
55

56
def get_subtechniques(self, remove_revoked_deprecated: bool = False) -> list[Technique]:
57
    """Retrieve all sub-technique objects."""
58

59
def get_mitigations(self, remove_revoked_deprecated: bool = False) -> list[Mitigation]:
60
    """Retrieve all mitigation objects."""
61

62
def get_groups(self, remove_revoked_deprecated: bool = False) -> list[Group]:
63
    """Retrieve all group objects."""
64

65
def get_software(self, remove_revoked_deprecated: bool = False) -> list[Software]:
66
    """Retrieve all software objects."""
67

68
def get_campaigns(self, remove_revoked_deprecated: bool = False) -> list[Campaign]:
69
    """Retrieve all campaign objects."""
70

71
def get_assets(self, remove_revoked_deprecated: bool = False) -> list[Asset]:
72
    """Retrieve all asset objects."""
73

74
def get_datasources(self, remove_revoked_deprecated: bool = False) -> list[DataSource]:
75
    """Retrieve all data source objects."""
76

77
def get_datacomponents(self, remove_revoked_deprecated: bool = False) -> list[DataComponent]:
78
    """Retrieve all data component objects."""
79
```
80

81
### Generic Object Queries
82

83
Query objects by type, content, name, or other criteria.
84

85
```python { .api }
86
def get_objects_by_type(self, stix_type: str, remove_revoked_deprecated: bool = False) -> list[AttackStixObject]:
87
    """Retrieve objects by STIX type."""
88

89
def get_objects_by_content(self, content: str, object_type: str | None = None, remove_revoked_deprecated: bool = False) -> list[AttackStixObject]:
90
    """Retrieve objects by the content of their description (case insensitive)."""
91

92
def get_objects_by_name(self, name: str, stix_type: str) -> list[AttackStixObject]:
93
    """Retrieve objects by name (case sensitive)."""
94

95
def get_objects_created_after(self, timestamp: str, remove_revoked_deprecated: bool = False) -> list[AttackStixObject]:
96
    """Retrieve objects which have been created after a given time."""
97

98
def get_objects_modified_after(self, date: str, remove_revoked_deprecated: bool = False) -> list[AttackStixObject]:
99
    """Retrieve objects which have been modified after a given time."""
100
```
101

102
### Platform and Tactic Filtering
103

104
Filter techniques by platform or tactic associations.
105

106
```python { .api }
107
def get_techniques_by_platform(self, platform: str, remove_revoked_deprecated: bool = False) -> list[Technique]:
108
    """Retrieve techniques under a specific platform."""
109

110
def get_techniques_by_tactic(self, tactic_shortname: str, domain: str, remove_revoked_deprecated: bool = False) -> list[Technique]:
111
    """Retrieve techniques by tactic."""
112

113
def get_tactics_by_technique(self, stix_id: str) -> list[Tactic]:
114
    """Retrieve the list of tactics within a particular technique."""
115

116
def get_tactics_by_matrix(self) -> dict[str, list[Tactic]]:
117
    """Retrieve the structured list of tactics within each matrix."""
118
```
119

120
### ID and Metadata Operations
121

122
Access objects by their identifiers and extract metadata.
123

124
```python { .api }
125
def get_object_by_stix_id(self, stix_id: str) -> AttackStixObject:
126
    """Retrieve a single object by STIX ID."""
127

128
def get_object_by_attack_id(self, attack_id: str, stix_type: str) -> AttackStixObject | None:
129
    """Retrieve a single object by its ATT&CK ID."""
130

131
def get_attack_id(self, stix_id: str) -> str | None:
132
    """Get the object's ATT&CK ID."""
133

134
def get_stix_type(self, stix_id: str) -> str:
135
    """Get the object's STIX type."""
136

137
def get_name(self, stix_id: str) -> str | None:
138
    """Get the object's name."""
139
```
140

141
### Group-Software Relationships
142

143
Map relationships between threat groups and software tools.
144

145
```python { .api }
146
def get_all_software_used_by_all_groups(self) -> RelationshipMapT[Software]:
147
    """Retrieve all software used by all groups."""
148

149
def get_software_used_by_group(self, group_stix_id: str) -> list[RelationshipEntry[Software]]:
150
    """Get all software used by a group."""
151

152
def get_all_groups_using_all_software(self) -> RelationshipMapT[Group]:
153
    """Get all groups using all software."""
154

155
def get_groups_using_software(self, software_stix_id: str) -> list[RelationshipEntry[Group]]:
156
    """Get all groups using a software."""
157
```
158

159
### Group-Technique Relationships
160

161
Map relationships between threat groups and attack techniques.
162

163
```python { .api }
164
def get_all_techniques_used_by_all_groups(self) -> RelationshipMapT[Technique]:
165
    """Get all techniques used by all groups."""
166

167
def get_techniques_used_by_group(self, group_stix_id: str) -> list[RelationshipEntry[Technique]]:
168
    """Get all techniques used by a group."""
169

170
def get_all_groups_using_all_techniques(self) -> RelationshipMapT[Group]:
171
    """Get all groups using all techniques."""
172

173
def get_groups_using_technique(self, technique_stix_id: str) -> list[RelationshipEntry[Group]]:
174
    """Get all groups using a technique."""
175
```
176

177
### Software-Technique Relationships
178

179
Map relationships between software tools and attack techniques.
180

181
```python { .api }
182
def get_all_techniques_used_by_all_software(self) -> RelationshipMapT[Technique]:
183
    """Get all techniques used by all software."""
184

185
def get_techniques_used_by_software(self, software_stix_id: str) -> list[RelationshipEntry[Technique]]:
186
    """Get all techniques used by a software."""
187

188
def get_all_software_using_all_techniques(self) -> RelationshipMapT[Software]:
189
    """Get all software using all techniques."""
190

191
def get_software_using_technique(self, technique_stix_id: str) -> list[RelationshipEntry[Software]]:
192
    """Get all software using a technique."""
193
```
194

195
### Mitigation Relationships
196

197
Map relationships between techniques and their mitigations.
198

199
```python { .api }
200
def get_all_techniques_mitigated_by_all_mitigations(self) -> RelationshipMapT[Technique]:
201
    """Get all techniques mitigated by all mitigations."""
202

203
def get_techniques_mitigated_by_mitigation(self, mitigation_stix_id: str) -> list[RelationshipEntry[Technique]]:
204
    """Get all techniques being mitigated by a mitigation."""
205

206
def get_all_mitigations_mitigating_all_techniques(self) -> RelationshipMapT[Mitigation]:
207
    """Get all mitigations mitigating all techniques."""
208

209
def get_mitigations_mitigating_technique(self, technique_stix_id: str) -> list[RelationshipEntry[Mitigation]]:
210
    """Get all mitigations mitigating a technique."""
211
```
212

213
### Detection Relationships
214

215
Map relationships between techniques and data sources/components that can detect them.
216

217
```python { .api }
218
def get_all_techniques_detected_by_all_datacomponents(self) -> RelationshipMapT[Technique]:
219
    """Get all techniques detected by all data components."""
220

221
def get_techniques_detected_by_datacomponent(self, datacomponent_stix_id: str) -> list[RelationshipEntry[Technique]]:
222
    """Get all techniques detected by a data component."""
223

224
def get_all_datacomponents_detecting_all_techniques(self) -> RelationshipMapT[DataComponent]:
225
    """Get all data components detecting all techniques."""
226

227
def get_datacomponents_detecting_technique(self, technique_stix_id: str) -> list[RelationshipEntry[DataComponent]]:
228
    """Get all data components detecting a technique."""
229
```
230

231
### Campaign Relationships
232

233
Map relationships between campaigns and techniques/software.
234

235
```python { .api }
236
def get_all_techniques_used_by_all_campaigns(self) -> RelationshipMapT[Technique]:
237
    """Get all techniques used by all campaigns."""
238

239
def get_techniques_used_by_campaign(self, campaign_stix_id: str) -> list[RelationshipEntry[Technique]]:
240
    """Get all techniques used by a campaign."""
241

242
def get_all_campaigns_using_all_techniques(self) -> RelationshipMapT[Campaign]:
243
    """Get all campaigns using all techniques."""
244

245
def get_campaigns_using_technique(self, technique_stix_id: str) -> list[RelationshipEntry[Campaign]]:
246
    """Get all campaigns using a technique."""
247

248
def get_all_software_used_by_all_campaigns(self) -> RelationshipMapT[Software]:
249
    """Get all software used by all campaigns."""
250

251
def get_software_used_by_campaign(self, campaign_stix_id: str) -> list[RelationshipEntry[Software]]:
252
    """Get all software used by a campaign."""
253

254
def get_all_campaigns_using_all_software(self) -> RelationshipMapT[Campaign]:
255
    """Get all campaigns using all software."""
256

257
def get_campaigns_using_software(self, software_stix_id: str) -> list[RelationshipEntry[Campaign]]:
258
    """Get all campaigns using a software."""
259

260
def get_all_groups_attributing_to_all_campaigns(self) -> RelationshipMapT[Group]:
261
    """Get all groups attributing to all campaigns."""
262

263
def get_groups_attributing_to_campaign(self, campaign_stix_id: str) -> list[RelationshipEntry[Group]]:
264
    """Get all groups attributing to a campaign."""
265

266
def get_all_campaigns_attributed_to_all_groups(self) -> RelationshipMapT[Campaign]:
267
    """Get all campaigns attributed to all groups."""
268

269
def get_campaigns_attributed_to_group(self, group_stix_id: str) -> list[RelationshipEntry[Campaign]]:
270
    """Get all campaigns attributed to a group."""
271
```
272

273
### Subtechnique and Asset Relationships
274

275
Map relationships between techniques and subtechniques, and techniques and assets.
276

277
```python { .api }
278
def get_all_parent_techniques_of_all_subtechniques(self) -> RelationshipMapT[Technique]:
279
    """Get all parent techniques of all sub-techniques."""
280

281
def get_parent_technique_of_subtechnique(self, subtechnique_stix_id: str) -> list[RelationshipEntry[Technique]]:
282
    """Get the parent technique of a sub-technique."""
283

284
def get_all_subtechniques_of_all_techniques(self) -> RelationshipMapT[Technique]:
285
    """Get all subtechniques of all parent techniques."""
286

287
def get_subtechniques_of_technique(self, technique_stix_id: str) -> list[RelationshipEntry[Technique]]:
288
    """Get all subtechniques of a technique."""
289

290
def get_all_techniques_targeting_all_assets(self) -> RelationshipMapT[Technique]:
291
    """Get all techniques targeting all assets."""
292

293
def get_techniques_targeting_asset(self, asset_stix_id: str) -> list[RelationshipEntry[Technique]]:
294
    """Get all techniques targeting an asset."""
295

296
def get_all_assets_targeted_by_all_techniques(self) -> RelationshipMapT[Asset]:
297
    """Get all assets targeted by all techniques."""
298

299
def get_assets_targeted_by_technique(self, technique_stix_id: str) -> list[RelationshipEntry[Asset]]:
300
    """Get all assets targeted by a technique."""
301
```
302

303
### Alias-Based Retrieval
304

305
Find objects by their known aliases.
306

307
```python { .api }
308
def get_groups_by_alias(self, alias: str) -> list[Group]:
309
    """Retrieve the groups corresponding to a given alias (case sensitive)."""
310

311
def get_campaigns_by_alias(self, alias: str) -> list[Campaign]:
312
    """Retrieve the campaigns corresponding to a given alias (case sensitive)."""
313

314
def get_software_by_alias(self, alias: str) -> list[Software]:
315
    """Retrieve the software corresponding to a given alias (case sensitive)."""
316
```
317

318
### Utility and Helper Methods
319

320
Additional utility methods for object handling.
321

322
```python { .api }
323
def remove_revoked_deprecated(self, stix_objects: list[T]) -> list[T]:
324
    """Remove revoked or deprecated objects from queries made to the data source."""
325

326
def get_procedure_examples_by_technique(self, stix_id: str) -> list[Relationship]:
327
    """Retrieve the list of procedure examples by technique."""
328

329
def get_techniques_used_by_group_software(self, group_stix_id: str) -> list[Technique]:
330
    """Get techniques used by a group's software (indirect technique usage)."""
331

332
def get_revoking_object(self, revoked_stix_id: str = "") -> AttackStixObject | None:
333
    """Given the STIX ID of a revoked object, retrieve the STIX object that replaced it."""
334

335
@staticmethod
336
def get_field(obj, field, default=None) -> Any:
337
    """Get a field from a dict or object."""
338

339
def print_stix_object(self, obj: AttackStixObject, pretty: bool = True) -> None:
340
    """Print a STIX object."""
341
```
342

343
## Types and Custom STIX Objects
344

345
The library defines custom STIX objects and types for ATT&CK-specific data types.
346

347
```python { .api }
348
# Type Definitions
349
AttackStixObject = Union[CustomStixObject, stix2.v20.sdo._DomainObject]
350

351
Technique = stix2.v20.sdo.AttackPattern
352
Malware = stix2.v20.sdo.Malware
353
Tool = stix2.v20.sdo.Tool
354
Software = Malware | Tool
355
Group = stix2.v20.sdo.IntrusionSet
356
Campaign = stix2.v20.sdo.Campaign
357
Mitigation = stix2.v20.sdo.CourseOfAction
358
Relationship = stix2.v20.sro.Relationship
359

360
class RelationshipEntry(TypedDict, Generic[T]):
361
    """Represents a relationship entry mapping an object to its relationships."""
362
    object: T
363
    relationships: list[Relationship]
364

365
RelationshipMapT = dict[str, list[RelationshipEntry[T]]]
366

367
# Custom STIX Objects
368
class Asset:
369
    """Custom STIX object for ATT&CK Assets."""
370

371
class DataComponent:
372
    """Custom STIX object for ATT&CK Data Components."""
373

374
class DataSource:
375
    """Custom STIX object for ATT&CK Data Sources."""
376

377
class Matrix:
378
    """Custom STIX object for ATT&CK Matrices."""
379

380
class Tactic:
381
    """Custom STIX object for ATT&CK Tactics."""
382

383
class StixObjectFactory:
384
    """Factory for creating custom STIX objects."""
385
    @staticmethod
386
    def create_object(stix_type: str, **kwargs) -> object:
387
        """Create custom STIX object of specified type."""
388
```
389

390
## Usage Examples
391

392
### Basic Querying
393

394
```python
395
from mitreattack.stix20 import MitreAttackData
396

397
# Initialize data
398
attack_data = MitreAttackData("enterprise-attack")
399

400
# Get all techniques and print count
401
techniques = attack_data.get_techniques()
402
print(f"Total techniques: {len(techniques)}")
403

404
# Find specific technique
405
process_injection = attack_data.get_object_by_attack_id("T1055")
406
print(f"Technique: {attack_data.get_name(process_injection)}")
407

408
# Get techniques for Windows platform
409
windows_techniques = attack_data.get_techniques_by_platform("Windows")
410
print(f"Windows techniques: {len(windows_techniques)}")
411
```
412

413
### Relationship Analysis
414

415
```python
416
# Analyze group capabilities
417
groups = attack_data.get_groups()
418
for group in groups[:5]:  # First 5 groups
419
    group_name = attack_data.get_name(group)
420
    group_techniques = attack_data.get_techniques_used_by_group(group)
421
    group_software = attack_data.get_software_used_by_group(group)
422
    
423
    print(f"{group_name}:")
424
    print(f"  Techniques: {len(group_techniques)}")
425
    print(f"  Software: {len(group_software)}")
426

427
# Find detection coverage
428
detection_mapping = attack_data.get_all_datacomponents_detecting_all_techniques()
429
covered_techniques = len(detection_mapping)
430
total_techniques = len(attack_data.get_techniques())
431
print(f"Detection coverage: {covered_techniques}/{total_techniques} techniques")
432
```