0
# Check Management and Execution
1

2
Core functionality for loading, filtering, and executing security checks across cloud providers. This module provides the foundation for Prowler's security assessment capabilities, supporting custom checks, service filtering, compliance framework mapping, and parallel execution.
3

4
## Capabilities
5

6
### Check Execution
7

8
Primary function for executing security checks against cloud resources and collecting findings.
9

10
```python { .api }
11
def execute_checks(
12
    checks: list,
13
    provider: Provider,
14
) -> list[Finding]:
15
    """
16
    Execute security checks and return findings.
17
    
18
    Coordinates the execution of loaded security checks against the configured
19
    provider, collecting results and generating Finding objects for each check.
20
    Handles parallel execution, exception management, and finding generation.
21
    
22
    Parameters:
23
    - checks: list - List of check modules/functions to execute
24
    - provider: Provider - Provider instance (AWS, Azure, GCP, etc.)
25
    
26
    Returns:
27
    list[Finding]: List of Finding objects representing check results with status,
28
    metadata, resource information, and compliance mappings
29
    
30
    Raises:
31
    Exception: On critical check execution errors that cannot be handled
32
    """
33
```
34

35
### Check Loading and Filtering
36

37
Load checks based on provider capabilities and filtering criteria.
38

39
```python { .api }
40
def load_checks_to_execute(
41
    provider: Provider,
42
    check_list: list = None,
43
    service_list: list = None,
44
    severities: list = None,
45
    compliance_frameworks: list = None,
46
    categories: set = None,
47
    checks_file: str = None,
48
    checks_folder: str = None,
49
) -> list:
50
    """
51
    Load checks based on provider and filtering criteria.
52
    
53
    Discovers available checks for the provider and applies various filters
54
    to determine which checks should be executed. This function is imported
55
    from prowler.lib.check.checks_loader module.
56
    
57
    Parameters:
58
    - provider: Provider - Provider instance to load checks for
59
    - check_list: list = None - Optional list of specific check IDs to run
60
    - service_list: list = None - Optional list of services to include
61
    - severities: list = None - Optional list of severity levels to filter by
62
    - compliance_frameworks: list = None - Optional list of compliance frameworks
63
    - categories: set = None - Optional set of check categories to include
64
    - checks_file: str = None - Path to file containing check list
65
    - checks_folder: str = None - Path to folder containing custom checks
66
    
67
    Returns:
68
    list: List of check modules ready for execution
69
    
70
    Raises:
71
    Exception: On check loading or filtering errors
72
    """
73
```
74

75
### Service and Check Exclusion
76

77
Functions for excluding specific checks and services from execution.
78

79
```python { .api }
80
def exclude_checks_to_run(checks_to_execute: set, excluded_checks: list) -> set:
81
    """
82
    Exclude specific checks from execution set.
83
    
84
    Parameters:
85
    - checks_to_execute: set - Set of checks to execute
86
    - excluded_checks: list - List of check IDs to exclude
87
    
88
    Returns:
89
    set: Filtered set of checks with exclusions removed
90
    """
91

92
def exclude_services_to_run(
93
    checks_to_execute: set,
94
    excluded_services: list,
95
    bulk_checks_metadata: dict,
96
) -> set:
97
    """
98
    Exclude checks from specific services.
99
    
100
    Parameters:
101
    - checks_to_execute: set - Set of checks to execute
102
    - excluded_services: list - List of service names to exclude
103
    - bulk_checks_metadata: dict - Bulk check metadata for service mapping
104
    
105
    Returns:
106
    set: Filtered set of checks with service exclusions applied
107
    """
108

109
def parse_checks_from_file(input_file: str, provider: str) -> set:
110
    """
111
    Parse checks from input file.
112
    
113
    Parameters:
114
    - input_file: str - Path to file containing check list
115
    - provider: str - Provider name for validation
116
    
117
    Returns:
118
    set: Set of valid check names from the file
119
    """
120

121
def parse_checks_from_folder(provider, input_folder: str) -> set:
122
    """
123
    Parse custom checks from folder.
124
    
125
    Parameters:
126
    - provider: Provider instance
127
    - input_folder: str - Path to folder containing custom checks
128
    
129
    Returns:
130
    set: Set of custom check names discovered in the folder
131
    """
132

133
def list_services(provider: str) -> set:
134
    """
135
    List available services for a provider.
136
    
137
    Parameters:
138
    - provider: str - Provider name
139
    
140
    Returns:
141
    set: Set of available service names
142
    """
143

144
def list_categories(bulk_checks_metadata: dict) -> set:
145
    """
146
    List available check categories.
147
    
148
    Parameters:
149
    - bulk_checks_metadata: dict - Bulk check metadata
150
    
151
    Returns:
152
    set: Set of available category names
153
    """
154

155
def print_checks(
156
    check_list: list,
157
    bulk_checks_metadata: dict,
158
    output_format: str = "table",
159
) -> None:
160
    """
161
    Print checks in specified format.
162
    
163
    Parameters:
164
    - check_list: list - List of checks to print
165
    - bulk_checks_metadata: dict - Check metadata for details
166
    - output_format: str - Output format ("table", "json", etc.)
167
    
168
    Returns:
169
    None (prints to stdout)
170
    """
171

172
def print_compliance_frameworks(
173
    bulk_compliance_frameworks: dict,
174
    provider: str = None,
175
) -> None:
176
    """
177
    Print available compliance frameworks.
178
    
179
    Parameters:
180
    - bulk_compliance_frameworks: dict - Bulk compliance framework data
181
    - provider: str = None - Optional provider filter
182
    
183
    Returns:
184
    None (prints to stdout)
185
    """
186

187
def run_fixer(check_findings: list) -> int:
188
    """
189
    Run automatic remediation for findings.
190
    
191
    Parameters:
192
    - check_findings: list - List of findings to attempt remediation
193
    
194
    Returns:
195
    int: Number of successfully remediated findings
196
    """
197
    Filtered list of checks with exclusions applied
198
    """
199

200
def exclude_services_to_run(checks: list, excluded_services: list) -> list:
201
    """
202
    Exclude entire services from check execution.
203
    
204
    Parameters:
205
    - checks: List of available checks
206
    - excluded_services: List of service names to exclude
207
    
208
    Returns:
209
    Filtered list of checks with service exclusions applied
210
    """
211
```
212

213
### Check Discovery and Listing
214

215
Functions for discovering and listing available checks, services, and categories.
216

217
```python { .api }
218
def list_checks_json(provider: str, check_list: list = None) -> dict:
219
    """
220
    Export available checks as JSON for programmatic access.
221
    
222
    Parameters:
223
    - provider: Provider name (aws, azure, gcp, etc.)
224
    - check_list: Optional list to filter specific checks
225
    
226
    Returns:
227
    Dictionary containing check metadata organized by service
228
    """
229

230
def list_services(provider: str) -> list[str]:
231
    """
232
    List available services for a provider.
233
    
234
    Parameters:
235
    - provider: Provider name
236
    
237
    Returns:
238
    List of available service names
239
    """
240

241
def list_categories(provider: str) -> list[str]:
242
    """
243
    List available check categories for a provider.
244
    
245
    Parameters:
246
    - provider: Provider name
247
    
248
    Returns:
249
    List of available category names
250
    """
251

252
def list_fixers(provider: str) -> list[str]:
253
    """
254
    List available automatic fixers for a provider.
255
    
256
    Parameters:
257
    - provider: Provider name
258
    
259
    Returns:
260
    List of fixer names for checks that support remediation
261
    """
262
```
263

264
### Check Information Display
265

266
Functions for displaying check information to users.
267

268
```python { .api }
269
def print_checks(
270
    provider: str,
271
    check_list: list = None,
272
    service_list: list = None
273
):
274
    """
275
    Print available checks with metadata.
276
    
277
    Parameters:
278
    - provider: Provider name
279
    - check_list: Optional list to filter specific checks
280
    - service_list: Optional list to filter by services
281
    
282
    Returns:
283
    None (prints to stdout)
284
    """
285

286
def print_services(provider: str):
287
    """
288
    Print available services for a provider.
289
    
290
    Parameters:
291
    - provider: Provider name
292
    
293
    Returns:
294
    None (prints to stdout)
295
    """
296

297
def print_categories(provider: str):
298
    """
299
    Print available check categories.
300
    
301
    Parameters:
302
    - provider: Provider name
303
    
304
    Returns:
305
    None (prints to stdout)
306
    """
307

308
def print_fixers(provider: str):
309
    """
310
    Print available fixers with their associated checks.
311
    
312
    Parameters:
313
    - provider: Provider name
314
    
315
    Returns:
316
    None (prints to stdout)
317
    """
318
```
319

320
### Custom Check Management
321

322
Functions for loading and managing custom security checks.
323

324
```python { .api }
325
def parse_checks_from_folder(custom_checks_folder: str) -> list:
326
    """
327
    Load custom checks from a specified folder.
328
    
329
    Scans the folder for Python modules containing security checks
330
    and loads them for execution alongside built-in checks.
331
    
332
    Parameters:
333
    - custom_checks_folder: Path to folder containing custom check modules
334
    
335
    Returns:
336
    List of loaded custom check modules
337
    
338
    Raises:
339
    ProwlerException: On folder access or module loading errors
340
    """
341

342
def remove_custom_checks_module():
343
    """
344
    Remove custom checks module from system to prevent conflicts.
345
    
346
    Cleans up custom check modules after execution to ensure
347
    they don't interfere with subsequent runs.
348
    
349
    Returns:
350
    None
351
    """
352
```
353

354
### Compliance Framework Integration
355

356
Functions for integrating compliance frameworks with check execution.
357

358
```python { .api }
359
def print_compliance_frameworks(provider: str = None):
360
    """
361
    Print available compliance frameworks.
362
    
363
    Parameters:
364
    - provider: Optional provider name to filter frameworks
365
    
366
    Returns:
367
    None (prints to stdout)
368
    """
369

370
def print_compliance_requirements(
371
    provider: str,
372
    compliance_framework: str
373
):
374
    """
375
    Print requirements for a specific compliance framework.
376
    
377
    Parameters:
378
    - provider: Provider name
379
    - compliance_framework: Framework name (e.g., 'cis_1.5_aws')
380
    
381
    Returns:
382
    None (prints to stdout)
383
    """
384
```
385

386
### Automatic Remediation
387

388
Execute automatic fixes for failed security checks where available.
389

390
```python { .api }
391
def run_fixer(
392
    findings: list[Finding],
393
    provider: Provider,
394
    fixer_list: list = None
395
) -> dict:
396
    """
397
    Run automatic remediation for failed checks.
398
    
399
    Attempts to automatically fix security issues identified by checks
400
    where fixers are available and appropriate.
401
    
402
    Parameters:
403
    - findings: List of Finding objects with failed checks
404
    - provider: Provider instance for executing fixes
405
    - fixer_list: Optional list of specific fixers to run
406
    
407
    Returns:
408
    Dictionary containing fix results and any errors encountered
409
    
410
    Raises:
411
    ProwlerException: On fixer execution errors
412
    """
413
```
414

415
## Usage Examples
416

417
### Basic Check Execution
418

419
```python
420
from prowler.lib.check.check import execute_checks
421
from prowler.lib.check.checks_loader import load_checks_to_execute
422
from prowler.providers.aws.aws_provider import AWSProvider
423

424
# Initialize provider
425
provider = AWSProvider()
426

427
# Load all checks for provider
428
checks = load_checks_to_execute(provider)
429

430
# Execute checks and collect findings
431
findings = execute_checks(checks, provider)
432

433
# Process results
434
for finding in findings:
435
    print(f"Check: {finding.metadata.CheckID}")
436
    print(f"Status: {finding.status}")
437
    print(f"Resource: {finding.resource_uid}")
438
```
439

440
### Filtered Check Execution
441

442
```python
443
from prowler.lib.check.checks_loader import load_checks_to_execute
444
from prowler.providers.azure.azure_provider import AzureProvider
445

446
provider = AzureProvider()
447

448
# Load specific checks only
449
specific_checks = load_checks_to_execute(
450
    provider,
451
    check_list=['storage_account_public_access_disabled', 'vm_disk_encryption_enabled']
452
)
453

454
# Load checks for specific services
455
service_checks = load_checks_to_execute(
456
    provider,
457
    service_list=['storage', 'compute']
458
)
459

460
# Load checks with exclusions
461
filtered_checks = load_checks_to_execute(
462
    provider,
463
    excluded_services=['network'],
464
    excluded_checks=['vm_old_image_version']
465
)
466
```
467

468
### Compliance Framework Filtering
469

470
```python
471
from prowler.lib.check.checks_loader import load_checks_to_execute
472
from prowler.providers.gcp.gcp_provider import GCPProvider
473

474
provider = GCPProvider()
475

476
# Load checks for CIS compliance
477
cis_checks = load_checks_to_execute(
478
    provider,
479
    compliance_frameworks=['cis_1.3_gcp']
480
)
481

482
# Load checks for multiple frameworks
483
multi_compliance_checks = load_checks_to_execute(
484
    provider,
485
    compliance_frameworks=['cis_1.3_gcp', 'nist_csf_1.1_gcp']
486
)
487
```
488

489
### Custom Check Loading
490

491
```python
492
from prowler.lib.check.check import parse_checks_from_folder, execute_checks
493
from prowler.providers.aws.aws_provider import AWSProvider
494

495
provider = AWSProvider()
496

497
# Load custom checks from folder
498
custom_checks = parse_checks_from_folder('/path/to/custom/checks')
499

500
# Execute custom checks
501
findings = execute_checks(custom_checks, provider)
502

503
# Clean up custom modules
504
remove_custom_checks_module()
505
```
506

507
### Information Discovery
508

509
```python
510
from prowler.lib.check.check import (
511
    list_services,
512
    list_categories,
513
    list_checks_json,
514
    print_checks
515
)
516

517
# Get available services for AWS
518
aws_services = list_services('aws')
519
print(f"AWS Services: {aws_services}")
520

521
# Get check categories
522
categories = list_categories('azure')
523
print(f"Azure Categories: {categories}")
524

525
# Export check metadata as JSON
526
check_metadata = list_checks_json('gcp', check_list=['compute_instance_public_ip'])
527

528
# Print formatted check information
529
print_checks('aws', service_list=['iam', 'ec2'])
530
```