翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# ガードフックのリソースを評価するためのガードルールを記述する
<a name="guard-hooks-write-rules"></a>

AWS CloudFormation Guard は、policy-as-codeの作成に使用できるオープンソースおよび汎用のドメイン固有の言語 (DSL) です。このトピックでは、Guard を使用して Guard Hook で実行できるサンプルルールを作成し、CloudFormation と AWS クラウドコントロール API オペレーションを自動的に評価する方法について説明します。また、ガードフックの実行時期に応じて、ガードルールで使用できるさまざまなタイプの入力にも焦点を当てます。ガードフックは、次のタイプのオペレーション中に実行するように設定できます。
+ リソースオペレーション
+ スタックオペレーション
+ 変更セットオペレーション

ガードルールの記述の詳細については、[「ルールの記述 AWS CloudFormation Guard](https://docs.aws.amazon.com/cfn-guard/latest/ug/writing-rules.html)」を参照してください。

**Topics**
+ [リソースオペレーションのガードルール](#guard-hooks-write-rules-resource-operations)
+ [スタックオペレーションのガードルール](#guard-hooks-write-rules-stack-operations)
+ [変更セットオペレーションのガードルール](#guard-hooks-write-rules-change-set-operations)

## リソースオペレーションのガードルール
<a name="guard-hooks-write-rules-resource-operations"></a>

リソースを作成、更新、または削除するときはいつでも、リソースオペレーションと見なされます。例えば、新しいリソースを作成する CloudFormation スタックの更新を実行すると、リソースオペレーションが完了しました。Cloud Control API を使用してリソースを作成、更新、または削除すると、リソースオペレーションとも見なされます。フックの設定で `RESOURCE`および `CLOUD_CONTROL`オペレーションをターゲットにするように ガードフック`TargetOperations`を設定できます。ガードフックがリソースオペレーションを評価すると、ガードエンジンはリソース入力を評価します。

**Topics**
+ [ガードリソース入力構文](#guard-hooks-write-rules-resource-operations-input)
+ [Guard リソースオペレーション入力の例](#guard-hooks-write-rules-resource-operations-example)
+ [リソース変更のガードルール](#guard-hooks-rules-resource-changes)

### ガードリソース入力構文
<a name="guard-hooks-write-rules-resource-operations-input"></a>

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`  <a name="guard-hook-resource-hookcontext"></a>  
`AWSAccountID`  <a name="guard-hook-resource-awsaccountid"></a>
評価対象のリソース AWS アカウント を含む の ID。  
`StackId`  <a name="guard-hook-resource-stackid"></a>
リソースオペレーションの一部である CloudFormation スタックのスタック ID。呼び出し元が Cloud Control API の場合、これは空です。  
`HookTypeName`  <a name="guard-hook-resource-hooktypename"></a>
実行中のフックの名前。  
`HookTypeVersion`  <a name="guard-hook-resource-hooktypeversion"></a>
実行中のフックのバージョン。  
`InvocationPoint`  <a name="guard-hook-resource-invocationpoint"></a>
フックが実行されるプロビジョニングロジックの正確なポイント。  
*有効な値*: (`CREATE_PRE_PROVISION` \$1 `UPDATE_PRE_PROVISION` \$1 `DELETE_PRE_PROVISION`)  
`TargetName`  <a name="guard-hook-resource-targetname"></a>
評価されるターゲットタイプ。例: `AWS::S3::Bucket`。  
`TargetType`  <a name="guard-hook-resource-targettype"></a>
評価されるターゲットタイプ。例: `AWS::S3::Bucket`。Cloud Control API でプロビジョニングされたリソースの場合、この値は になります`RESOURCE`。  
`TargetLogicalId`  <a name="guard-hook-resource-targetlogicalid"></a>
評価対象のリソース`TargetLogicalId`の 。フックのオリジンが CloudFormation の場合、これはリソースの論理 ID (論理名とも呼ばれます) になります。フックのオリジンが Cloud Control API の場合、これは構築された値になります。  
`ChangeSetId`  <a name="guard-hook-resource-changesetid"></a>
フック呼び出しを引き起こすために実行された変更セット ID。リソースの変更が Cloud Control API、、、`create-stack``update-stack`または `delete-stack`オペレーションによって開始された場合、この値は空です。

`Resources`  <a name="guard-hook-resource-resources"></a>  
`ResourceLogicalID`  <a name="guard-hook-resource-current-resourcelogicalid"></a>
オペレーションが CloudFormation によって開始されると、 `ResourceLogicalID`は CloudFormation テンプレート内のリソースの論理 ID です。  
オペレーションが Cloud Control API によって開始されると、 `ResourceLogicalID`はリソースタイプ、名前、オペレーション ID、リクエスト ID の組み合わせになります。  
`ResourceType`  <a name="guard-hook-resource-current-resourcetype"></a>
リソースのタイプ名 (例: `AWS::S3::Bucket`)。  
`ResourceProperties`  <a name="guard-hook-resource-current-resourceproperties"></a>
変更されるリソースの提案されたプロパティ。Guard Hook が CloudFormation リソースに対して実行されている場合、関数、パラメータ、変換はすべて完全に解決されます。リソースが削除されている場合、この値は空になります。

`Previous`  <a name="guard-hook-resource-previous"></a>  
`ResourceLogicalID`  <a name="guard-hook-resource-previous-resourcelogicalid"></a>
オペレーションが CloudFormation によって開始されると、 `ResourceLogicalID`は CloudFormation テンプレート内のリソースの論理 ID です。  
オペレーションが Cloud Control API によって開始されると、 `ResourceLogicalID`はリソースタイプ、名前、オペレーション ID、リクエスト ID の組み合わせになります。  
`ResourceType`  <a name="guard-hook-resource-previous-resourcetype"></a>
リソースのタイプ名 (例: `AWS::S3::Bucket`)。  
`ResourceProperties`  <a name="guard-hook-resource-previous-resourceproperties"></a>
変更するリソースに関連付けられている現在のプロパティ。リソースが削除されている場合、この値は空になります。

### Guard リソースオペレーション入力の例
<a name="guard-hooks-write-rules-resource-operations-example"></a>

次の入力例は、更新する`AWS::S3::Bucket`リソースの定義を受け取る Guard Hook を示しています。これは、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
```

リソースタイプで使用できるすべてのプロパティを確認するには、「」を参照してください[https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-s3-bucket.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-s3-bucket.html)。

### リソース変更のガードルール
<a name="guard-hooks-rules-resource-changes"></a>

ガードフックがリソースの変更を評価するとき、まずフックで設定されたすべてのルールをダウンロードします。これらのルールは、リソース入力に対して評価されます。いずれかのルールが評価に失敗すると、フックは失敗します。失敗がない場合、フックは成功します。

次の例は、 `ObjectLockEnabled`プロパティが任意の`AWS::S3::Bucket`リソースタイプ`true`用であるかどうかを評価する Guard ルールです。

```
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 または Cloud Control API に伝達されます。Guard Hook にログ記録バケットが設定されている場合、追加のルールフィードバックがそこで提供されます。この追加のフィードバックには、 `Violation`および `Fix`情報が含まれます。

## スタックオペレーションのガードルール
<a name="guard-hooks-write-rules-stack-operations"></a>

CloudFormation スタックが作成、更新、または削除されると、新しいテンプレートを評価してスタックオペレーションの進行をブロックできるように Guard Hook を設定できます。フックの設定で`STACK`オペレーションをターゲットにするように Guard Hook `TargetOperations` を設定できます。

**Topics**
+ [ガードスタックの入力構文](#guard-hooks-write-rules-stack-operations-input)
+ [Guard スタックオペレーション入力の例](#guard-hooks-write-rules-stack-operations-example)
+ [スタック変更のガードルール](#guard-hooks-rules-stack-changes)

### ガードスタックの入力構文
<a name="guard-hooks-write-rules-stack-operations-input"></a>

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`  <a name="guard-hook-stack-hookcontext"></a>  
`AWSAccountID`  <a name="guard-hook-stack-awsaccountid"></a>
リソース AWS アカウント を含む の ID。  
`StackId`  <a name="guard-hook-stack-stackid"></a>
スタックオペレーションの一部である CloudFormation スタックのスタック ID。  
`HookTypeName`  <a name="guard-hook-stack-hooktypename"></a>
実行中のフックの名前。  
`HookTypeVersion`  <a name="guard-hook-stack-hooktypeversion"></a>
実行中のフックのバージョン。  
`InvocationPoint`  <a name="guard-hook-stack-invocationpoint"></a>
フックが実行されるプロビジョニングロジックの正確なポイント。  
*有効な値*: (`CREATE_PRE_PROVISION` \$1 `UPDATE_PRE_PROVISION` \$1 `DELETE_PRE_PROVISION`)  
`TargetName`  <a name="guard-hook-stack-targetname"></a>
評価対象のスタックの名前。  
`TargetType`  <a name="guard-hook-stack-targettype"></a>
この値は、スタックレベルのフックとして を実行する`STACK`ときに になります。  
`ChangeSetId`  <a name="guard-hook-stack-changesetid"></a>
フック呼び出しを引き起こすために実行された変更セット ID。スタックオペレーションが `create-stack`、、または `delete-stack`オペレーションによって開始された場合`update-stack`、この値は空です。

`Proposed CloudFormation Template`  <a name="guard-hook-stack-template-current-template"></a>
CloudFormation `create-stack`または `update-stack`オペレーションに渡された CloudFormation テンプレートの完全な値。これには、`Resources`、、 `Outputs`などが含まれます`Properties`。CloudFormation に提供された内容に応じて、JSON または YAML 文字列にすることができます。  
`delete-stack` オペレーションでは、この値は空になります。

`Previous`  <a name="guard-hook-stack-template-previous-template"></a>
最後に正常にデプロイされた CloudFormation テンプレート。スタックを作成または削除する場合、この値は空です。  
`delete-stack` オペレーションでは、この値は空になります。

**注記**  
提供されるテンプレートは、 `create`または `update`スタックオペレーションに渡されます。スタックを削除する場合、テンプレート値は指定されません。

### Guard スタックオペレーション入力の例
<a name="guard-hooks-write-rules-stack-operations-example"></a>

次の入力例は、完全なテンプレートと以前にデプロイされたテンプレートを受け取る 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": {}
        }
    }
}
```

### スタック変更のガードルール
<a name="guard-hooks-rules-stack-changes"></a>

ガードフックがスタックの変更を評価するとき、まずフックで設定されたすべてのルールをダウンロードします。これらのルールは、リソース入力に対して評価されます。いずれかのルールが評価に失敗すると、フックは失敗します。失敗がない場合、フックは成功します。

次の例は、 または に`SSEAlgorithm`設定された `BucketEncryption`というプロパティを含む`AWS::S3::Bucket`リソースタイプがあるかどうかを評価する Guard `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
```

## 変更セットオペレーションのガードルール
<a name="guard-hooks-write-rules-change-set-operations"></a>

CloudFormation 変更セットが作成されると、変更セットで提案されたテンプレートと変更を評価して変更セットの実行をブロックするように Guard Hook を設定できます。

**Topics**
+ [ガード変更セットの入力構文](#guard-hooks-write-rules-change-set-operations-input)
+ [ガード変更セットオペレーション入力の例](#guard-hooks-write-rules-change-set-operations-example)
+ [変更セットオペレーションのガードルール](#guard-hooks-rules-change-set-operations)

### ガード変更セットの入力構文
<a name="guard-hooks-write-rules-change-set-operations-input"></a>

ガード変更セット入力は、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` モデル構文は次のとおりです。

```
logicalResourceId: String 
resourceType: String
action: CREATE, UPDATE, DELETE
lineNumber: Number
beforeContext: JSON String
afterContext: JSON String
```

`HookContext`  <a name="guard-hook-change-set-hookcontext"></a>  
`AWSAccountID`  <a name="guard-hook-change-set-awsaccountid"></a>
リソース AWS アカウント を含む の ID。  
`StackId`  <a name="guard-hook-change-set-stackid"></a>
スタックオペレーションの一部である CloudFormation スタックのスタック ID。  
`HookTypeName`  <a name="guard-hook-change-set-hooktypename"></a>
実行中のフックの名前。  
`HookTypeVersion`  <a name="guard-hook-change-set-hooktypeversion"></a>
実行中のフックのバージョン。  
`InvocationPoint`  <a name="guard-hook-change-set-invocationpoint"></a>
フックが実行されるプロビジョニングロジックの正確なポイント。  
*有効な値*: (`CREATE_PRE_PROVISION` \$1 `UPDATE_PRE_PROVISION` \$1 `DELETE_PRE_PROVISION`)  
`TargetName`  <a name="guard-hook-change-set-targetname"></a>
評価対象のスタックの名前。  
`TargetType`  <a name="guard-hook-change-set-targettype"></a>
この値は、変更セットレベルのフックとして を実行する`CHANGE_SET`ときに になります。  
`TargetLogicalId`  <a name="guard-hook-change-set-targetlogicalid"></a>
この値は、変更セットの ARN になります。  
`ChangeSetId`  <a name="guard-hook-change-set-changesetid"></a>
フック呼び出しを引き起こすために実行された変更セット ID。スタックオペレーションが `create-stack`、、または `delete-stack`オペレーションによって開始された場合`update-stack`、この値は空です。

`Proposed CloudFormation Template`  <a name="guard-hook-change-set-current-template"></a>
`create-change-set` オペレーションに提供された完全な CloudFormation テンプレート。CloudFormation に提供された内容に応じて、JSON または YAML 文字列を指定できます。

`Previous`  <a name="guard-hook-change-set-previous-template"></a>
最後に正常にデプロイされた CloudFormation テンプレート。スタックを作成または削除する場合、この値は空です。

`Changes`  <a name="guard-hook-change-set-changes"></a>
`Changes` モデル。これにより、リソースの変更が一覧表示されます。

変更    
logicalResourceId  <a name="guard-hook-change-set-change-logicalresourceid"></a>
変更されたリソースの論理リソース名。  
resourceType  <a name="guard-hook-change-set-change-resourcetype"></a>
変更されるリソースタイプ。  
action  <a name="guard-hook-change-set-change-action"></a>
リソースで実行されるオペレーションのタイプ。  
*有効な値*: (`CREATE` \$1 `UPDATE` \$1 `DELETE`)  
lineNumber  <a name="guard-hook-change-set-change-linenumber"></a>
変更に関連付けられたテンプレートの行番号。  
beforeContext  <a name="guard-hook-change-set-change-beforecontext"></a>
変更前のリソースのプロパティの JSON 文字列:  

```
{"properties": {"property1": "value"}}
```  
afterContext  <a name="guard-hook-change-set-change-aftercontext"></a>
変更後のリソースのプロパティの JSON 文字列:  

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

### ガード変更セットオペレーション入力の例
<a name="guard-hooks-write-rules-change-set-operations-example"></a>

次の入力例は、完全なテンプレート、以前にデプロイされたテンプレート、およびリソース変更のリストを受け取る 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\"}}}"
  }
]
```

### 変更セットオペレーションのガードルール
<a name="guard-hooks-rules-change-set-operations"></a>

次の例は、Amazon S3 バケットへの変更を評価し、 が無効にならないようにする Guard ルール`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'
    }
}
```