0
# Check Metadata and Models
1

2
Standardized data models for representing security check metadata, severity levels, remediation information, and compliance mappings. These Pydantic models ensure consistent structure and validation across all security checks and findings in the Prowler ecosystem.
3

4
## Capabilities
5

6
### Check Metadata Model
7

8
Comprehensive metadata model for security checks containing all necessary information for execution, reporting, and compliance mapping.
9

10
```python { .api }
11
class CheckMetadata(BaseModel):
12
    """
13
    Model representing the metadata of a check.
14
    
15
    This Pydantic model standardizes how security checks are defined and provides
16
    the foundation for check execution, finding generation, and compliance
17
    reporting across all supported providers.
18
    
19
    Attributes:
20
    - Provider: str - The provider of the check (aws, azure, gcp, kubernetes, etc.)
21
    - CheckID: str - The unique ID of the check
22
    - CheckTitle: str - The human-readable title of the check
23
    - CheckType: list[str] - The type/categories of the check
24
    - CheckAliases: list[str] - Optional aliases for the check (defaults to empty list)
25
    - ServiceName: str - The name of the cloud service
26
    - SubServiceName: str - The name of the sub-service or component
27
    - ResourceIdTemplate: str - The template for the resource ID
28
    - Severity: Severity - The severity level of the check
29
    - ResourceType: str - The type of the resource being checked
30
    - Description: str - The description of the check
31
    - Risk: str - The risk associated with the check
32
    - RelatedUrl: str - The URL related to the check or documentation
33
    - Remediation: Remediation - The remediation steps for the check
34
    - Categories: list[str] - The categories of the check
35
    - DependsOn: list[str] - The dependencies of the check
36
    - RelatedTo: list[str] - The related checks
37
    - Notes: str - Additional notes for the check
38
    - Compliance: Optional[list] - The compliance information for the check (defaults to empty list)
39
    
40
    Validators:
41
    - valid_category(value): Validator function to validate the categories of the check
42
    - severity_to_lower(severity): Validator function to convert the severity to lowercase
43
    - valid_cli_command(remediation): Validator function to validate the CLI command is not a URL
44
    - valid_resource_type(resource_type): Validator function to validate the resource type is not empty
45
    """
46
    
47
    Provider: str
48
    CheckID: str
49
    CheckTitle: str
50
    CheckType: list[str]
51
    CheckAliases: list[str] = []
52
    ServiceName: str
53
    SubServiceName: str
54
    ResourceIdTemplate: str
55
    Severity: Severity
56
    ResourceType: str
57
    Description: str
58
    Risk: str
59
    RelatedUrl: str
60
    Remediation: Remediation
61
    Categories: list[str]
62
    DependsOn: list[str]
63
    RelatedTo: list[str]
64
    Notes: str
65
    # We set the compliance to None to store the compliance later if supplied
66
    Compliance: Optional[list[Any]] = []
67

68
    @validator("Categories", each_item=True, pre=True, always=True)
69
    def valid_category(value):
70
        """
71
        Validate category format - must be lowercase letters, numbers and hyphens only.
72
        
73
        Parameters:
74
        - value: Category string to validate
75
        
76
        Returns:
77
        str: Validated and normalized category value
78
        
79
        Raises:
80
        ValueError: If category format is invalid
81
        """
82
        if not isinstance(value, str):
83
            raise ValueError("Categories must be a list of strings")
84
        value_lower = value.lower()
85
        if not re.match("^[a-z0-9-]+$", value_lower):
86
            raise ValueError(
87
                f"Invalid category: {value}. Categories can only contain lowercase letters, numbers and hyphen '-'"
88
            )
89
        return value_lower
90

91
    @validator("Severity", pre=True, always=True)
92
    def severity_to_lower(severity):
93
        """
94
        Convert severity to lowercase for consistency.
95
        
96
        Parameters:
97
        - severity: Severity value to normalize
98
        
99
        Returns:
100
        str: Lowercase severity value
101
        """
102
        return severity.lower()
103

104
    @validator("Remediation")
105
    def valid_cli_command(remediation):
106
        """
107
        Validate that CLI remediation command is not a URL.
108
        
109
        Parameters:
110
        - remediation: Remediation object to validate
111
        
112
        Returns:
113
        Remediation: Validated remediation object
114
        
115
        Raises:
116
        ValueError: If CLI command is a URL
117
        """
118
        if re.match(r"^https?://", remediation.Code.CLI):
119
            raise ValueError("CLI command cannot be an URL")
120
        return remediation
121

122
    @validator("ResourceType", pre=True, always=True)
123
    def valid_resource_type(resource_type):
124
        """
125
        Validate that resource type is not empty.
126
        
127
        Parameters:
128
        - resource_type: Resource type string to validate
129
        
130
        Returns:
131
        str: Validated resource type
132
        
133
        Raises:
134
        ValueError: If resource type is empty or invalid
135
        """
136
        if not resource_type or not isinstance(resource_type, str):
137
            raise ValueError("ResourceType must be a non-empty string")
138
        return resource_type
139
```
140

141
### Severity Enumeration
142

143
Standardized severity levels for security findings aligned with industry standards.
144

145
```python { .api }
146
class Severity(Enum):
147
    """
148
    Severity level enumeration for security findings.
149
    
150
    Provides standardized severity classification aligned with
151
    industry security frameworks and vulnerability assessment standards.
152
    """
153
    
154
    critical = "critical"    # Immediate action required, severe security risk
155
    high = "high"           # High priority, significant security risk
156
    medium = "medium"       # Medium priority, moderate security risk
157
    low = "low"            # Low priority, minor security risk
158
    informational = "informational"  # Information only, no immediate risk
159
```
160

161
### Remediation Models
162

163
Structured models for representing remediation information including code samples and recommendations.
164

165
```python { .api }
166
class Code(BaseModel):
167
    """
168
    Model for remediation code in various formats.
169
    
170
    Provides code samples for fixing security issues using
171
    different infrastructure management approaches.
172
    
173
    Attributes:
174
    - NativeIaC: str - Native infrastructure-as-code (CloudFormation, ARM, etc.)
175
    - Terraform: str - Terraform configuration code
176
    - CLI: str - Command-line interface commands
177
    - Other: str - Other remediation code formats
178
    """
179
    
180
    NativeIaC: Optional[str] = None
181
    Terraform: Optional[str] = None
182
    CLI: Optional[str] = None
183
    Other: Optional[str] = None
184

185
class Recommendation(BaseModel):
186
    """
187
    Model for remediation recommendations and guidance.
188
    
189
    Provides textual guidance and reference URLs for
190
    understanding and implementing security fixes.
191
    
192
    Attributes:
193
    - Text: str - Detailed remediation guidance text
194
    - Url: str - Reference URL for additional information
195
    """
196
    
197
    Text: str
198
    Url: Optional[str] = None
199

200
class Remediation(BaseModel):
201
    """
202
    Combined remediation information model.
203
    
204
    Contains both code samples and textual recommendations
205
    for comprehensive remediation guidance.
206
    
207
    Attributes:
208
    - Code: Code - Code samples for various platforms
209
    - Recommendation: Recommendation - Textual guidance and references
210
    """
211
    
212
    Code: Optional[Code] = None
213
    Recommendation: Recommendation
214
```
215

216
### Compliance Models
217

218
Models for representing compliance framework mappings and requirements.
219

220
```python { .api }
221
class ComplianceBaseModel(BaseModel):
222
    """
223
    Base model for compliance framework mappings.
224
    
225
    Provides the foundation for mapping security checks to
226
    various compliance frameworks and regulatory requirements.
227
    
228
    Attributes:
229
    - Framework: str - Compliance framework name
230
    - Provider: str - Cloud provider for framework
231
    - Version: str - Framework version
232
    - Description: str - Framework description
233
    - Requirements: list[dict] - Specific compliance requirements
234
    """
235
    
236
    Framework: str
237
    Provider: str
238
    Version: str
239
    Description: str
240
    Requirements: List[Dict[str, Any]] = []
241

242
class Compliance(BaseModel):
243
    """
244
    Main compliance framework model.
245
    
246
    Comprehensive model for representing compliance frameworks
247
    with their associated checks and requirements.
248
    
249
    Attributes:
250
    - Framework: str - Framework identifier
251
    - Provider: str - Provider name
252
    - Version: str - Framework version
253
    - Description: str - Framework description
254
    - Requirements: list - List of compliance requirements
255
    - Checks: dict - Mapping of checks to requirements
256
    """
257
    
258
    Framework: str
259
    Provider: str
260
    Version: str
261
    Description: str
262
    Requirements: List[Dict[str, Any]]
263
    Checks: Dict[str, List[str]]
264
```
265

266
### Custom Check Metadata
267

268
Functions for parsing and updating custom check metadata.
269

270
```python { .api }
271
def parse_custom_checks_metadata_file(metadata_file: str) -> dict:
272
    """
273
    Parse custom checks metadata from file.
274
    
275
    Loads and validates custom check metadata from YAML or JSON
276
    files, ensuring compatibility with the CheckMetadata model.
277
    
278
    Parameters:
279
    - metadata_file: Path to metadata file (YAML or JSON)
280
    
281
    Returns:
282
    Dictionary containing parsed and validated metadata
283
    
284
    Raises:
285
    ProwlerException: On file parsing or validation errors
286
    """
287

288
def update_checks_metadata(
289
    checks_metadata: dict,
290
    custom_metadata: dict
291
) -> dict:
292
    """
293
    Update checks metadata with custom definitions.
294
    
295
    Merges custom check metadata with built-in metadata,
296
    allowing for customization and extension of check behavior.
297
    
298
    Parameters:
299
    - checks_metadata: Built-in checks metadata dictionary
300
    - custom_metadata: Custom metadata to merge
301
    
302
    Returns:
303
    Updated metadata dictionary with custom overrides applied
304
    
305
    Raises:
306
    ProwlerException: On metadata merge conflicts or validation errors
307
    """
308
```
309

310
## Usage Examples
311

312
### Creating Check Metadata
313

314
```python
315
from prowler.lib.check.models import (
316
    CheckMetadata,
317
    Severity,
318
    Remediation,
319
    Recommendation,
320
    Code
321
)
322

323
# Create remediation information
324
code = Code(
325
    CLI="aws iam put-user-policy --user-name <user> --policy-name MFARequired",
326
    Terraform="""
327
resource "aws_iam_user_policy" "mfa_required" {
328
  name = "MFARequired"
329
  user = var.user_name
330
  policy = jsonencode({
331
    Version = "2012-10-17"
332
    Statement = [{
333
      Effect = "Deny"
334
      Action = "*"
335
      Resource = "*"
336
      Condition = {
337
        BoolIfExists = {
338
          "aws:MultiFactorAuthPresent" = "false"
339
        }
340
      }
341
    }]
342
  })
343
}
344
"""
345
)
346

347
recommendation = Recommendation(
348
    Text="Enable MFA for all IAM users to enhance account security",
349
    Url="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa.html"
350
)
351

352
remediation = Remediation(
353
    Code=code,
354
    Recommendation=recommendation
355
)
356

357
# Create check metadata
358
check_metadata = CheckMetadata(
359
    Provider="aws",
360
    CheckID="iam_user_mfa_enabled",
361
    CheckTitle="Ensure MFA is enabled for all IAM users",
362
    CheckType=["Identity and Access Management"],
363
    ServiceName="iam",
364
    SubServiceName="user",
365
    ResourceIdTemplate="arn:aws:iam::account:user/user-name",
366
    Severity=Severity.high,
367
    ResourceType="AwsIamUser",
368
    Description="Checks if MFA is enabled for all IAM users",
369
    Risk="Users without MFA are vulnerable to credential compromise",
370
    RelatedUrl="",
371
    Remediation=remediation,
372
    Categories=["Security", "IAM"],
373
    Compliance=[]
374
)
375
```
376

377
### Working with Severity Levels
378

379
```python
380
from prowler.lib.check.models import Severity
381

382
# Check severity levels
383
critical_checks = []
384
high_priority_checks = []
385

386
for check in all_checks:
387
    if check.metadata.Severity == Severity.critical:
388
        critical_checks.append(check)
389
    elif check.metadata.Severity == Severity.high:
390
        high_priority_checks.append(check)
391

392
# Sort by severity
393
severity_order = {
394
    Severity.critical: 5,
395
    Severity.high: 4,
396
    Severity.medium: 3,
397
    Severity.low: 2,
398
    Severity.informational: 1
399
}
400

401
sorted_checks = sorted(
402
    all_checks,
403
    key=lambda c: severity_order[c.metadata.Severity],
404
    reverse=True
405
)
406
```
407

408
### Custom Metadata Processing
409

410
```python
411
from prowler.lib.check.custom_checks_metadata import (
412
    parse_custom_checks_metadata_file,
413
    update_checks_metadata
414
)
415

416
# Load custom metadata
417
custom_metadata = parse_custom_checks_metadata_file(
418
    '/path/to/custom-checks-metadata.yaml'
419
)
420

421
# Update built-in metadata with customizations
422
updated_metadata = update_checks_metadata(
423
    built_in_metadata,
424
    custom_metadata
425
)
426

427
# Apply updated metadata to checks
428
for check_id, metadata in updated_metadata.items():
429
    if check_id in active_checks:
430
        active_checks[check_id].metadata = CheckMetadata(**metadata)
431
```
432

433
### Compliance Framework Integration
434

435
```python
436
from prowler.lib.check.compliance_models import Compliance
437
from prowler.lib.check.compliance import update_checks_metadata_with_compliance
438

439
# Load compliance framework
440
cis_aws_framework = Compliance(
441
    Framework="CIS",
442
    Provider="aws",
443
    Version="1.5",
444
    Description="CIS Amazon Web Services Foundations Benchmark v1.5.0",
445
    Requirements=[
446
        {
447
            "Id": "1.1",
448
            "Description": "Maintain current contact details",
449
            "Checks": ["account_maintain_current_contact_details"]
450
        }
451
    ],
452
    Checks={
453
        "1.1": ["account_maintain_current_contact_details"],
454
        "1.4": ["iam_user_mfa_enabled"]
455
    }
456
)
457

458
# Update check metadata with compliance mapping
459
compliance_updated_metadata = update_checks_metadata_with_compliance(
460
    checks_metadata,
461
    [cis_aws_framework]
462
)
463
```