Custom Lambda Rules (General Example) - Amazon Config
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Custom Lambda Rules (General Example)

Complete the following procedure to create a Custom Lambda rule. To create a Custom Lambda rule, you first create an Amazon Lambda function, which contains the evaluation logic for the rule. Then you associate the function with a Custom Lambda rule that you create in Amazon Config.

Important

As a security best practice when allowing Amazon Config permission to invoke your Lambda function, we strongly recommend that you restrict access in the resource-based policy for Lambda with sourceARN and/or sourceAccountId in the invoke request. For more information, see Security best practice for Amazon Lambda resource-based policy.

Creating an Amazon Lambda Function for a Custom Config Rule

A Lambda function is custom code that you upload to Amazon Lambda, and it is invoked by events that are published to it by an event source. If the Lambda function is associated with a Config rule, Amazon Config invokes it when the rule's trigger occurs. The Lambda function then evaluates the configuration information that is sent by Amazon Config, and it returns the evaluation results. For more information about Lambda functions, see Function and Event Sources in the Amazon Lambda Developer Guide.

You can use a programming language that is supported by Amazon Lambda to create a Lambda function for a Custom Lambda rule. To make this task easier, you can customize an Amazon Lambda blueprint or reuse a sample function from the Amazon Config Rules GitHub repository.

Amazon Lambda blueprints

The Amazon Lambda console provides sample functions, or blueprints, which you can customize by adding your own evaluation logic. When you create a function, you can choose one of the following blueprints:

  • config-rule-change-triggered – Triggered when your Amazon resource configurations change.

  • config-rule-periodic – Triggered at a frequency that you choose (for example, every 24 hours).

Amazon Config Rules GitHub repository

A public repository of sample functions for Custom Lambda rules is available on GitHub, a web-based code hosting and sharing service. The sample functions are developed and contributed by the Amazon community. If you want to use a sample, you can copy its code into a new Amazon Lambda function. To view the repository, see https://github.com/awslabs/aws-config-rules/.

To create the function for your custom rule
  1. Sign in to the Amazon Web Services Management Console and open the Amazon Lambda console at https://console.amazonaws.cn/lambda/.

  2. In the Amazon Web Services Management Console menu, verify that the region selector is set to a region that supports Amazon Config rules. For the list of supported regions, see Amazon Config Regions and Endpoints in the Amazon Web Services General Reference.

  3. Choose Create a Lambda function.

  4. On the Use a blueprint page, you can choose one of the blueprint functions for Amazon Config rules as a starting point, or you can proceed without a blueprint by choosing Skip.

  5. On the Configure triggers page, choose Next.

  6. On the Basic information page, type a name and description.

  7. For Runtime, choose the programming language in which your function is written.

  8. For Code entry type, choose your preferred entry type. If you are using a blueprint, keep the preconfigured code.

  9. Provide your code using the method required by the code entry type that you selected. If you are using a blueprint, the function code is provided in the code editor, and you can customize it to include your own evaluation logic. Your code can evaluate the event data that Amazon Config provides when it invokes your function:

    • For functions based on the config-rule-change-triggered blueprint, or for functions triggered by configuration changes, the event data is the configuration item or an oversized configuration item object for the Amazon resource that changed.

    • For functions based on the config-rule-periodic blueprint, or for functions triggered at a frequency that you choose, the event data is a JSON object that includes information about when the evaluation was triggered.

    • For both types of functions, Amazon Config passes rule parameters in JSON format. You can define which rule parameters are passed when you create the Custom Lambda rule in Amazon Config.

    • For example events that Amazon Config publishes when it invokes your function, see Example Events for Amazon Config Rules.

  10. For Execution role, choose Create new role from Amazon Policy templates.

  11. For Role name, type a name.

  12. For Policy templates, choose Amazon Config Rules permission.

  13. Verify the details and choose Create function.

Creating a Custom Rule in Amazon Config

Use Amazon Config to create a Custom Lambda rule and associate the rule with a Lambda function.

To create a custom rule
  1. Open the Amazon Config console at https://console.amazonaws.cn/config/.

  2. In the Amazon Web Services Management Console menu, verify that the region selector is set to the same region in which you created the Amazon Lambda function for your Custom Lambda rule.

  3. On the Rules page, choose Add rule.

  4. On the Specify rule type page, choose Create custom rule.

  5. On the Configure rule page, type a name and description.

  6. For Amazon Lambda function ARN, specify the ARN that Amazon Lambda assigned to your function.

    Note

    The ARN that you specify in this step must not include the $LATEST qualifier. You can specify an ARN without a version qualifier or with any qualifier besides $LATEST. Amazon Lambda supports function versioning, and each version is assigned an ARN with a qualifier. Amazon Lambda uses the $LATEST qualifier for the latest version.

  7. For Trigger type, choose one or both of the following:

    • Configuration changes – Amazon Config invokes your Lambda function when it detects a configuration change.

    • Periodic – Amazon Config invokes your Lambda function at the frequency that you choose (for example, every 24 hours).

  8. If the trigger types for your rule include Configuration changes, specify one of the following options for Scope of changes with which Amazon Config invokes your Lambda function:

    • All changes – When any resource recorded by Amazon Config is created, changed, or deleted.

    • Resources – When any resource that matches the specified type, or the type plus identifier, is created, changed, or deleted.

    • Tags – When any resource with the specified tag is created, changed, or deleted

  9. If the trigger types for your rule include Periodic, specify the Frequency with which Amazon Config invokes your Lambda function.

  10. In the Parameters section, specify any rule parameters that your Amazon Lambda function evaluates and the desired value.

  11. Choose Next. On the Review and create page, verify the details about your rule, and choose Add rule function. Your new rule displays on the Rulespage.

    Compliance will display Evaluating... until Amazon Config receives evaluation results from your Amazon Lambda function. If the rule and the function are working as expected, a summary of results appears after several minutes. You can update the results with the refresh button.

    If the rule or function is not working as expected, you might see one of the following for Compliance:

    • No results reported - Amazon Config evaluated your resources against the rule. The rule did not apply to the Amazon resources in its scope, the specified resources were deleted, or the evaluation results were deleted. To get evaluation results, update the rule, change its scope, or choose Re-evaluate.

      This message may also appear if the rule didn't report evaluation results.

    • No resources in scope - Amazon Config cannot evaluate your recorded Amazon resources against this rule because none of your resources are within the rule’s scope. You can choose which resources Amazon Config records on the Settings page.

    • Evaluations failed - For information that can help you determine the problem, choose the rule name to open its details page and see the error message.

Note

When you create a Custom Lambda rule with the Amazon Config console, the appropriate permissions are automatically created for you. If you create a Custom Lambda rule with the Amazon CLI, you need to give Amazon Config permission to invoke your Lambda function, using the aws lambda add-permission command. For more information, see Using Resource-Based Policies for Amazon Lambda (Lambda Function Policies) in the Amazon Lambda Developer Guide.

Before giving Amazon Config permission to invoke your Lambda function, see the following section Security best practice for Amazon Lambda resource-based policy.

Security best practice for Amazon Lambda resource-based policy

As a security best practice, to avoid giving invoke permission for the whole service principal name (SPN) to call your Lambda function, we strongly recommend that you restrict access in the Lambda resource-based policy with sourceARN and/or sourceAccountId in the invoke request.

The sourceARN is the ARN of Amazon Config rule that is invoking the Lambda function.

The sourceAccountId is the account ID of the user who created the rule.

Restricting access in the Lambda resource-based policy helps make sure Amazon Lambda is accessing your resources on behalf of expected users and scenarios only.

To add SPN based permission, you need to use the following CLI

aws lambda add-permission --function-name rule lambda function name --action lambda:InvokeFunction --statement-id config --principal config.amazonaws.com

To add SourceAccountId based permission

Before the rule is created, you can add sourceAccountId based permission to the resource-based policy with the following CLI

aws lambda add-permission --function-name rule lambda function name --action lambda:InvokeFunction --statement-id config --principal config.amazonaws.com --source-account your account ID

To add both SourceArn and SourceAccountId based permission

After the rule is created, you can add sourceARN based permission to resource-based policy with the following CLI. This allows only a specific rule ARN to invoke the Lambda function.

aws lambda add-permission --function-name rule lambda function name --action lambda:InvokeFunction --statement-id config --principal config.amazonaws.com --source-account your account ID --source-arn ARN of the created config rule

Evaluating Additional Resource Types

You can create Custom Lambda rules to run evaluations for resource types not yet recorded by Amazon Config. This is useful if you want to evaluate compliance for additional resource types that Amazon Config doesn't currently record. For a list of additional resource types that you can evaluate with Custom Lambda rules, see Amazon Resource Types Reference.

Note

When creating a Custom Lambda for a resource type that is not recorded by Amazon Config, the rule must have the periodic trigger type. The configuration changes trigger type is not supported. For more information, see Evaluation Mode and Trigger Types for Amazon Config Rules.

Example
  1. You want to evaluate Amazon S3 Glacier vaults in your account. Amazon S3 Glacier vault resources are currently not recorded by Amazon Config.

  2. You create an Amazon Lambda function that evaluates whether your Amazon S3 Glacier vaults comply with your account requirements.

  3. You create a Custom Lambda rule named evaluate-glacier-vaults and then assign your Amazon Lambda function to the rule.

  4. Amazon Config invokes your Lambda function and then evaluates the Amazon S3 Glacier vaults against your rule.

  5. Amazon Config returns the evaluations and you can view the compliance results for your rule.

Note

You can view the configuration details in the Amazon Config timeline and look up resources in the Amazon Config console for resources that Amazon Config supports. If you configured Amazon Config to record all resource types, newly supported resources will automatically be recorded. For more information, see Supported Resource Types.