Syntax Properties Return values Examples

AWS::Config::ConfigRule

Adds or updates an AWS Config rule to evaluate if your AWS resources comply with your desired configurations. For information on how many AWS Config rules you can have per account, see Service Limits in the AWS Config Developer Guide.

There are two types of rules: AWS Config Managed Rules and AWS Config Custom Rules. You can use the ConfigRule resource to create both AWS Config Managed Rules and AWS Config Custom Rules.

AWS Config Managed Rules are predefined, customizable rules created by AWS Config. For a list of managed rules, see List of AWS Config Managed Rules. If you are adding an AWS Config managed rule, you must specify the rule's identifier for the SourceIdentifier key.

AWS Config Custom Rules are rules that you create from scratch. There are two ways to create AWS Config custom rules: with Lambda functions (AWS Lambda Developer Guide) and with Guard (Guard GitHub Repository), a policy-as-code language. AWS Config custom rules created with AWS Lambda are called AWS Config Custom Lambda Rules and AWS Config custom rules created with Guard are called AWS Config Custom Policy Rules.

If you are adding a newAWS Config Custom Lambda rule, you first need to create an AWS Lambda function that the rule invokes to evaluate your resources. When you use the ConfigRule resource to add a Custom Lambda rule to AWS Config, you must specify the Amazon Resource Name (ARN) that AWS 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 AWS 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 AWS 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 AWS Config rules, see Evaluating Resources with AWS Config Rules in the AWS Config Developer Guide.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON


{
  "Type" : "AWS::Config::ConfigRule",
  "Properties" : {
      "ConfigRuleName" : String,
      "Description" : String,
      "InputParameters" : Json,
      "MaximumExecutionFrequency" : String,
      "Scope" : Scope,
      "Source" : Source
    }
}

YAML


Type: AWS::Config::ConfigRule
Properties: 
  ConfigRuleName: String
  Description: String
  InputParameters: Json
  MaximumExecutionFrequency: String
  Scope: 
    Scope
  Source: 
    Source

Properties

ConfigRuleName

A name for the AWS Config rule. If you don't specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the rule name. For more information, see Name Type.

Required: No

Type: String

Minimum: 1

Maximum: 128

Pattern: .*\S.*

Update requires: Replacement

Description

The description that you provide for the AWS Config rule.

Required: No

Type: String

Minimum: 0

Maximum: 256

Update requires: No interruption

InputParameters

A string, in JSON format, that is passed to the AWS Config rule Lambda function.

Required: No

Type: Json

Minimum: 1

Maximum: 1024

Update requires: No interruption

MaximumExecutionFrequency

The maximum frequency with which AWS Config runs evaluations for a rule. You can specify a value for MaximumExecutionFrequency when:

You are using an AWS managed rule that is triggered at a periodic frequency.
Your custom rule is triggered when AWS 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 (AWS for managed rules, CUSTOM_POLICY for Custom Policy rules, and CUSTOM_LAMBDA for Custom Lambda rules), the rule identifier, and the notifications that cause the function to evaluate your AWS resources.

Required: Yes

Type: Source

Update requires: No interruption

Return values

Ref

When you pass the logical ID of this resource to the intrinsic Reffunction, Refreturns the rule name, such as mystack-MyConfigRule-12ABCFPXHV4OV.

For more information about using the Reffunction, see Ref.

Fn::GetAtt

The Fn::GetAttintrinsic 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::GetAttintrinsic function, see Fn::GetAtt.

Arn: The Amazon Resource Name (ARN) of the AWS Config rule, such as arn:aws:config:us-east-1:123456789012:config-rule/config-rule-a1bzhi.
Compliance.Type: The compliance status of an AWS Config rule, such as COMPLIANT or NON_COMPLIANT.
ConfigRuleId: The ID of the AWS Config rule, such as config-rule-a1bzhi.

Examples

Config Rule

The following example uses an AWS 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 AWS 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 AWS Config rule has been created, there is a sourceARN which is the ARN of the AWS 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 AWS 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

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

AWS::Config::AggregationAuthorization

CustomPolicyDetails