Prowler Checks

​

Introduction

​

Creating a Check

1. Prerequisites:
   • Verify the check does not already exist by searching Prowler Hub or checking prowler/providers/<provider>/services/<service>/<check_name_want_to_implement>/.
   • Ensure required provider and service exist. If not, follow the Provider and Service documentation to create them.
   • Confirm the service has implemented all required methods and attributes for the check (in most cases, you will need to add or modify some methods in the service to get the data you need for the check).
2. Navigate to the service directory. The path should be as follows: prowler/providers/<provider>/services/<service>.
3. Create a check-specific folder. The path should follow this pattern: prowler/providers/<provider>/services/<service>/<check_name_want_to_implement>. Adhere to the Naming Format for Checks.
4. Populate the folder with files as specified in File Creation.
5. Run the check locally to ensure it works as expected. For checking you can use the CLI in the next way:
   • To ensure the check has been detected by Prowler: poetry run python prowler-cli.py <provider> --list-checks | grep <check_name>.
   • To run the check, to find possible issues: poetry run python prowler-cli.py <provider> --log-level ERROR --verbose --check <check_name>.
6. Create comprehensive tests for the check that cover multiple scenarios including both PASS (compliant) and FAIL (non-compliant) cases. For detailed information about test structure and implementation guidelines, refer to the Testing documentation.
7. If the check and its corresponding tests are working as expected, you can submit a PR to Prowler.

​

Naming Format for Checks

• service – The main service being audited (e.g., ec2, entra, iam, etc.)
• subservice – An individual component or subset of functionality within the service that is being audited. This may correspond to a shortened version of the class attribute accessed within the check. If there is no subservice, just omit.
• resource – The specific resource type being evaluated (e.g., instance, policy, role, etc.)
• action – The security aspect or configuration being checked (e.g., public, encrypted, enabled, etc.)

​

File Creation

• __init__.py (empty file) – Ensures Python treats the check folder as a package.
• <check_name>.py (code file) – Contains the check logic, following the prescribed format. Please refer to the prowler’s check code structure for more information.
• <check_name>.metadata.json (metadata file) – Defines the check’s metadata for contextual information. Please refer to the check metadata for more information.

​

Prowler’s Check Code Structure

# Required Imports
# Import the base Check class and the provider-specific CheckReport class
from prowler.lib.check.models import Check, CheckReport<Provider>
# Import the provider service client
from prowler.providers.<provider>.services.<service>.<service>_client import <service>_client

# Defining the Check Class
# Each check must be implemented as a Python class with the same name as its corresponding file.
# The class must inherit from the Check base class.
class <check_name>(Check):
    """
    Ensure that <resource> meets <security_requirement>.

    This check evaluates whether <specific_condition> to ensure <security_benefit>.
    - PASS: <description_of_compliant_state(s)>.
    - FAIL: <description_of_non_compliant_state(s)>.
    """

    def execute(self):
        """Execute the check logic.

        Returns:
            A list of reports containing the result of the check.
        """
        findings = []
        # Iterate over the target resources using the provider service client
        for resource in <service>_client.<resources>:
            # Initialize the provider-specific report class, passing metadata and resource
            report = Check_Report_<Provider>(metadata=self.metadata(), resource=resource)
            # Set required fields and implement check logic
            report.status = "PASS"
            report.status_extended = f"<Description about why the resource is compliant>"
            # If some of the information needed for the report is not inside the resource, it can be set it manually here.
            # This depends on the provider and the resource that is being audited.
            # report.region = resource.region
            # report.resource_tags = getattr(resource, "tags", [])
            # ...
            # Example check logic (replace with actual logic):
            if <non_compliant_condition>:
                report.status = "FAIL"
                report.status_extended = f"<Description about why the resource is not compliant>"
            findings.append(report)
        return findings

​

Data Requirements for Checks in Prowler

​

Statuses for Checks in Prowler

• Status field: report.status
  • PASS – Assigned when the check confirms compliance with the configured value.
  • FAIL – Assigned when the check detects non-compliance with the configured value.
  • MANUAL – This status must not be used unless manual verification is necessary to determine whether the status (report.status) passes (PASS) or fails (FAIL).
• Status extended field: report.status_extended
  • It must end with a period (.).
  • It must include the audited service, the resource, and a concise explanation of the check result, for instance: EC2 AMI ami-0123456789 is not public..

​

Prowler’s Check Severity Levels

• critical – Issue that must be addressed immediately.
• high – Issue that should be addressed as soon as possible.
• medium – Issue that should be addressed within a reasonable timeframe.
• low – Issue that can be addressed in the future.
• informational – Not an issue but provides valuable information.

if <generic_condition_1>:
    report.status = "PASS"
    report.check_metadata.Severity = "informational"
    report.status_extended = f"<Resource> is compliant with <requirement>."
elif <generic_condition_2>:
    report.status = "FAIL"
    report.check_metadata.Severity = "low"
    report.status_extended = f"<Resource> is not compliant with <requirement>: <reason>."
elif <generic_condition_3>:
    report.status = "FAIL"
    report.check_metadata.Severity = "medium"
    report.status_extended = f"<Resource> is not compliant with <requirement>: <reason>."
elif <generic_condition_4>:
    report.status = "FAIL"
    report.check_metadata.Severity = "high"
    report.status_extended = f"<Resource> is not compliant with <requirement>: <reason>."
else:
    report.status = "FAIL"
    report.check_metadata.Severity = "critical"
    report.status_extended = f"<Resource> is not compliant with <requirement>: <critical reason>."

​

Resource Identification in Prowler

• AWS
  • Amazon Resource ID — report.resource_id.
    • The resource identifier. This is the name of the resource, the ID of the resource, or a resource path. Some resource identifiers include a parent resource (sub-resource-type/parent-resource/sub-resource) or a qualifier such as a version (resource-type:resource-name:qualifier).
    • If the resource ID cannot be retrieved directly from the audited resource, it can be extracted from the ARN. It is the last part of the ARN after the last slash (/) or colon (:).
    • If no actual resource to audit exists, this format can be used: <resource_type>/unknown
  • Amazon Resource Name — report.resource_arn.
    • The Amazon Resource Name (ARN) of the audited entity.
    • If the ARN cannot be retrieved directly from the audited resource, construct a valid ARN using the resource_id component as the audited entity. Examples:
      • Bedrock — arn:<partition>:bedrock:<region>:<account-id>:model-invocation-logging.
      • DirectConnect — arn:<partition>:directconnect:<region>:<account-id>:dxcon.
    • If no actual resource to audit exists, this format can be used: arn:<partition>:<service>:<region>:<account-id>:<resource_type>/unknown.
      • Examples:
        • AWS Security Hub — arn:<partition>:security-hub:<region>:<account-id>:hub/unknown.
        • Access Analyzer — arn:<partition>:access-analyzer:<region>:<account-id>:analyzer/unknown.
        • GuardDuty — arn:<partition>:guardduty:<region>:<account-id>:detector/unknown.
• GCP
  • Resource ID — report.resource_id.
    • Resource ID represents the full, unambiguous path to a resource, known as the full resource name. Typically, it follows the format: //{api_service/resource_path}.
    • If the resource ID cannot be retrieved directly from the audited resource, by default the resource name is used.
  • Resource Name — report.resource_name.
    • Resource Name usually refers to the name of a resource within its service.
• Azure
  • Resource ID — report.resource_id.
    • Resource ID represents the full Azure Resource Manager path to a resource, which follows the format: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}.
  • Resource Name — report.resource_name.
    • Resource Name usually refers to the name of a resource within its service.
    • If the resource name cannot be retrieved directly from the audited resource, the last part of the resource ID can be used.
• Kubernetes
  • Resource ID — report.resource_id.
    • The UID of the Kubernetes object. This is a system-generated string that uniquely identifies the object within the cluster for its entire lifetime. See Kubernetes Object Names and IDs - UIDs.
  • Resource Name — report.resource_name.
    • The name of the Kubernetes object. This is a client-provided string that must be unique for the resource type within a namespace (for namespaced resources) or cluster (for cluster-scoped resources). Names typically follow DNS subdomain or label conventions. See Kubernetes Object Names and IDs - Names.
• M365
  • Resource ID — report.resource_id.
    • If the audited resource has a globally unique identifier such as a guid, use it as the resource_id.
    • If no guid exists, use another unique and relevant identifier for the resource, such as the tenant domain, the internal policy ID, or a representative string following the format <resource_type>/<name_or_id>.
  • Resource Name — report.resource_name.
    • Use the visible or descriptive name of the audited resource. If no explicit name is available, use a clear description of the resource or configuration being evaluated.
  • Examples:
    • For an organization:
      • resource_id: Organization GUID
      • resource_name: Organization name
    • For a policy:
      • resource_id: Unique policy ID
      • resource_name: Policy display name
    • For global configurations:
      • resource_id: Tenant domain or representative string (e.g., “userSettings”)
      • resource_name: Description of the configuration (e.g., “SharePoint Settings”)
• GitHub
  • Resource ID — report.resource_id.
    • The ID of the Github resource. This is a system-generated integer that uniquely identifies the resource within the Github platform.
  • Resource Name — report.resource_name.
    • The name of the Github resource. In the case of a repository, this is just the repository name. For full repository names use the resource full_name.

​

Configurable Checks in Prowler

​

Metadata Structure for Prowler Checks

​

Example Metadata File

{
  "Provider": "aws",
  "CheckID": "service_resource_security_setting",
  "CheckTitle": "Service resource has security setting enabled",
  "CheckType": [],
  "ServiceName": "service",
  "SubServiceName": "",
  "ResourceIdTemplate": "",
  "Severity": "medium",
  "ResourceType": "Other",
  "Description": "This check verifies that the service resource has the required **security setting** enabled to protect against potential vulnerabilities.\n\nIt ensures that the resource follows security best practices and maintains proper access controls. The check evaluates whether the security configuration is properly implemented and active.",
  "Risk": "Without proper security settings, the resource may be vulnerable to:\n\n- **Unauthorized access** - Malicious actors could gain entry\n- **Data breaches** - Sensitive information could be compromised\n- **Security threats** - Various attack vectors could be exploited\n\nThis could result in compliance violations and potential financial or reputational damage.",
  "RelatedUrl": "",
  "AdditionalURLs": ["https://example.com/security-documentation", "https://example.com/best-practices"],
  "Remediation": {
    "Code": {
      "CLI": "provider-cli service enable-security-setting --resource-id resource-123",
      "NativeIaC": "```yaml\nType: Provider::Service::Resource\nProperties:\n  SecuritySetting: enabled\n  ResourceId: resource-123\n```",
      "Other": "1. Open the provider management console\n2. Navigate to the service section\n3. Select the resource\n4. Enable the security setting\n5. Save the configuration",
      "Terraform": "```hcl\nresource \"provider_service_resource\" \"example\" {\n  resource_id      = \"resource-123\"\n  security_setting = true\n}\n```"
    },
    "Recommendation": {
      "Text": "Enable security settings on all service resources to ensure proper protection. Regularly review and update security configurations to align with current best practices.",
      "Url": "https://hub.prowler.com/check/service_resource_security_setting"
    }
  },
  "Categories": ["internet-exposed", "secrets"],
  "DependsOn": [],
  "RelatedTo": ["service_resource_security_setting", "service_resource_security_setting_2"],
  "Notes": "This is a generic example check that should be customized for specific provider and service requirements."
}

​

Metadata Fields and Their Purpose

​

Provider

​

CheckID

​

CheckTitle

​

CheckType

​

ServiceName

​

SubServiceName

​

ResourceIdTemplate

​

Severity

​

ResourceType

• AWS: Use Security Hub resource types or PascalCase CloudFormation types removing the :: separator used in CloudFormation templates (e.g., in CloudFormation template the type of an EC2 instance is AWS::EC2::Instance but in the check it should be AwsEc2Instance). Use Other if none apply.
• Azure: Use types from Azure Resource Graph, for example: Microsoft.Storage/storageAccounts.
• Google Cloud: Use Cloud Asset Inventory asset types, for example: compute.googleapis.com/Instance.
• Kubernetes: Use types shown under KIND from kubectl api-resources.
• M365 / GitHub: Leave empty due to lack of standardized types.

​

Description

​

Risk

​

RelatedUrl

​

AdditionalURLs

​

Remediation

• Code: Contains remediation examples in different formats:
  • CLI: Command-line interface commands to make the finding compliant in runtime.
  • NativeIaC: Native Infrastructure as Code templates with an example of a compliant configuration. For now it applies to:
    • AWS: CloudFormation YAML formatted code (do not use JSON format).
    • Azure: Bicep formatted code (do not use ARM templates).
  • Terraform: HashiCorp Configuration Language (HCL) code with an example of a compliant configuration.
  • Other: Manual steps through web interfaces or other tools to make the finding compliant.
  For detailed guidelines on writing remediation code, see Remediation Code Guidelines.
• Recommendation
  • Text: Generic best practice guidance in natural language using Markdown format (maximum 400 characters). For writing guidelines, see Recommendation Guidelines.
  • Url: Prowler Hub URL of the check. This URL is always composed by https://hub.prowler.com/check/<check_id>.

​

Categories

​

DependsOn

​

RelatedTo

​

Notes

​

Python Model Reference

​

Generic Check Patterns and Best Practices

​

Common Patterns

• Every check is implemented as a class inheriting from Check (from prowler.lib.check.models).
• The main logic is implemented in the execute() method (only method that must be implemented), which always returns a list of provider-specific report objects (e.g., CheckReport<Provider>)—one per finding/resource. If there are no findings/resources, return an empty list.
• Never use the provider’s client directly; instead, use the service client (e.g., <service>_client) and iterate over its resources.
• For each resource, create a provider-specific report object, populate it with metadata, resource details, status (PASS, FAIL, etc.), and a human-readable status_extended message.
• Use the metadata() method to attach check metadata to each report.
• Checks are designed to be idempotent and stateless: they do not modify resources, only report on their state.

​

Best Practices

• Use clear, actionable, and user-friendly language in status_extended to explain the result. Always provide information to identify the resource.
• Use helper functions/utilities for repeated logic to avoid code duplication. Save them in the lib folder of the service.
• Handle exceptions gracefully: catch errors per resource, log them, and continue processing other resources.
• Document the check with a class and function level docstring explaining what it does, what it checks, and any caveats or provider-specific behaviors.
• Use type hints for the execute() method (e.g., -> list[CheckReport<Provider>]) for clarity and static analysis.
• Ensure checks are efficient; avoid excessive nested loops. If the complexity is high, consider refactoring the check.
• Keep the check logic focused: one check = one control/requirement. Avoid combining unrelated logic in a single check.

​

Specific Check Patterns