【Tips】How to create custom checks with Prowler

Created date: 2025/02/11, Update date: 2025/02/11

Prowler is a tool for checking the security settings of AWS, Azure, and GCP accounts.
In addition to the checks provided by default, you can also create custom checks.
Since the method for creating custom checks was not detailed in the official documentation, we analyzed the source code to confirm the method for creating custom checks.
This article describes how to create custom checks with Prowler.

Table of contents

What is Prowler?
What is mentioned about custom checks in the official documentation?
(Conclusion first) File structure and content of custom checks
1. Using Prowler’s standard client
2. Using a custom client
Debugging method during custom check development
Reading Prowler’s source code (as of v1.12.1)
1. Entry point - prowler()

What is Prowler?

As described on GitHub - prowler-cloud/prowler :

Prowler is an open-source security tool for AWS, Azure, Google Cloud, and Kubernetes that performs security best practices assessments, audits, incident response, continuous monitoring, hardening, and forensics readiness, and also performs remediation. There is Prowler CLI (Command Line Interface) called Prowler Open Source and a service on top of it called Prowler SaaS.
Source: GitHub - prowler-cloud/prowler

Prowler can perform checks based on security frameworks such as CIS, NIST, and PCI-DSS.
- As summarized in the article 【Tips】Investigating security check tools that support CIS AWS Foundations Benchmark v3.0.0 (Security Hub, CFn Guard, Prowler) , Prowler can check a wide range of rules within security frameworks compared to Security Hub.

What is mentioned about custom checks in the official documentation?

Custom checks are described on the following page of the official documentation:
- Miscellaneous - Prowler Documentation

Below is the translated content, but the official documentation does not provide much detail on how to create custom checks. The Developer Guide, which is said to describe the detailed writing of checks, contains information on how to develop Prowler itself and does not mention custom checks.

The custom checks folder must contain one subfolder per check, each subfolder must be named after the check and contain the following:

An empty init .py: This tells Python to treat this check folder as a package. check_name.py: Contains the logic of the check. check_name.metadata.json: Contains the metadata of the check. The check name must start with the service name followed by an underscore (e.g., ec2_instance_public_ip).

For more details on how to write checks, refer to the “Developer Guide”.
Source: Miscellaneous - Prowler Documentation

(Conclusion first) File structure and content of custom checks

When creating custom checks, there are two patterns for the file structure: “Using Prowler’s standard client” and “Using a custom client”.

Using Prowler’s standard client

When using Prowler’s standard client, you can create custom checks with the following file structure.


          ${parent_folder_name}/
          ∟ ${AWS_service_name}_${check_name}
          　 ∟ __init__.py
          　 ∟ ${AWS_service_name}_${check_name}.py
          　 ∟ ${AWS_service_name}_${check_name}.metadata.json

          # Example file structure: Check if alternative contact information is registered for the account
          custom-checks-folder/
          ∟ account_alternative_contact_information_is_registered/
          　 ∟ __init__.py
          　 ∟ account_alternative_contact_information_is_registered.py
          　 ∟ account_alternative_contact_information_is_registered.metadata.json

${parent_folder_name} specifies an appropriate folder name. Create a folder named ${AWS_service_name}_${check_name} directly under the parent folder.
The parent folder can be placed in any nested structure. However, the folder specified as an argument must be the path of the parent folder containing the check folder.
Multiple ${AWS_service_name}_${check_name} folders can be created.

${AWS_service_name} must be one of the following. The detailed reason is explained later. (As of v3.12.1)

List of AWS service names

accessanalyzer
account
acm
apigateway
apigatewayv2
appstream
athena
autoscaling
awslambda
backup
cloudformation
cloudfront
cloudtrail
cloudwatch
codeartifact
codebuild
cognito
config
directoryservice
dlm
documentdb
drs
dynamodb
ec2
ecr
ecs
efs
eks
elasticache
elb
elbv2
emr
fms
glacier
globalaccelerator
glue
guardduty
iam
inspector2
kms
macie
neptune
networkfirewall
opensearch
organizations
rds
redshift
resourceexplorer2
route53
s3
sagemaker
secretsmanager
securityhub
shield
sns
sqs
ssm
ssmincidents
trustedadvisor
vpc
waf
wafv2
wellarchitected
workspaces

${check_name} specifies the name of the check in lower snake case.

Next, I will explain the content of the files.
The content of the files is created with reference to prowler/prowler/providers/aws/services at master · prowler-cloud/prowler .

__init__.py is an empty file. There is no need to write any processing.

${AWS_service_name}_${check_name}.py describes the logic of the check.
For example, to create a check to see if alternative contact information is registered for the account, it is described as follows.
- There are several patterns for generating check reports, but the following example explains the pattern that returns the result of the check as “FAIL” or “PASS”.
- The highlighted processing is basically necessary code. After generating Check_Report_AWS , set the values of region , resource_arn , resource_id , status , status_extended , and resource_tags .
  - For details, refer to Checks - Prowler Documentation .
- To generate the report, use Prowler’s standard client account_client . account_client is defined in the Prowler GitHub repository in prowler/providers/aws/services/${AWS_service_name}/${AWS_service_name}_client.py and prowler/providers/aws/services/${AWS_service_name}/${AWS_service_name}_service.py . By looking at the content of the class that inherits AWSService or BaseModel in ${AWS_service_name}_service.py , you can check the variables that can be used with account_client .
  - If you want to use variables that are not defined here, you need to create your own client. The detailed method is explained later.


          import json
          from prowler.lib.logger import logger
          from prowler.lib.check.models import Check, Check_Report_AWS
          from prowler.providers.aws.services.account.account_client import account_client


          class account_alternative_contact_information_is_registered(Check):
              def execute(self):
                  desired_alternative_contact_count = account_client.audit_config.get("desired_alternative_contact_count", 1)
                  findings = []
                  report = Check_Report_AWS(self.metadata())

                  # For each Prowler check we MUST fill the following
                  # Check_Report_AWS fields:
                  # - region
                  # - resource_id
                  # - resource_arn
                  # - status
                  # - status_extended
                  # - resource_tags (optional)

                  logger.debug(f"account_client.contact_names: {account_client.contact_names}")
                  logger.debug(f"account_client.contact_phone_numbers: {account_client.contact_phone_numbers}")
                  logger.debug(f"account_client.contact_emails: {account_client.contact_emails}")

                  contact_emails = account_client.contact_emails
                  contact_emails.discard(None)

                  report = Check_Report_AWS(self.metadata())
                  report.region = account_client.region
                  report.resource_arn = account_client.audited_account_arn
                  report.resource_id = account_client.audited_account

                  if len(contact_emails) != desired_alternative_contact_count:
                      report.status = "FAIL"
                  else:
                      report.status = "PASS"

                  report.status_extended = json.dumps(
                      {
                          "desired_alternative_contact_count": desired_alternative_contact_count,
                          "contact_emails_count": len(contact_emails),
                          "contact_emails": list(contact_emails),
                      },
                  )

                  findings.append(report)

                  return findings

${AWS_service_name}_${check_name}.metadata.json describes the metadata of the check.
For the check to see if alternative contact information is registered for the account, it is described as follows.
- The metadata keys must be included in the JSON, but some key values can be empty. In the example below, only the items that are likely to be required are specified.
- The following value formats must be met.
  - Provider is aws
  - CheckID is ${AWS_service_name}_${check_name} (lower snake case)
  - ServiceName is ${AWS_service_name} (as defined in Prowler)
  - Severity is one of low , medium , high , critical


          {
            "Provider": "aws",
            "CheckID": "account_alternative_contact_information_is_registered",
            "CheckTitle": "Account alternative contact information is registered",
            "CheckType": [
              "IAM"
            ],
            "ServiceName": "account",
            "SubServiceName": "",
            "ResourceIdTemplate": "arn:partition:access-recorder:region:account-id:recorder/resource-id",
            "Severity": "medium",
            "ResourceType": "Other",
            "Description": "",
            "Risk": "",
            "RelatedUrl": "",
            "Remediation": {
              "Code": {
                "CLI": "",
                "NativeIaC": "",
                "Other": "",
                "Terraform": ""
              },
              "Recommendation": {
                "Text": "",
                "Url": ""
              }
            },
            "Categories": [
              "custom-checks"
            ],
            "DependsOn": [],
            "RelatedTo": [],
            "Notes": ""
          }

Using a custom client

When using a custom client, you can create custom checks with the following file structure. The file naming is the same as when using Prowler’s standard client.
- The highlighted cst_*.py file names can be arbitrary, but it is recommended to use names that are easy to understand when loading.


          ${parent_folder_name}/
          ∟ ${AWS_service_name}_${check_name}
          　 ∟ __init__.py
          　 ∟ ${AWS_service_name}_${check_name}.py
          　 ∟ ${AWS_service_name}_${check_name}.metadata.json
          　 ∟ cst_${AWS_service_name}_client.py
          　 ∟ cst_${AWS_service_name}_service.py

          # Example file structure: Check if the Config delivery channel is enabled
          custom-checks-folder/
          ∟ config_delivery_channel_enabled/
          　 ∟ __init__.py
          　 ∟ config_delivery_channel_enabled.py
          　 ∟ config_delivery_channel_enabled.metadata.json
          　 ∟ cst_config_client.py
          　 ∟ cst_config_service.py

Next, I will explain the content of the files.
__init__.py and ${AWS_service_name}_${check_name}.metadata.json are the same as when using Prowler’s standard client.
In ${AWS_service_name}_${check_name}.py , you need to change the way the client is loaded. Here, I will explain the example of creating a check to see if the Config delivery channel is enabled.
- The key point is lines 3-7 below. Since files placed under the ${AWS_service_name}_${check_name}/ directory will fail to load as they are, add the directory where the file exists with sys.path.append .


          from prowler.lib.logger import logger
          from prowler.lib.check.models import Check, Check_Report_AWS
          import os
          import sys

          sys.path.append(os.path.join(os.path.dirname(__file__)))
          from cst_config_client import config_client  # noqa: E402


          class config_delivery_channel_enabled(Check):
              def execute(self):
                  findings = []
                  report = Check_Report_AWS(self.metadata())

          // Omitted

The content of the cst_config_client.py file is as follows. Here, I will explain the example of defining a custom client for Config.
- The content is simple, and it instantiates the client defined in cst_config_service.py .


          from prowler.providers.aws.lib.audit_info.audit_info import current_audit_info
          from cst_config_service import Config

          config_client = Config(current_audit_info)

The content of the cst_config_service.py file is as follows. Here, I will explain the example of defining the Config delivery recorder.
- The processing content is developed based on the content of Prowler’s standard client.
- The Config(AWSService) class defines the processing to be executed when the client is initialized.
  - The __describe_delivery_channels__ function executes regional_client.describe_delivery_channels() to obtain the Config delivery channel.
  - It generates an instance of the DeliveryChannel class and adds it to the self.delivery_channels list.
  - The self.delivery_channels list contains information about the Config delivery channel. The check results are generated based on this information.
  - For processing that checks security-related resources, it is necessary to define the processing for when AWS resources do not exist. Conversely, for processing that checks multiple AWS resources such as EC2 instances and S3 buckets, it is necessary to execute List or Describe APIs to obtain information about all resources.
- The DeliveryChannel(BaseModel) class defines the structure of the DeliveryChannel based on CloudFormation and API documentation. Parameters that are not mandatory as information are specified as Optional . When outputting results even if AWS resources do not exist, parameters other than name and region may be specified as None , so Optional is specified.
  - AWS::Config::DeliveryChannel - AWS CloudFormation
  - DescribeDeliveryChannels - AWS Config


          from typing import Optional

          from pydantic import BaseModel

          from prowler.lib.logger import logger
          from prowler.lib.scan_filters.scan_filters import is_resource_filtered
          from prowler.providers.aws.lib.service.service import AWSService


          class Config(AWSService):
              def __init__(self, audit_info):
                  super().__init__(__class__.__name__, audit_info)
                  self.delivery_channels = []
                  self.__threading_call__(self.__describe_delivery_channels__)

              def __describe_delivery_channels__(self, regional_client):
                  logger.info("Config - Listing Delivery Channels...")
                  try:
                      delivery_channel_count = 0
                      delivery_channels = regional_client.describe_delivery_channels()[
                          "DeliveryChannels"
                      ]
                      for delivery_channel in delivery_channels:
                          if not self.audit_resources or (
                              is_resource_filtered(delivery_channel["name"], self.audit_resources)
                          ):
                              self.delivery_channels.append(
                                  DeliveryChannel(
                                      name=delivery_channel["name"],
                                      s3_bucket_name=delivery_channel["s3BucketName"],
                                      s3_key_prefix=delivery_channel["s3KeyPrefix"],
                                      sns_topic_arn=delivery_channel["snsTopicARN"],
                                      region=regional_client.region,
                                  )
                              )
                              delivery_channel_count += 1

                      # No delivery channels in region
                      if delivery_channel_count == 0:
                          self.delivery_channels.append(
                              DeliveryChannel(
                                  name=self.audited_account,
                                  s3_bucket_name=None,
                                  s3_key_prefix=None,
                                  sns_topic_arn=None,
                                  region=regional_client.region,
                              )
                          )
                  except Exception as error:
                      logger.error(
                          f"{regional_client.region} -- {error.__class__.__name__}[{error.__traceback__.tb_lineno}]: {error}"
                      )


          class DeliveryChannel(BaseModel):
              name: str
              s3_bucket_name: Optional[str]
              s3_key_prefix: Optional[str]
              sns_topic_arn: Optional[str]
              region: str

Debugging method during custom check development

The quickest way to debug during custom check development is to execute it from Prowler.
By specifying only the check under development with the --checks option as shown below, you can shorten the time required for debugging.
If you specify --log-level , you can check the logs output by the logger.


          prowler aws \
          --checks-folder ./custom-checks-folder/ \
          --checks \
          account_alternative_contact_information_is_registered \
          --log-level ERROR \
          -M csv \
          --output-directory ./output

When outputting logs at the DEBUG level, it is recommended to output the logs to a file as it is difficult to check in the terminal.


          prowler aws \
          --checks-folder ./custom-checks-folder/ \
          --checks \
          account_alternative_contact_information_is_registered \
          --log-level DEBUG \
          -M csv \
          --output-directory ./output > debug.log 2>&1

Reading Prowler’s source code (as of v1.12.1)

Entry point - prowler()

The entry point of Prowler is prowler/__main__.py ’s prowler() .
The arguments at the