AWS::Config::ConfigRule
Note
You must first create and start the Amazon Config configuration recorder in order to create Amazon Config managed rules with Amazon CloudFormation. For more information, see Managing the Configuration Recorder.
Adds or updates an Amazon Config rule to evaluate if your Amazon resources comply with your desired configurations. For information on how many Amazon Config rules you can have per account, see Service Limits in the Amazon Config Developer Guide.
There are two types of rules: Amazon Config Managed Rules and Amazon Config Custom Rules.
You can use the ConfigRule
resource to create both Amazon Config Managed Rules and Amazon Config Custom Rules.
Amazon Config Managed Rules are predefined,
customizable rules created by Amazon Config. For a list of managed rules, see
List of Amazon Config
Managed Rules. If you are adding an Amazon Config managed rule, you must specify the
rule's identifier for the SourceIdentifier
key.
Amazon Config Custom Rules are rules that you create from scratch. There are two ways to create Amazon Config custom rules: with Lambda functions
(Amazon Lambda Developer Guide) and with Guard (Guard GitHub
Repository
If you are adding a new Amazon Config Custom Lambda rule,
you first need to create an Amazon Lambda function that the rule invokes to evaluate
your resources. When you use the ConfigRule
resource to add a Custom Lambda rule to Amazon Config, you must specify the Amazon Resource
Name (ARN) that Amazon Lambda assigns to the function. You specify the ARN
in the SourceIdentifier
key. This key is part of the
Source
object, which is part of the
ConfigRule
object.
For any new Amazon Config rule that you add, specify the
ConfigRuleName
in the ConfigRule
object. Do not specify the ConfigRuleArn
or the
ConfigRuleId
. These values are generated by Amazon Config for new rules.
If you are updating a rule that you added previously, you can
specify the rule by ConfigRuleName
,
ConfigRuleId
, or ConfigRuleArn
in the
ConfigRule
data type that you use in this
request.
For more information about developing and using Amazon Config rules, see Evaluating Resources with Amazon Config Rules in the Amazon Config Developer Guide.
Syntax
To declare this entity in your Amazon CloudFormation template, use the following syntax:
JSON
{ "Type" : "AWS::Config::ConfigRule", "Properties" : { "Compliance" :
Compliance
, "ConfigRuleName" :String
, "Description" :String
, "EvaluationModes" :[ EvaluationModeConfiguration, ... ]
, "InputParameters" :Json
, "MaximumExecutionFrequency" :String
, "Scope" :Scope
, "Source" :Source
} }
YAML
Type: AWS::Config::ConfigRule Properties: Compliance:
Compliance
ConfigRuleName:String
Description:String
EvaluationModes:- EvaluationModeConfiguration
InputParameters:Json
MaximumExecutionFrequency:String
Scope:Scope
Source:Source
Properties
Compliance
-
Indicates whether an Amazon resource or Amazon Config rule is compliant and provides the number of contributors that affect the compliance.
Required: No
Type: Compliance
Update requires: No interruption
ConfigRuleName
-
A name for the Amazon Config rule. If you don't specify a name, Amazon CloudFormation generates a unique physical ID and uses that ID for the rule name. For more information, see Name Type.
Required: No
Type: String
Pattern:
.*\S.*
Minimum:
1
Maximum:
128
Update requires: Replacement
Description
-
The description that you provide for the Amazon Config rule.
Required: No
Type: String
Minimum:
0
Maximum:
256
Update requires: No interruption
EvaluationModes
-
The modes the Amazon Config rule can be evaluated in. The valid values are distinct objects. By default, the value is Detective evaluation mode only.
Required: No
Type: Array of EvaluationModeConfiguration
Update requires: No interruption
InputParameters
-
A string, in JSON format, that is passed to the Amazon Config rule Lambda function.
Required: No
Type: Json
Minimum:
1
Maximum:
1024
Update requires: No interruption
MaximumExecutionFrequency
-
The maximum frequency with which Amazon Config runs evaluations for a rule. You can specify a value for
MaximumExecutionFrequency
when:-
You are using an Amazon managed rule that is triggered at a periodic frequency.
-
Your custom rule is triggered when Amazon Config delivers the configuration snapshot. For more information, see ConfigSnapshotDeliveryProperties.
Note
By default, rules with a periodic trigger are evaluated every 24 hours. To change the frequency, specify a valid value for the
MaximumExecutionFrequency
parameter.Required: No
Type: String
Allowed values:
One_Hour | Six_Hours | Three_Hours | Twelve_Hours | TwentyFour_Hours
Update requires: No interruption
-
Scope
-
Defines which resources can trigger an evaluation for the rule. The scope can include one or more resource types, a combination of one resource type and one resource ID, or a combination of a tag key and value. Specify a scope to constrain the resources that can trigger an evaluation for the rule. If you do not specify a scope, evaluations are triggered when any resource in the recording group changes.
Note
The scope can be empty.
Required: No
Type: Scope
Update requires: No interruption
Source
-
Provides the rule owner (
Amazon
for managed rules,CUSTOM_POLICY
for Custom Policy rules, andCUSTOM_LAMBDA
for Custom Lambda rules), the rule identifier, and the notifications that cause the function to evaluate your Amazon resources.Required: Yes
Type: Source
Update requires: No interruption
Return values
Ref
When you pass the logical ID of this resource to the intrinsic Ref
function, Ref
returns the rule name, such as mystack-MyConfigRule-12ABCFPXHV4OV
.
For more information about using the Ref
function, see Ref
.
Fn::GetAtt
The Fn::GetAtt
intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.
For more information about using the Fn::GetAtt
intrinsic function, see Fn::GetAtt
.
Arn
-
The Amazon Resource Name (ARN) of the Amazon Config rule, such as
arn:aws:config:us-east-1:123456789012:config-rule/config-rule-a1bzhi
. ConfigRuleId
-
The ID of the Amazon Config rule, such as
config-rule-a1bzhi
. Type
Property description not available.
Examples
Config Rule
The following example uses an Amazon managed rule that checks whether EC2 volumes resource types have a CostCenter tag.
JSON
"ConfigRuleForVolumeTags": { "Type": "AWS::Config::ConfigRule", "Properties": { "InputParameters": {"tag1Key": "CostCenter"}, "Scope": { "ComplianceResourceTypes": ["AWS::EC2::Volume"] }, "Source": { "Owner": "AWS", "SourceIdentifier": "REQUIRED_TAGS" } } }
YAML
ConfigRuleForVolumeTags: Type: AWS::Config::ConfigRule Properties: InputParameters: | {"tag1Key": "CostCenter"} Scope: ComplianceResourceTypes: - "AWS::EC2::Volume" Source: Owner: AWS SourceIdentifier: "REQUIRED_TAGS"
Create Rule Using Lambda Function
The following example creates a custom configuration rule that uses a Lambda function. The function checks whether an EC2 volume has the AutoEnableIO property set to true. Note that the configuration rule has a dependency on the Lambda policy so that the rule calls the function only after it's permitted to do so.
After you create a rule using Lambda it is recommended you update the permissions based on the Update Rule Using Lambda Function with SourceArn based permission example which restricts only a specific rule ARN to invoke the Lambda function. This helps make sure Amazon Lambda is accessing your resources on behalf of expected users and scenarios only.
JSON
"ConfigPermissionToCallLambda": { "Type": "AWS::Lambda::Permission", "Properties": { "FunctionName": {"Fn::GetAtt": ["VolumeAutoEnableIOComplianceCheck", "Arn"]}, "Action": "lambda:InvokeFunction", "Principal": "config.amazonaws.com", "SourceAccount": {"Ref": "AWS::AccountId" } } }, "VolumeAutoEnableIOComplianceCheck": { "Type": "AWS::Lambda::Function", "Properties": { "Code": { "ZipFile": {"Fn::Join": ["\n", [ "var aws = require('aws-sdk');", "var config = new aws.ConfigService();", "var ec2 = new aws.EC2();", "exports.handler = function(event, context) {", " compliance = evaluateCompliance(event, function(compliance, event) {", " var configurationItem = JSON.parse(event.invokingEvent).configurationItem;", " var putEvaluationsRequest = {", " Evaluations: [{", " ComplianceResourceType: configurationItem.resourceType,", " ComplianceResourceId: configurationItem.resourceId,", " ComplianceType: compliance,", " OrderingTimestamp: configurationItem.configurationItemCaptureTime", " }],", " ResultToken: event.resultToken", " };", " config.putEvaluations(putEvaluationsRequest, function(err, data) {", " if (err) context.fail(err);", " else context.succeed(data);", " });", " });", "};", "function evaluateCompliance(event, doReturn) {", " var configurationItem = JSON.parse(event.invokingEvent).configurationItem;", " var status = configurationItem.configurationItemStatus;", " if (configurationItem.resourceType !== 'AWS::EC2::Volume' || event.eventLeftScope || (status !== 'OK' && status !== 'ResourceDiscovered'))", " doReturn('NOT_APPLICABLE', event);", " else ec2.describeVolumeAttribute({VolumeId: configurationItem.resourceId, Attribute: 'autoEnableIO'}, function(err, data) {", " if (err) context.fail(err);", " else if (data.AutoEnableIO.Value) doReturn('COMPLIANT', event);", " else doReturn('NON_COMPLIANT', event);", " });", "}" ]]} }, "Handler": "index.handler", "Runtime": "nodejs12.x", "Timeout": "30", "Role": {"Fn::GetAtt": ["LambdaExecutionRole", "Arn"]} } }, "ConfigRuleForVolumeAutoEnableIO": { "Type": "AWS::Config::ConfigRule", "Properties": { "ConfigRuleName": "ConfigRuleForVolumeAutoEnableIO", "Scope": { "ComplianceResourceId": {"Ref": "Ec2Volume"}, "ComplianceResourceTypes": ["AWS::EC2::Volume"] }, "Source": { "Owner": "CUSTOM_LAMBDA", "SourceDetails": [{ "EventSource": "aws.config", "MessageType": "ConfigurationItemChangeNotification" }], "SourceIdentifier": {"Fn::GetAtt": ["VolumeAutoEnableIOComplianceCheck", "Arn"]} } }, "DependsOn": "ConfigPermissionToCallLambda" }
YAML
ConfigPermissionToCallLambda: Type: AWS::Lambda::Permission Properties: FunctionName: Fn::GetAtt: - VolumeAutoEnableIOComplianceCheck - Arn Action: "lambda:InvokeFunction" Principal: "config.amazonaws.com" SourceAccount: !Ref 'AWS::AccountId' VolumeAutoEnableIOComplianceCheck: Type: AWS::Lambda::Function Properties: Code: ZipFile: !Sub | var aws = require('aws-sdk'); var config = new aws.ConfigService(); var ec2 = new aws.EC2(); exports.handler = function(event, context) { compliance = evaluateCompliance(event, function(compliance, event) { var configurationItem = JSON.parse(event.invokingEvent).configurationItem; var putEvaluationsRequest = { Evaluations: [{ ComplianceResourceType: configurationItem.resourceType, ComplianceResourceId: configurationItem.resourceId, ComplianceType: compliance, OrderingTimestamp: configurationItem.configurationItemCaptureTime }], ResultToken: event.resultToken }; config.putEvaluations(putEvaluationsRequest, function(err, data) { if (err) context.fail(err); else context.succeed(data); }); }); }; function evaluateCompliance(event, doReturn) { var configurationItem = JSON.parse(event.invokingEvent).configurationItem; var status = configurationItem.configurationItemStatus; if (configurationItem.resourceType !== 'AWS::EC2::Volume' || event.eventLeftScope || (status !== 'OK' && status !== 'ResourceDiscovered')) doReturn('NOT_APPLICABLE', event); else ec2.describeVolumeAttribute({VolumeId: configurationItem.resourceId, Attribute: 'autoEnableIO'}, function(err, data) { if (err) context.fail(err); else if (data.AutoEnableIO.Value) doReturn('COMPLIANT', event); else doReturn('NON_COMPLIANT', event); }); } Handler: "index.handler" Runtime: nodejs12.x Timeout: 30 Role: Fn::GetAtt: - LambdaExecutionRole - Arn ConfigRuleForVolumeAutoEnableIO: Type: AWS::Config::ConfigRule Properties: ConfigRuleName: ConfigRuleForVolumeAutoEnableIO Scope: ComplianceResourceId: Ref: Ec2Volume ComplianceResourceTypes: - "AWS::EC2::Volume" Source: Owner: "CUSTOM_LAMBDA" SourceDetails: - EventSource: "aws.config" MessageType: "ConfigurationItemChangeNotification" SourceIdentifier: Fn::GetAtt: - VolumeAutoEnableIOComplianceCheck - Arn DependsOn: ConfigPermissionToCallLambda
Update Rule Using Lambda Function with SourceArn based permission
After an Amazon Config rule has been created, there is a sourceARN
which is the ARN of the Amazon Config rule that is invoking the Lambda function.
The following example includes sourceARN
based permission to restrict only a specific rule ARN to invoke the Lambda function.
It is recommended after you create a rule that you update with these more restrictive permissions to help make sure Amazon Lambda is accessing your resources on behalf of expected users and scenarios only.
JSON
"ConfigPermissionToCallLambda": { "Type": "AWS::Lambda::Permission", "Properties": { "FunctionName": {"Fn::GetAtt": ["VolumeAutoEnableIOComplianceCheck", "Arn"]}, "Action": "lambda:InvokeFunction", "Principal": "config.amazonaws.com", "SourceAccount": {"Ref": "AWS::AccountId" }, "SourceArn": {"Fn::GetAtt": [ "ConfigRuleForVolumeAutoEnableIO", "Arn" ] } } }, "VolumeAutoEnableIOComplianceCheck": { "Type": "AWS::Lambda::Function", "Properties": { "Code": { "ZipFile": {"Fn::Join": ["\n", [ "var aws = require('aws-sdk');", "var config = new aws.ConfigService();", "var ec2 = new aws.EC2();", "exports.handler = function(event, context) {", " compliance = evaluateCompliance(event, function(compliance, event) {", " var configurationItem = JSON.parse(event.invokingEvent).configurationItem;", " var putEvaluationsRequest = {", " Evaluations: [{", " ComplianceResourceType: configurationItem.resourceType,", " ComplianceResourceId: configurationItem.resourceId,", " ComplianceType: compliance,", " OrderingTimestamp: configurationItem.configurationItemCaptureTime", " }],", " ResultToken: event.resultToken", " };", " config.putEvaluations(putEvaluationsRequest, function(err, data) {", " if (err) context.fail(err);", " else context.succeed(data);", " });", " });", "};", "function evaluateCompliance(event, doReturn) {", " var configurationItem = JSON.parse(event.invokingEvent).configurationItem;", " var status = configurationItem.configurationItemStatus;", " if (configurationItem.resourceType !== 'AWS::EC2::Volume' || event.eventLeftScope || (status !== 'OK' && status !== 'ResourceDiscovered'))", " doReturn('NOT_APPLICABLE', event);", " else ec2.describeVolumeAttribute({VolumeId: configurationItem.resourceId, Attribute: 'autoEnableIO'}, function(err, data) {", " if (err) context.fail(err);", " else if (data.AutoEnableIO.Value) doReturn('COMPLIANT', event);", " else doReturn('NON_COMPLIANT', event);", " });", "}" ]]} }, "Handler": "index.handler", "Runtime": "nodejs12.x", "Timeout": "30", "Role": {"Fn::GetAtt": ["LambdaExecutionRole", "Arn"]} } }, "ConfigRuleForVolumeAutoEnableIO": { "Type": "AWS::Config::ConfigRule", "Properties": { "ConfigRuleName": "ConfigRuleForVolumeAutoEnableIO", "Scope": { "ComplianceResourceId": {"Ref": "Ec2Volume"}, "ComplianceResourceTypes": ["AWS::EC2::Volume"] }, "Source": { "Owner": "CUSTOM_LAMBDA", "SourceDetails": [{ "EventSource": "aws.config", "MessageType": "ConfigurationItemChangeNotification" }], "SourceIdentifier": {"Fn::GetAtt": ["VolumeAutoEnableIOComplianceCheck", "Arn"]} } }, "DependsOn": "ConfigPermissionToCallLambda" }
YAML
ConfigPermissionToCallLambda: Type: AWS::Lambda::Permission Properties: FunctionName: Fn::GetAtt: - VolumeAutoEnableIOComplianceCheck - Arn Action: "lambda:InvokeFunction" Principal: "config.amazonaws.com" SourceAccount: !Ref 'AWS::AccountId' SourceArn: Fn::GetAtt: - VolumeAutoEnableIOComplianceCheck - Arn VolumeAutoEnableIOComplianceCheck: Type: AWS::Lambda::Function Properties: Code: ZipFile: !Sub | var aws = require('aws-sdk'); var config = new aws.ConfigService(); var ec2 = new aws.EC2(); exports.handler = function(event, context) { compliance = evaluateCompliance(event, function(compliance, event) { var configurationItem = JSON.parse(event.invokingEvent).configurationItem; var putEvaluationsRequest = { Evaluations: [{ ComplianceResourceType: configurationItem.resourceType, ComplianceResourceId: configurationItem.resourceId, ComplianceType: compliance, OrderingTimestamp: configurationItem.configurationItemCaptureTime }], ResultToken: event.resultToken }; config.putEvaluations(putEvaluationsRequest, function(err, data) { if (err) context.fail(err); else context.succeed(data); }); }); }; function evaluateCompliance(event, doReturn) { var configurationItem = JSON.parse(event.invokingEvent).configurationItem; var status = configurationItem.configurationItemStatus; if (configurationItem.resourceType !== 'AWS::EC2::Volume' || event.eventLeftScope || (status !== 'OK' && status !== 'ResourceDiscovered')) doReturn('NOT_APPLICABLE', event); else ec2.describeVolumeAttribute({VolumeId: configurationItem.resourceId, Attribute: 'autoEnableIO'}, function(err, data) { if (err) context.fail(err); else if (data.AutoEnableIO.Value) doReturn('COMPLIANT', event); else doReturn('NON_COMPLIANT', event); }); } Handler: "index.handler" Runtime: nodejs12.x Timeout: 30 Role: Fn::GetAtt: - LambdaExecutionRole - Arn ConfigRuleForVolumeAutoEnableIO: Type: AWS::Config::ConfigRule Properties: ConfigRuleName: ConfigRuleForVolumeAutoEnableIO Scope: ComplianceResourceId: Ref: Ec2Volume ComplianceResourceTypes: - "AWS::EC2::Volume" Source: Owner: "CUSTOM_LAMBDA" SourceDetails: - EventSource: "aws.config" MessageType: "ConfigurationItemChangeNotification" SourceIdentifier: Fn::GetAtt: - VolumeAutoEnableIOComplianceCheck - Arn DependsOn: ConfigPermissionToCallLambda