0
# Version Management and Data Download
1

2
Download specific ATT&CK releases, manage version information, and access historical ATT&CK data. This module provides comprehensive tools for managing different versions of ATT&CK data, downloading from official sources, and working with version-specific datasets for analysis and comparison.
3

4
## Capabilities
5

6
### Data Download Functions
7

8
Core functions for downloading ATT&CK STIX data from official sources.
9

10
```python { .api }
11
def download_stix(stix_version: str, domain: str, download_dir: str, release: str, known_hash: str) -> str:
12
    """
13
    Download specific ATT&CK release data.
14
    
15
    Args:
16
        stix_version (str): STIX format version ("2.0" or "2.1")
17
        domain (str): ATT&CK domain ("enterprise-attack", "mobile-attack", "ics-attack")
18
        download_dir (str): Directory to save downloaded files
19
        release (str): Specific ATT&CK version to download (e.g., "14.1")
20
        known_hash (str): Expected SHA256 hash for verification
21
        
22
    Returns:
23
        str: Path to downloaded file
24
        
25
    Raises:
26
        ValueError: If hash verification fails
27
        requests.RequestException: If download fails
28
    """
29

30
def download_domains(domains: List[str], download_dir: str, all_versions: bool, 
31
                    stix_version: str, attack_versions: List[str] = None) -> Dict[str, List[str]]:
32
    """
33
    Download multiple ATT&CK domains.
34
    
35
    Args:
36
        domains (List[str]): List of domains to download
37
        download_dir (str): Directory to save downloaded files
38
        all_versions (bool): Whether to download all available versions
39
        stix_version (str): STIX format version
40
        attack_versions (List[str], optional): Specific versions to download
41
        
42
    Returns:
43
        Dict[str, List[str]]: Mapping of domains to downloaded file paths
44
    """
45

46
def download_attack_stix() -> None:
47
    """
48
    Main CLI function for downloading ATT&CK data.
49
    Provides interactive interface for selecting domains, versions, and output locations.
50
    """
51
```
52

53
### Version Information and Constants
54

55
Access version metadata and release information.
56

57
```python { .api }
58
LATEST_VERSION: str = "17.1"
59
"""Current latest ATT&CK version."""
60

61
STIX20: Dict[str, str]
62
"""
63
SHA256 hashes for all STIX 2.0 releases.
64
Keys are version strings, values are SHA256 hashes.
65
"""
66

67
STIX21: Dict[str, str] 
68
"""
69
SHA256 hashes for all STIX 2.1 releases.
70
Keys are version strings, values are SHA256 hashes.
71
"""
72

73
def get_attack_version(domain: str, stix_version: str = "2.0", stix_file: str = None, 
74
                      stix_content: str = None) -> str:
75
    """
76
    Determine ATT&CK version from file content or metadata.
77
    
78
    Args:
79
        domain (str): ATT&CK domain being analyzed
80
        stix_version (str): STIX format version. Defaults to "2.0"
81
        stix_file (str, optional): Path to STIX file to analyze
82
        stix_content (str, optional): Raw STIX content to analyze
83
        
84
    Returns:
85
        str: Detected ATT&CK version (e.g., "14.1")
86
        
87
    Note:
88
        Either stix_file or stix_content must be provided.
89
    """
90
```
91

92
### Version Validation and Verification
93

94
Utilities for validating downloaded data and version integrity.
95

96
```python { .api }
97
def verify_file_hash(filepath: str, expected_hash: str) -> bool:
98
    """
99
    Verify downloaded file integrity using SHA256 hash.
100
    
101
    Args:
102
        filepath (str): Path to file to verify
103
        expected_hash (str): Expected SHA256 hash
104
        
105
    Returns:
106
        bool: True if hash matches, False otherwise
107
    """
108

109
def get_available_versions(stix_version: str) -> List[str]:
110
    """
111
    Get list of all available ATT&CK versions for given STIX format.
112
    
113
    Args:
114
        stix_version (str): STIX format version ("2.0" or "2.1")
115
        
116
    Returns:
117
        List[str]: Sorted list of available version strings
118
    """
119

120
def is_version_available(version: str, stix_version: str) -> bool:
121
    """
122
    Check if specific ATT&CK version is available for download.
123
    
124
    Args:
125
        version (str): ATT&CK version to check
126
        stix_version (str): STIX format version
127
        
128
    Returns:
129
        bool: True if version is available
130
    """
131
```
132

133
## Usage Examples
134

135
### Download Latest ATT&CK Data
136

137
```python
138
from mitreattack.download_stix import download_stix, LATEST_VERSION, STIX20
139

140
# Download latest Enterprise ATT&CK in STIX 2.0 format
141
download_path = download_stix(
142
    stix_version="2.0",
143
    domain="enterprise-attack", 
144
    download_dir="./attack_data/",
145
    release=LATEST_VERSION,
146
    known_hash=STIX20[LATEST_VERSION]
147
)
148

149
print(f"Downloaded: {download_path}")
150
```
151

152
### Download Multiple Domains
153

154
```python
155
from mitreattack.download_stix import download_domains
156

157
# Download multiple domains for specific versions
158
downloaded_files = download_domains(
159
    domains=["enterprise-attack", "mobile-attack", "ics-attack"],
160
    download_dir="./multi_domain_data/",
161
    all_versions=False,
162
    stix_version="2.1", 
163
    attack_versions=["14.1", "15.0", "15.1"]
164
)
165

166
for domain, files in downloaded_files.items():
167
    print(f"{domain}: {len(files)} files downloaded")
168
    for file_path in files:
169
        print(f"  - {file_path}")
170
```
171

172
### Download All Historical Versions
173

174
```python
175
from mitreattack.download_stix import download_domains, get_available_versions
176

177
# Get all available versions
178
available_versions = get_available_versions("2.0")
179
print(f"Available versions: {available_versions}")
180

181
# Download all versions for enterprise domain
182
all_files = download_domains(
183
    domains=["enterprise-attack"],
184
    download_dir="./historical_data/",
185
    all_versions=True,
186
    stix_version="2.0"
187
)
188

189
print(f"Downloaded {len(all_files['enterprise-attack'])} historical versions")
190
```
191

192
### Version Detection and Analysis
193

194
```python
195
from mitreattack.release_info import get_attack_version
196
import json
197

198
# Detect version from downloaded file
199
detected_version = get_attack_version(
200
    domain="enterprise-attack",
201
    stix_version="2.0",
202
    stix_file="./attack_data/enterprise-attack-v14.1.json"
203
)
204

205
print(f"Detected ATT&CK version: {detected_version}")
206

207
# Detect version from raw content
208
with open("./attack_data/enterprise-attack.json", "r") as f:
209
    stix_content = f.read()
210

211
version_from_content = get_attack_version(
212
    domain="enterprise-attack",
213
    stix_version="2.0", 
214
    stix_content=stix_content
215
)
216

217
print(f"Version from content: {version_from_content}")
218
```
219

220
### File Verification and Integrity Checking
221

222
```python
223
from mitreattack.download_stix import verify_file_hash
224
from mitreattack.release_info import STIX20
225

226
# Verify downloaded file integrity
227
file_path = "./attack_data/enterprise-attack-v14.1.json"
228
expected_hash = STIX20["14.1"]
229

230
if verify_file_hash(file_path, expected_hash):
231
    print("File integrity verified - hash matches")
232
else:
233
    print("WARNING: File hash does not match expected value")
234
```
235

236
### Version Availability Checking
237

238
```python
239
from mitreattack.download_stix import get_available_versions, is_version_available
240

241
# Check what versions are available
242
stix20_versions = get_available_versions("2.0")
243
stix21_versions = get_available_versions("2.1")
244

245
print(f"STIX 2.0 versions: {len(stix20_versions)}")
246
print(f"STIX 2.1 versions: {len(stix21_versions)}")
247

248
# Check specific version availability
249
version_to_check = "15.1"
250
if is_version_available(version_to_check, "2.0"):
251
    print(f"Version {version_to_check} is available in STIX 2.0")
252
else:
253
    print(f"Version {version_to_check} is not available in STIX 2.0")
254
```
255

256
### CLI Data Download
257

258
```bash
259
# Interactive download with domain and version selection
260
download_attack_stix
261

262
# Download latest versions of all domains
263
download_attack_stix --domains enterprise-attack mobile-attack ics-attack --latest
264

265
# Download specific versions
266
download_attack_stix --domains enterprise-attack --versions 14.1,15.0,15.1 --stix-version 2.1
267

268
# Download to specific directory
269
download_attack_stix --domains enterprise-attack --output ./my_attack_data/ --latest
270

271
# Download with verification
272
download_attack_stix --domains enterprise-attack --verify-hashes --latest
273
```
274

275
### Automated Version Management Workflow
276

277
```python
278
import os
279
from pathlib import Path
280
from mitreattack.download_stix import download_domains, get_available_versions, verify_file_hash
281
from mitreattack.release_info import STIX20, STIX21
282

283
def setup_attack_data_repository(base_dir: str, stix_version: str = "2.0"):
284
    """
285
    Set up a complete ATT&CK data repository with all versions and domains.
286
    """
287
    base_path = Path(base_dir)
288
    base_path.mkdir(parents=True, exist_ok=True)
289
    
290
    # Get available versions
291
    versions = get_available_versions(stix_version)
292
    print(f"Setting up repository with {len(versions)} versions")
293
    
294
    # Download all domains for all versions
295
    domains = ["enterprise-attack", "mobile-attack", "ics-attack"]
296
    
297
    downloaded_files = download_domains(
298
        domains=domains,
299
        download_dir=str(base_path),
300
        all_versions=True,
301
        stix_version=stix_version
302
    )
303
    
304
    # Verify all downloaded files
305
    hash_dict = STIX20 if stix_version == "2.0" else STIX21
306
    verified_count = 0
307
    
308
    for domain, file_list in downloaded_files.items():
309
        for file_path in file_list:
310
            # Extract version from filename for hash lookup
311
            for version, expected_hash in hash_dict.items():
312
                if version in file_path:
313
                    if verify_file_hash(file_path, expected_hash):
314
                        verified_count += 1
315
                    else:
316
                        print(f"WARNING: Hash mismatch for {file_path}")
317
                    break
318
    
319
    print(f"Repository setup complete:")
320
    print(f"  Total files: {sum(len(files) for files in downloaded_files.values())}")
321
    print(f"  Verified files: {verified_count}")
322
    print(f"  Location: {base_path}")
323
    
324
    return downloaded_files
325

326
# Set up complete ATT&CK data repository
327
repository_files = setup_attack_data_repository("./complete_attack_repo/", "2.0")
328
```
329

330
### Working with Version-Specific Data
331

332
```python
333
from mitreattack.stix20 import MitreAttackData
334
from mitreattack.download_stix import download_stix
335
from mitreattack.release_info import STIX20
336

337
def compare_technique_counts_across_versions(versions: List[str]):
338
    """
339
    Compare technique counts across different ATT&CK versions.
340
    """
341
    results = {}
342
    
343
    for version in versions:
344
        # Download specific version
345
        file_path = download_stix(
346
            stix_version="2.0",
347
            domain="enterprise-attack",
348
            download_dir="./version_comparison/",
349
            release=version,
350
            known_hash=STIX20[version]
351
        )
352
        
353
        # Load and analyze
354
        attack_data = MitreAttackData(file_path)
355
        techniques = attack_data.get_techniques()
356
        subtechniques = attack_data.get_subtechniques()
357
        
358
        results[version] = {
359
            "techniques": len(techniques),
360
            "subtechniques": len(subtechniques),
361
            "total": len(techniques) + len(subtechniques)
362
        }
363
        
364
        print(f"Version {version}: {results[version]['total']} total techniques")
365
    
366
    return results
367

368
# Compare technique evolution
369
versions_to_compare = ["12.1", "13.1", "14.1", "15.1"]
370
comparison_results = compare_technique_counts_across_versions(versions_to_compare)
371

372
for version, counts in comparison_results.items():
373
    print(f"Version {version}: {counts['techniques']} techniques, {counts['subtechniques']} sub-techniques")
374
```