编写 Guard 规则来评估 Guard Hooks 的资源

AWS CloudFormation Guard 是一种开源的通用域特定语言 (DSL)，可用于编写策略即代码。本主题介绍如何使用 Guard 编写示例规则，这些规则可在 Guard Hook 中运行以自动评估 CloudFormation 和 AWS 云端控制 API 操作。它还将重点介绍您的警卫规则可用的不同输入类型，具体取决于您的 Guard Hook 运行时间。可以将 Guard Hook 配置为在以下类型的操作期间运行：

资源操作
堆栈操作
更改集合操作

有关编写 Guard 规则的更多信息，请参阅编写 AWS CloudFormation Guard 规则

资源操作守护规则

每当您创建、更新或删除资源时，这都被视为资源操作。例如，如果您运行更新 CloudFormation 堆栈以创建新资源，则您已经完成了资源操作。当您使用 Cloud Control API 创建、更新或删除资源时，这也被视为资源操作。您可以在 Hook 的配置中将 Guard Hook TargetOperations 配置为目标RESOURCE和CLOUD_CONTROL操作。当您的 Guard Hook 评估资源操作时，Guard 引擎会评估资源输入。

主题

保护资源输入语法
Guard 资源操作输入示例
资源变更的保护规则

保护资源输入语法

Guard 资源输入是可供您的 Guard 规则评估的数据。

以下是资源输入的示例形状：


HookContext:
  AWSAccountID: String
  StackId: String
  HookTypeName: String
  HookTypeVersion: String
  InvocationPoint: [CREATE_PRE_PROVISION, UPDATE_PRE_PROVISION, DELETE_PRE_PROVISION]
  TargetName: String
  TargetType: RESOURCE
  TargetLogicalId: String
  ChangeSetId: String
Resources:
  {ResourceLogicalID}:
    ResourceType: {ResourceType}
    ResourceProperties:
        {ResourceProperties}
Previous:
  ResourceLogicalID:
    ResourceType: {ResourceType}
    ResourceProperties:
        {PreviousResourceProperties}

HookContext

AWSAccountID

AWS 账户包含正在评估的资源的 ID。

StackId

作为资源操作一部分的 CloudFormation 堆栈的堆栈 ID。如果调用方是 Cloud Control API，则此字段为空。

HookTypeName

正在运行的 Hook 的名称。

HookTypeVersion

正在运行的 Hook 的版本。

InvocationPoint

配置逻辑中 Hook 运行的确切点。

有效值：(CREATE_PRE_PROVISION| UPDATE_PRE_PROVISION |DELETE_PRE_PROVISION)

TargetName

正在评估的目标类型，例如AWS::S3::Bucket。

TargetType

例如，正在评估的目标类型AWS::S3::Bucket。对于使用云控制 API 配置的资源，此值将RESOURCE为。

TargetLogicalId

正在评估TargetLogicalId的资源的。如果 Hook 的来源是 CloudFormation，这将是资源的逻辑 ID（也称为逻辑名称）。如果挂钩的来源是云控制 API，则这将是一个构造值。

ChangeSetId

为导致 Hook 调用而执行的更改集 ID。如果资源更改是由 Cloud Control API 或、或delete-stack操作启动的 create-stackupdate-stack，则此值为空。

Resources

ResourceLogicalID

当操作由启动时 CloudFormation，ResourceLogicalID是 CloudFormation 模板中资源的逻辑 ID。

当操作由 Cloud Control API 启动时，ResourceLogicalID是资源类型、名称、操作 ID 和请求 ID 的组合。

ResourceType

资源的类型名称（例如：AWS::S3::Bucket）。

ResourceProperties

正在修改的资源的拟议属性。当 Guard Hook 针对 CloudFormation 资源变化运行时，所有函数、参数和转换都将完全解析。如果要删除资源，则此值将为空。

Previous

ResourceLogicalID

当操作由启动时 CloudFormation，ResourceLogicalID是 CloudFormation 模板中资源的逻辑 ID。

当操作由 Cloud Control API 启动时，ResourceLogicalID是资源类型、名称、操作 ID 和请求 ID 的组合。

ResourceType

资源的类型名称（例如：AWS::S3::Bucket）。

ResourceProperties

与正在修改的资源相关的当前属性。如果要删除资源，则此值将为空。

Guard 资源操作输入示例

以下示例输入显示了一个 Guard Hook，它将接收要更新的AWS::S3::Bucket资源的定义。这是 Guard 可用于评估的数据。


HookContext:
  AwsAccountId: "123456789012"
  StackId: "arn:aws:cloudformation:us-west-2:123456789012:stack/MyStack/1a2345b6-0000-00a0-a123-00abc0abc000"
  HookTypeName: org::s3policy::hook
  HookTypeVersion: "00001"
  InvocationPoint: UPDATE_PRE_PROVISION
  TargetName: AWS::S3::Bucket
  TargetType: RESOURCE
  TargetLogicalId: MyS3Bucket
  ChangeSetId: ""
Resources:
  MyS3Bucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: amzn-s3-demo-bucket
      ObjectLockEnabled: true
Previous:
  MyS3Bucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: amzn-s3-demo-bucket
      ObjectLockEnabled: false

要查看该资源类型的所有可用属性，请参阅AWS::S3::Bucket。

资源变更的保护规则

当 Guard Hook 评估资源变化时，它首先下载使用该挂钩配置的所有规则。然后根据资源输入评估这些规则。如果任何规则评估失败，Hook 将失败。如果没有故障，Hook 将通过。

以下示例是一条 Guard 规则，用于评估该ObjectLockEnabled属性是否true适用于任何AWS::S3::Bucket资源类型。


let s3_buckets_default_lock_enabled = Resources.*[ Type == 'AWS::S3::Bucket']

rule S3_BUCKET_DEFAULT_LOCK_ENABLED when %s3_buckets_default_lock_enabled !empty {
  %s3_buckets_default_lock_enabled.Properties.ObjectLockEnabled exists
  %s3_buckets_default_lock_enabled.Properties.ObjectLockEnabled == true
  <<
    Violation: S3 Bucket ObjectLockEnabled must be set to true.
    Fix: Set the S3 property ObjectLockEnabled parameter to true.
  >>
}

当此规则针对以下输入运行时，它将失败，因为该ObjectLockEnabled属性未设置为true。


Resources:
  MyS3Bucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: amzn-s3-demo-bucket 
      ObjectLockEnabled: false

当此规则针对以下输入运行时，它将传递，因为设置ObjectLockEnabled为true。


Resources:
  MyS3Bucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: amzn-s3-demo-bucket
      ObjectLockEnabled: true

当挂钩失败时，失败的规则将传播回我们的 CloudFormation 云控制 API。如果已为 Guard Hook 配置了日志存储桶，则将在此处提供其他规则反馈。此附加反馈包括Violation和Fix信息。

堆栈操作守护规则

创建、更新或删除 CloudFormation 堆栈时，您可以将 Guard Hook 配置为从评估新模板开始，并可能阻止堆栈操作继续进行。您可以在 Hook 的配置中将 Guard Hook TargetOperations 配置为目标STACK操作。

主题

保护堆栈输入语法
Guard 堆栈操作输入示例
堆栈变更的保护规则

保护堆栈输入语法

Guard 堆栈操作的输入为您的警卫规则提供了完整的 CloudFormation模板供您评估。

以下是堆栈输入的示例形状：


HookContext:
  AWSAccountID: String
  StackId: String
  HookTypeName: String
  HookTypeVersion: String
  InvocationPoint: [CREATE_PRE_PROVISION, UPDATE_PRE_PROVISION, DELETE_PRE_PROVISION]
  TargetName: String
  TargetType:STACK
  ChangeSetId: String
{Proposed CloudFormation Template}
Previous:
    {CloudFormation Template}

HookContext

AWSAccountID

AWS 账户包含资源的 ID。

StackId

作为堆栈操作一部分的 CloudFormation 堆栈的堆栈 ID。

HookTypeName

正在运行的 Hook 的名称。

HookTypeVersion

正在运行的 Hook 的版本。

InvocationPoint

配置逻辑中 Hook 运行的确切点。

有效值：(CREATE_PRE_PROVISION| UPDATE_PRE_PROVISION |DELETE_PRE_PROVISION)

TargetName

正在评估的堆栈的名称。

TargetType

当作为堆栈级 Hook 运行STACK时，该值将为。

ChangeSetId

为导致 Hook 调用而执行的更改集 ID。如果堆栈操作由、或delete-stack操作启动 create-stackupdate-stack，则此值为空。

Proposed CloudFormation Template

传递给 CloudFormationcreate-stack或update-stack操作的完整 CloudFormation 模板值。这包括ResourcesOutputs、和之类的内容Properties。它可以是 JSON 或 YAML 字符串，具体取决于提供给 CloudFormation的内容。

在delete-stack操作中，此值将为空。

Previous

上次成功部署的 CloudFormation 模板。如果正在创建或删除堆栈，则此值为空。

在delete-stack操作中，此值将为空。

注意

提供的模板是传入create或update堆栈操作的模板。删除堆栈时，不提供模板值。

Guard 堆栈操作输入示例

以下示例输入显示了将接收完整模板和先前部署的模板的 Guard Hook。此示例中的模板使用 JSON 格式。


HookContext:
  AwsAccountId: 123456789012
  StackId: "arn:aws:cloudformation:us-west-2:123456789012:stack/MyStack/1a2345b6-0000-00a0-a123-00abc0abc000"
  HookTypeName: org::templatechecker::hook
  HookTypeVersion: "00001"
  InvocationPoint: UPDATE_PRE_PROVISION
  TargetName: MyStack
  TargetType: CHANGE_SET
  TargetLogicalId: arn:aws:cloudformation:us-west-2:123456789012:changeSet/SampleChangeSet/1a2345b6-0000-00a0-a123-00abc0abc000
  ChangeSetId: arn:aws:cloudformation:us-west-2:123456789012:changeSet/SampleChangeSet/1a2345b6-0000-00a0-a123-00abc0abc000
Resources: {
   "S3Bucket": {
        "Type": "AWS::S3::Bucket",
        "Properties": {
           "BucketEncryption": {
               "ServerSideEncryptionConfiguration": [ 
                {"ServerSideEncryptionByDefault": 
                    {"SSEAlgorithm": "aws:kms", 
                      "KMSMasterKeyID": "KMS-KEY-ARN" }, 
                      "BucketKeyEnabled": true } 
                ] 
           }
        }
}
Previous: {
    "AWSTemplateFormatVersion": "2010-09-09",
    "Resources": {
        "S3Bucket": {
            "Type": "AWS::S3::Bucket",
            "Properties": {}
        }
    }
}

堆栈变更的保护规则

当 Guard Hook 评估堆栈变化时，它首先下载使用该挂钩配置的所有规则。然后根据资源输入评估这些规则。如果任何规则评估失败，Hook 将失败。如果没有故障，Hook 将通过。

以下示例是一条 Guard 规则，该规则评估是否有任何AWS::S3::Bucket资源类型包含名为的属性BucketEncryption，该属性SSEAlgorithm设置为aws:kms或AES256。


let s3_buckets_s3_default_encryption = Resources.*[ Type == 'AWS::S3::Bucket']

rule S3_DEFAULT_ENCRYPTION_KMS when %s3_buckets_s3_default_encryption !empty {
  %s3_buckets_s3_default_encryption.Properties.BucketEncryption exists
  %s3_buckets_s3_default_encryption.Properties.BucketEncryption.ServerSideEncryptionConfiguration[*].ServerSideEncryptionByDefault.SSEAlgorithm in ["aws:kms","AES256"]
  <<
    Violation: S3 Bucket default encryption must be set.
    Fix: Set the S3 Bucket property BucketEncryption.ServerSideEncryptionConfiguration.ServerSideEncryptionByDefault.SSEAlgorithm to either "aws:kms" or "AES256"
  >>
}

当规则针对以下模板运行时，它会fail。


AWSTemplateFormatVersion: 2010-09-09
Description: S3 bucket without default encryption
Resources:
  EncryptedS3Bucket:
    Type: 'AWS::S3::Bucket'
    Properties:
      BucketName: !Sub 'encryptedbucket-${AWS::Region}-${AWS::AccountId}'

当规则针对以下模板运行时，它会pass。


AWSTemplateFormatVersion: 2010-09-09
Description: S3 bucket with default encryption using SSE-KMS with an S3 Bucket Key
Resources:
  EncryptedS3Bucket:
    Type: 'AWS::S3::Bucket'
    Properties:
      BucketName: !Sub 'encryptedbucket-${AWS::Region}-${AWS::AccountId}'
      BucketEncryption:
        ServerSideEncryptionConfiguration:
          - ServerSideEncryptionByDefault:
              SSEAlgorithm: 'aws:kms'
              KMSMasterKeyID: KMS-KEY-ARN
            BucketKeyEnabled: true

更改设定的操作守卫规则

创建 CloudFormation 变更集时，您可以配置 Guard Hook 来评估模板和变更集中提出的更改，从而阻止变更集的执行。

主题

保护变更集输入语法
示例 Guard 变更集操作输入
变更集操作的保护规则

保护变更集输入语法

Guard 变更集输入是可供您的 Guard 规则评估的数据。

以下是变更集输入的示例形状：


HookContext:
  AWSAccountID: String
  StackId: String
  HookTypeName: String
  HookTypeVersion: String
  InvocationPoint: [CREATE_PRE_PROVISION, UPDATE_PRE_PROVISION, DELETE_PRE_PROVISION]
  TargetName: CHANGE_SET
  TargetType:CHANGE_SET
  TargetLogicalId:ChangeSet ID
  ChangeSetId: String
{Proposed CloudFormation Template}
Previous:
  {CloudFormation Template}
Changes: [{ResourceChange}]

ResourceChange模型语法是：


逻辑的 ResourceId: String 
resourceType: String
action: CREATE, UPDATE, DELETE
行号: Number
在上下文之前: JSON String
后置上下文: JSON String

HookContext

AWSAccountID

AWS 账户包含资源的 ID。

StackId

作为堆栈操作一部分的 CloudFormation 堆栈的堆栈 ID。

HookTypeName

正在运行的 Hook 的名称。

HookTypeVersion

正在运行的 Hook 的版本。

InvocationPoint

配置逻辑中 Hook 运行的确切点。

有效值：(CREATE_PRE_PROVISION| UPDATE_PRE_PROVISION |DELETE_PRE_PROVISION)

TargetName

正在评估的堆栈的名称。

TargetType

当作为变更集级别 Hook 运行CHANGE_SET时，该值将为。

TargetLogicalId

该值将是变更集的 ARN。

ChangeSetId

为导致 Hook 调用而执行的更改集 ID。如果堆栈操作由、或delete-stack操作启动 create-stackupdate-stack，则此值为空。

Proposed CloudFormation Template

为create-change-set操作提供的完整 CloudFormation 模板。它可以是 JSON 或 YAML 字符串，具体取决于提供给 CloudFormation的内容。

Previous

上次成功部署的 CloudFormation 模板。如果正在创建或删除堆栈，则此值为空。

Changes

Changes模型。这列出了资源更改。

更改

逻辑的 ResourceId

已更改资源的逻辑资源名称。

resourceType

将要更改的资源类型。

action

对资源执行的操作的类型。

有效值：(CREATE| UPDATE |DELETE)

行号

模板中与更改相关的行号。

在上下文之前

更改前资源属性的 JSON 字符串：


{"properties": {"property1": "value"}}

后置上下文

更改后资源属性的 JSON 字符串：


{"properties": {"property1": "new value"}}

示例 Guard 变更集操作输入

以下示例输入显示了将接收完整模板、之前部署的模板和资源更改列表的 Guard Hook。此示例中的模板使用 JSON 格式。


HookContext:
  AwsAccountId: "00000000"
  StackId: MyStack
  HookTypeName: org::templatechecker::hook
  HookTypeVersion: "00001"
  InvocationPoint: UPDATE_PRE_PROVISION
  TargetName: my-example-stack
  TargetType:STACK
  TargetLogicalId: arn...:changeSet/change-set
  ChangeSetId: ""
Resources: {
    "S3Bucket": {
       "Type": "AWS::S3::Bucket",
       "Properties": {
           "BucketName": "amzn-s3-demo-bucket",
           "VersioningConfiguration":{
              "Status": "Enabled"
            }                
         }
    }
Previous: {
    "AWSTemplateFormatVersion": "2010-09-09",
    "Resources": {
        "S3Bucket": {
            "Type": "AWS::S3::Bucket",
            "Properties": {
                "BucketName": "amzn-s3-demo-bucket",
                "VersioningConfiguration":{
                  "Status": "Suspended"
                }
            }
        }
    }
}
Changes: [
  {
    "logicalResourceId": "S3Bucket",
    "resourceType": "AWS::S3::Bucket",
    "action": "UPDATE",
    "lineNumber": 5,
    "beforeContext": "{\"Properties\":{\"VersioningConfiguration\":{\"Status\":\"Suspended\"}}}",
    "afterContext": "{\"Properties\":{\"VersioningConfiguration\":{\"Status\":\"Enabled\"}}}"
  }
]

变更集操作的保护规则

以下示例是一条 Guard 规则，用于评估 Amazon S3 存储桶的更改，并确保该更改未VersionConfiguration被禁用。


let s3_buckets_changing = Changes[resourceType == 'AWS::S3::Bucket']

rule S3_VERSIONING_STAY_ENABLED when %s3_buckets_changing !empty {
    let afterContext = json_parse(%s3_buckets_changing.afterContext)
    when %afterContext.Properties.VersioningConfiguration.Status !empty {
        %afterContext.Properties.VersioningConfiguration.Status == 'Enabled'
    }
}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

Guard 挂钩