0
# Configuration and Options
1

2
Comprehensive configuration system for customizing STIX validation behavior, including version selection, strictness levels, custom schema directories, and selective enabling/disabling of validation checks.
3

4
## Capabilities
5

6
### ValidationOptions Class
7

8
Central configuration class that controls all aspects of STIX validation behavior, supporting both programmatic configuration and command-line argument parsing.
9

10
```python { .api }
11
class ValidationOptions:
12
    """
13
    Collection of validation options which can be set via command line or programmatically in a script.
14
    
15
    Parameters:
16
    - cmd_args (argparse.Namespace, optional): Command line arguments from argparse
17
    - version (str, optional): STIX specification version to validate against ("2.0" or "2.1")
18
    - verbose (bool): Enable verbose output with detailed error messages (default: False)
19
    - silent (bool): Suppress all output to stdout (default: False)
20
    - files (List[str], optional): List of input files and directories to validate
21
    - recursive (bool): Recursively search directories for JSON files (default: False)
22
    - schema_dir (str, optional): Custom schema directory path for validation
23
    - disabled (str): Comma-separated list of "SHOULD" check codes to disable (default: "")
24
    - enabled (str): Comma-separated list of "SHOULD" check codes to enable (default: "")
25
    - strict (bool): Treat "SHOULD" recommendations as errors instead of warnings (default: False)
26
    - strict_types (bool): Disallow custom object types (default: False)
27
    - strict_properties (bool): Disallow custom properties (default: False)
28
    - enforce_refs (bool): Ensure referenced objects are in the same bundle (default: False)
29
    - interop (bool): Enable interoperability validation settings (default: False)
30
    - no_cache (bool): Disable caching of external source values (default: False)
31
    - refresh_cache (bool): Clear cache and download fresh external values (default: False)
32
    - clear_cache (bool): Clear external source cache after validation (default: False)
33
    
34
    Methods:
35
    - set_check_codes(version=None): Configure which validation checks are enabled/disabled
36
    """
37
    
38
    def __init__(self, cmd_args=None, version=None, verbose=False, silent=False, 
39
                 files=None, recursive=False, schema_dir=None, disabled="", 
40
                 enabled="", strict=False, strict_types=False, 
41
                 strict_properties=False, enforce_refs=False, interop=False,
42
                 no_cache=False, refresh_cache=False, clear_cache=False):
43
        pass
44
    
45
    def set_check_codes(self, version=None):
46
        """
47
        Set which checks are enabled/disabled based on version and configuration.
48
        
49
        Parameters:
50
        - version (str, optional): STIX version to configure checks for
51
        """
52
        pass
53
```
54

55
**Example Usage:**
56

57
```python
58
from stix2validator import ValidationOptions, validate_file
59

60
# Basic configuration
61
options = ValidationOptions(
62
    version="2.1",
63
    verbose=True
64
)
65

66
# Strict validation configuration
67
strict_options = ValidationOptions(
68
    version="2.1",
69
    strict=True,
70
    strict_types=True,
71
    strict_properties=True,
72
    enforce_refs=True
73
)
74

75
# Custom schema validation
76
custom_options = ValidationOptions(
77
    schema_dir="/path/to/custom/schemas",
78
    version="2.1"
79
)
80

81
# Selective check configuration
82
selective_options = ValidationOptions(
83
    version="2.1",
84
    disabled="101,102",  # Disable custom prefix checks
85
    enabled="1,2,3"      # Enable specific check categories
86
)
87

88
# Use options with validation
89
results = validate_file("stix_document.json", strict_options)
90
```
91

92
### Command Line Argument Parsing
93

94
Converts command line arguments into ValidationOptions objects, enabling integration with command-line tools and scripts.
95

96
```python { .api }
97
def parse_args(cmd_args, is_script=False):
98
    """
99
    Parses a list of command line arguments into a ValidationOptions object.
100
    
101
    Parameters:
102
    - cmd_args (List[str]): The list of command line arguments to be parsed
103
    - is_script (bool): Whether arguments are for standalone script or imported tool (default: False)
104
    
105
    Returns:
106
    ValidationOptions: Configured ValidationOptions instance
107
    
108
    Raises:
109
    SystemExit: If invalid arguments are provided (argparse behavior)
110
    """
111
```
112

113
**Example Usage:**
114

115
```python
116
import sys
117
from stix2validator import parse_args, run_validation
118

119
# Parse command line arguments
120
options = parse_args(sys.argv[1:], is_script=True)
121

122
# Run validation with parsed options
123
results = run_validation(options)
124

125
# Example command line arguments that would be parsed:
126
# ["--version", "2.1", "--strict", "--verbose", "stix_files/", "--recursive"]
127
cmd_args = ["--version", "2.1", "--strict", "--verbose", "stix_files/", "--recursive"]
128
options = parse_args(cmd_args)
129

130
print(f"Version: {options.version}")
131
print(f"Strict mode: {options.strict}")
132
print(f"Verbose: {options.verbose}")
133
print(f"Files: {options.files}")
134
print(f"Recursive: {options.recursive}")
135
```
136

137
## Configuration Options
138

139
### Version Selection
140

141
```python
142
# STIX 2.0 validation
143
options_2_0 = ValidationOptions(version="2.0")
144

145
# STIX 2.1 validation (default)
146
options_2_1 = ValidationOptions(version="2.1")
147

148
# Default version constant
149
from stix2validator.util import DEFAULT_VER
150
print(f"Default STIX version: {DEFAULT_VER}")  # "2.1"
151
```
152

153
### Output Control
154

155
```python
156
# Verbose output with detailed messages
157
verbose_options = ValidationOptions(verbose=True)
158

159
# Silent mode - no stdout output
160
silent_options = ValidationOptions(silent=True)
161

162
# Normal output (default)
163
normal_options = ValidationOptions(verbose=False, silent=False)
164
```
165

166
### Strictness Levels
167

168
```python
169
# Relaxed validation (warnings only for SHOULD requirements)
170
relaxed_options = ValidationOptions(strict=False)
171

172
# Strict validation (SHOULD requirements become errors)
173
strict_options = ValidationOptions(strict=True)
174

175
# Strict type checking (no custom object types)
176
type_strict_options = ValidationOptions(strict_types=True)
177

178
# Strict property checking (no custom properties)
179
property_strict_options = ValidationOptions(strict_properties=True)
180

181
# Reference enforcement (all referenced objects must be in bundle)
182
ref_strict_options = ValidationOptions(enforce_refs=True)
183

184
# All strict options combined
185
full_strict_options = ValidationOptions(
186
    strict=True,
187
    strict_types=True,
188
    strict_properties=True,
189
    enforce_refs=True
190
)
191
```
192

193
### Check Code Management
194

195
```python
196
# Disable specific validation checks
197
disabled_checks = ValidationOptions(
198
    disabled="101,102,111",  # Disable custom prefix and vocab checks
199
    version="2.1"
200
)
201

202
# Enable only specific checks
203
enabled_checks = ValidationOptions(
204
    enabled="1,2",  # Enable only format and approved-values categories
205
    version="2.1"
206
)
207

208
# Combined enable/disable
209
selective_checks = ValidationOptions(
210
    enabled="1,2,3",      # Enable categories 1, 2, 3
211
    disabled="101,121",   # But disable specific checks 101, 121
212
    version="2.1"
213
)
214
```
215

216
### File Processing Options
217

218
```python
219
# Single file validation
220
single_file_options = ValidationOptions(
221
    files=["single_document.json"]
222
)
223

224
# Multiple files and directories
225
multi_file_options = ValidationOptions(
226
    files=["file1.json", "stix_directory/", "file2.json"],
227
    recursive=True  # Search directories recursively
228
)
229

230
# Directory-only with recursion
231
directory_options = ValidationOptions(
232
    files=["stix_files/", "indicators/"],
233
    recursive=True
234
)
235
```
236

237
### Custom Schema Support
238

239
```python
240
# Use custom schema directory
241
custom_schema_options = ValidationOptions(
242
    schema_dir="/path/to/custom/stix/schemas",
243
    version="2.1"
244
)
245

246
# Interoperability mode with specific schema handling
247
interop_options = ValidationOptions(
248
    interop=True,
249
    version="2.1"
250
)
251
```
252

253
## Advanced Configuration Examples
254

255
### Enterprise Validation Pipeline
256

257
```python
258
from stix2validator import ValidationOptions, run_validation
259

260
# Configure for enterprise threat intelligence pipeline
261
enterprise_options = ValidationOptions(
262
    version="2.1",
263
    strict=True,
264
    strict_types=False,      # Allow custom threat types
265
    strict_properties=True,  # But enforce standard properties
266
    enforce_refs=True,       # Ensure bundle consistency
267
    disabled="102",          # Allow more flexible custom prefixes
268
    verbose=True,
269
    files=["intel_feeds/", "threat_reports/"],
270
    recursive=True
271
)
272

273
results = run_validation(enterprise_options)
274

275
# Process results for enterprise reporting
276
for result in results:
277
    if not result.is_valid:
278
        # Enterprise-specific error handling
279
        handle_validation_failure(result)
280
```
281

282
### Research Environment Configuration
283

284
```python
285
# Configure for cybersecurity research with flexibility
286
research_options = ValidationOptions(
287
    version="2.1",
288
    strict=False,           # Allow warnings for experimental data
289
    strict_types=False,     # Allow custom object types for research
290
    strict_properties=False, # Allow custom properties for extended attributes
291
    enforce_refs=False,     # Allow cross-bundle references
292
    enabled="1,2",          # Basic format and value checks only
293
    verbose=True
294
)
295
```
296

297
### Production Validation Configuration
298

299
```python
300
# High-security production environment
301
production_options = ValidationOptions(
302
    version="2.1",
303
    strict=True,
304
    strict_types=True,
305
    strict_properties=True,
306
    enforce_refs=True,
307
    silent=False,  # Log validation results
308
    verbose=False  # But keep output concise
309
)
310
```