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 AWS Lambda function, which contains the evaluation logic for the rule. Then you associate the function with a Custom Lambda rule that you create in AWS Config.

Important

As a security best practice when allowing AWS 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 AWS Lambda resource-based policy.

Contents

• Creating an AWS Lambda Function for a Custom Config Rule
• Creating a Custom Rule in AWS Config
• Security best practice for AWS Lambda resource-based policy
• Evaluating Additional Resource Types

Creating an AWS Lambda Function for a Custom Config Rule

A Lambda function is custom code that you upload to AWS 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, AWS Config invokes it when the rule's trigger occurs. The Lambda function then evaluates the configuration information that is sent by AWS Config, and it returns the evaluation results. For more information about Lambda functions, see Function and Event Sources in the AWS Lambda Developer Guide.

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

AWS Lambda blueprints

The AWS 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 AWS resource configurations change.

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

AWS 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 AWS community. If you want to use a sample, you can copy its code into a new AWS 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 AWS Management Console and open the AWS Lambda console at https://console.aws.amazon.com/lambda/.

2. In the AWS Management Console menu, verify that the region selector is set to a region that supports AWS Config rules. For the list of supported regions, see AWS 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 AWS 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 AWS 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 AWS 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, AWS Config passes rule parameters in JSON format. You can define which rule parameters are passed when you create the Custom Lambda rule in AWS Config.

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

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

11. For Role name, type a name.

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

13. Verify the details and choose Create function.

Creating a Custom Rule in AWS Config

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

To create a custom rule

1. Open the AWS Config console at https://console.aws.amazon.com/config/.

2. In the AWS Management Console menu, verify that the region selector is set to the same region in which you created the AWS 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 AWS Lambda function ARN, specify the ARN that AWS 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. AWS Lambda supports function versioning, and each version is assigned an ARN with a qualifier. AWS Lambda uses the $LATEST qualifier for the latest version.

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

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

   • Periodic – AWS 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 AWS Config invokes your Lambda function:

   • All changes – When any resource recorded by AWS 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 AWS Config invokes your Lambda function.

10. In the Parameters section, specify any rule parameters that your AWS 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 AWS Config receives evaluation results from your AWS 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 - AWS Config evaluated your resources against the rule. The rule did not apply to the AWS 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 - AWS Config cannot evaluate your recorded AWS resources against this rule because none of your resources are within the rule’s scope. You can choose which resources AWS 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 AWS Config console, the appropriate permissions are automatically created for you. If you create a Custom Lambda rule with the AWS CLI, you need to give AWS Config permission to invoke your Lambda function, using the aws lambda add-permission command. For more information, see Using Resource-Based Policies for AWS Lambda (Lambda Function Policies) in the AWS Lambda Developer Guide.

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

Security best practice for AWS 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 AWS 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 AWS 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 AWS Config. This is useful if you want to evaluate compliance for additional resource types that AWS Config doesn't currently record. For a list of additional resource types that you can evaluate with Custom Lambda rules, see AWS Resource Types Reference.

Note

When creating a Custom Lambda for a resource type that is not recorded by AWS 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 AWS 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 AWS Config.

2. You create an AWS 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 AWS Lambda function to the rule.

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

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

Note

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