0
# Prowler
1

2
Prowler is an open-source cloud security assessment tool that performs comprehensive security audits across AWS, Azure, GCP, Kubernetes, GitHub, and Microsoft 365 environments. It provides hundreds of security checks aligned with industry compliance frameworks including CIS benchmarks, NIST, PCI-DSS, GDPR, HIPAA, and SOC2, enabling automated security assessments, continuous monitoring, and compliance validation for cloud infrastructures.
3

4
## Package Information
5

6
- **Package Name**: prowler
7
- **Language**: Python
8
- **Installation**: `pip install prowler`
9
- **Repository**: https://github.com/prowler-cloud/prowler
10
- **Documentation**: https://docs.prowler.cloud
11

12
## Core Imports
13

14
```python
15
import prowler
16
```
17

18
Main CLI entry point:
19

20
```python
21
from prowler.__main__ import prowler
22
```
23

24
Core check execution:
25

26
```python
27
from prowler.lib.check.check import execute_checks
28
from prowler.lib.check.checks_loader import load_checks_to_execute
29
from prowler.lib.check.models import CheckMetadata, Severity
30
from prowler.lib.outputs.finding import Finding
31
```
32

33
Provider management:
34

35
```python
36
from prowler.providers.aws.aws_provider import AWSProvider
37
from prowler.providers.azure.azure_provider import AzureProvider
38
from prowler.providers.gcp.gcp_provider import GCPProvider
39
from prowler.providers.common.provider import Provider
40
```
41

42
Configuration and compliance:
43

44
```python
45
from prowler.config.config import (
46
    prowler_version,
47
    get_available_compliance_frameworks,
48
    available_compliance_frameworks,
49
    available_output_formats,
50
    default_output_directory
51
)
52
```
53

54
Logging:
55

56
```python
57
from prowler.lib.logger import logger, set_logging_config
58
```
59

60
## Basic Usage
61

62
### CLI Usage
63

64
```python
65
from prowler.__main__ import prowler
66

67
# Run prowler CLI with arguments
68
import sys
69
sys.argv = ['prowler', 'aws', '--region', 'us-east-1']
70
prowler()
71
```
72

73
### Programmatic Usage
74

75
```python
76
from prowler.lib.check.check import execute_checks
77
from prowler.lib.check.checks_loader import load_checks_to_execute
78
from prowler.providers.aws.aws_provider import AWSProvider
79
from prowler.lib.outputs.finding import Finding
80

81
# Initialize AWS provider with authentication
82
provider = AWSProvider(
83
    profile="default",
84
    regions={"us-east-1", "us-west-2"},
85
    resource_tags=["Environment=production"]
86
)
87

88
# Load checks for execution
89
checks = load_checks_to_execute(provider, check_list=['iam_user_mfa_enabled'])
90

91
# Execute security checks
92
findings = execute_checks(checks, provider)
93

94
# Process findings
95
for finding in findings:
96
    if finding.status == 'FAIL':
97
        print(f"Failed check: {finding.metadata.CheckID}")
98
        print(f"Resource: {finding.resource_uid}")
99
        print(f"Description: {finding.metadata.Description}")
100
```
101

102
### Provider Authentication Examples
103

104
```python
105
from prowler.providers.aws.aws_provider import AWSProvider
106
from prowler.providers.azure.azure_provider import AzureProvider
107
from prowler.providers.gcp.gcp_provider import GCPProvider
108

109
# AWS with IAM role assumption
110
aws_provider = AWSProvider(
111
    role_arn="arn:aws:iam::123456789012:role/ProwlerRole",
112
    external_id="unique-external-id",
113
    regions={"us-east-1", "eu-west-1"}
114
)
115

116
# Azure with service principal
117
azure_provider = AzureProvider(
118
    client_id="12345678-1234-1234-1234-123456789012",
119
    client_secret="your-client-secret",
120
    tenant_id="87654321-4321-4321-4321-210987654321",
121
    subscription_ids=["sub-1", "sub-2"]
122
)
123

124
# GCP with service account
125
gcp_provider = GCPProvider(
126
    credentials_file="/path/to/service-account.json",
127
    project_ids=["project-1", "project-2"],
128
    organization_id="123456789012"
129
)
130
```
131

132
## Architecture
133

134
Prowler follows a modular architecture organized around key components:
135

136
- **Providers**: Cloud platform abstractions (AWS, Azure, GCP, Kubernetes, GitHub, M365) implementing a common Provider interface
137
- **Checks**: Security assessment modules organized by service and compliance framework
138
- **Findings**: Standardized result objects representing security check outcomes
139
- **Outputs**: Multiple output formats (JSON, CSV, HTML, ASFF, OCSF) with compliance reporting
140
- **Compliance**: Framework mappings linking checks to industry standards and regulations
141

142
This design enables Prowler to scale across multiple cloud platforms while maintaining consistent security assessment patterns and supporting extensive compliance reporting requirements.
143

144
## Capabilities
145

146
### CLI Interface and Main Entry Point
147

148
Main command-line interface providing comprehensive cloud security scanning with support for multiple providers, filtering options, compliance frameworks, and output formats.
149

150
```python { .api }
151
def prowler():
152
    """
153
    Main CLI entry point that orchestrates the entire scanning process.
154
    Uses sys.argv for command-line argument parsing.
155
    
156
    Returns:
157
    None (exits with appropriate status code)
158
    """
159
```
160

161
[CLI Interface](./cli-interface.md)
162

163
### Check Management and Execution
164

165
Core functionality for loading, filtering, and executing security checks across cloud providers with support for custom checks, service filtering, and compliance framework mapping.
166

167
```python { .api }
168
def execute_checks(checks: list, provider: Provider) -> list[Finding]:
169
    """
170
    Execute security checks and return findings.
171
    
172
    Parameters:
173
    - checks: List of check modules to execute
174
    - provider: Provider instance (AWS, Azure, GCP, etc.)
175
    
176
    Returns:
177
    List of Finding objects representing check results
178
    """
179

180
def load_checks_to_execute(provider: Provider, check_list: list = None, service_list: list = None) -> list:
181
    """
182
    Load checks based on provider and filtering criteria.
183
    
184
    Parameters:
185
    - provider: Provider instance
186
    - check_list: Optional list of specific checks to run
187
    - service_list: Optional list of services to include
188
    
189
    Returns:
190
    List of check modules to execute
191
    """
192
```
193

194
[Check Management](./check-management.md)
195

196
### Check Metadata and Models
197

198
Standardized data models for representing security check metadata, severity levels, remediation information, and compliance mappings using Pydantic for validation.
199

200
```python { .api }
201
class CheckMetadata:
202
    """
203
    Pydantic model for check metadata.
204
    
205
    Attributes:
206
    - Provider: str - Provider type (aws, azure, gcp, etc.)
207
    - CheckID: str - Unique check identifier
208
    - CheckTitle: str - Human-readable check name
209
    - CheckType: list[str] - Check categories
210
    - ServiceName: str - Cloud service name
211
    - SubServiceName: str - Sub-service name
212
    - Severity: Severity - Severity level enum
213
    - ResourceType: str - Resource type being checked
214
    - Description: str - Check description
215
    - Risk: str - Risk description
216
    - Remediation: Remediation - Remediation information
217
    """
218

219
class Severity(Enum):
220
    """Severity level enumeration."""
221
    critical = "critical"
222
    high = "high"
223
    medium = "medium"  
224
    low = "low"
225
    informational = "informational"
226
```
227

228
[Check Models](./check-models.md)
229

230
### Finding Management and Output
231

232
Comprehensive finding representation and output generation supporting multiple formats (JSON, CSV, HTML, ASFF, OCSF) with compliance reporting and integration capabilities.
233

234
```python { .api }
235
class Finding:
236
    """
237
    Pydantic model representing a security finding.
238
    
239
    Attributes:
240
    - auth_method: str - Authentication method used
241
    - timestamp: datetime - Finding timestamp
242
    - account_uid: str - Account unique identifier
243
    - metadata: CheckMetadata - Check metadata
244
    - status: Status - Finding status (PASS/FAIL/MANUAL)
245
    - resource_uid: str - Resource unique identifier
246
    - region: str - Cloud region
247
    - compliance: dict - Compliance framework mappings
248
    """
249

250
def generate_output(findings: list[Finding], output_format: str, output_directory: str):
251
    """
252
    Generate output in specified format.
253
    
254
    Parameters:
255
    - findings: List of Finding objects
256
    - output_format: Output format (json, csv, html, asff, ocsf)
257
    - output_directory: Directory for output files
258
    
259
    Returns:
260
    None (writes files to output directory)
261
    """
262
```
263

264
[Finding Management](./finding-management.md)
265

266
### Provider Framework
267

268
Multi-cloud provider abstraction supporting AWS, Azure, GCP, Kubernetes, GitHub, and Microsoft 365 with standardized authentication, session management, and credential handling.
269

270
```python { .api }
271
class Provider:
272
    """
273
    Abstract base class for all cloud providers.
274
    
275
    Properties:
276
    - type: str - Provider type identifier
277
    - identity: dict - Provider identity information
278
    - session: object - Provider session object
279
    - audit_config: dict - Audit configuration
280
    
281
    Methods:
282
    - setup_session(): Abstract method to setup provider session
283
    - print_credentials(): Abstract method to print credential info
284
    - validate_arguments(): Abstract method to validate provider arguments
285
    """
286

287
class AWSProvider(Provider):
288
    """AWS provider implementation."""
289

290
class AzureProvider(Provider):
291
    """Azure provider implementation."""
292

293
class GCPProvider(Provider):
294
    """GCP provider implementation."""
295
```
296

297
[Provider Framework](./provider-framework.md)
298

299
### Configuration and Compliance
300

301
Configuration management and compliance framework support with mappings to industry standards including CIS benchmarks, NIST, ISO 27001, PCI-DSS, and custom frameworks.
302

303
```python { .api }
304
prowler_version: str = "5.10.2"
305
available_compliance_frameworks: list[str]
306
available_output_formats: list[str]
307
default_output_directory: str
308

309
def get_available_compliance_frameworks(provider: str = None) -> list[str]:
310
    """
311
    Get available compliance frameworks for a provider.
312
    
313
    Parameters:
314
    - provider: Optional provider name to filter frameworks
315
    
316
    Returns:
317
    List of available compliance framework names
318
    """
319

320
def check_current_version() -> dict:
321
    """
322
    Check for newer Prowler versions.
323
    
324
    Returns:
325
    Dictionary with version information and update availability
326
    """
327
```
328

329
[Configuration](./configuration.md)
330

331
### Logging and Utilities
332

333
Logging configuration, utility functions, and helper methods for string manipulation, data processing, and common operations across the Prowler ecosystem.
334

335
```python { .api }
336
def set_logging_config(log_level: str, log_file: str = None, only_logs: bool = False):
337
    """
338
    Configure logging for Prowler.
339
    
340
    Parameters:
341
    - log_level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
342
    - log_file: Optional log file path
343
    - only_logs: Whether to suppress banner and only show logs
344
    
345
    Returns:
346
    None
347
    """
348

349
logger: Logger  # Global logger instance
350
logging_levels: dict[str, int]  # Mapping of level names to constants
351
```
352

353
[Logging and Utilities](./logging-utilities.md)
354

355
## Types
356

357
```python { .api }
358
from enum import Enum
359
from typing import Optional, List, Dict, Any
360
from pydantic import BaseModel
361
from datetime import datetime
362

363
class Status(Enum):
364
    """Finding status enumeration."""
365
    PASS = "PASS"
366
    FAIL = "FAIL"
367
    MANUAL = "MANUAL"
368

369
class Provider(Enum):
370
    """Supported provider enumeration."""
371
    aws = "aws"
372
    azure = "azure"
373
    gcp = "gcp"
374
    kubernetes = "kubernetes"
375
    github = "github"
376
    m365 = "m365"
377
    nhn = "nhn"
378
    iac = "iac"
379

380
class Code(BaseModel):
381
    """Remediation code model."""
382
    NativeIaC: Optional[str] = None
383
    Terraform: Optional[str] = None
384
    CLI: Optional[str] = None
385
    Other: Optional[str] = None
386

387
class Recommendation(BaseModel):
388
    """Recommendation model."""
389
    Text: str
390
    Url: Optional[str] = None
391

392
class Remediation(BaseModel):
393
    """Remediation information model."""
394
    Code: Optional[Code] = None
395
    Recommendation: Recommendation
396
```