AWS CloudFormation Guard ルールの記述 - AWS CloudFormation Guard
句句でのクエリの使用句での演算子の使用句でのカスタムメッセージの使用句の組み合わせガードルールでのブロックの使用組み込み関数の使用

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

AWS CloudFormation Guard ルールの記述

では AWS CloudFormation Guard、ルールは policy-as-code ルールです。JSON 形式または YAML 形式のデータを検証できる Guard ドメイン固有の言語 (DSL) でルールを記述します。ルールは 句で構成されます。

Guard DSL を使用して記述されたルールは、任意のファイル拡張子を使用するプレーンテキストファイルに保存できます。

複数のルールファイルを作成し、ルールセットとして分類できます。ルールセットを使用すると、JSON 形式または YAML 形式のデータを複数のルールファイルに対して同時に検証できます。

トピック

句

句は、true (PASS) または false () のいずれかに評価されるブール式ですFAIL。句は、バイナリ演算子を使用して 2 つの値を比較するか、単一の値で動作する単一演算子を使用します。

単項句の例

次の unary 句は、コレクションTcpBlockedPortsが空であるかどうかを評価します。

InputParameters.TcpBlockedPorts not empty

次の unary 句は、 ExecutionRoleArnプロパティが文字列であるかどうかを評価します。

Properties.ExecutionRoleArn is_string

バイナリ句の例

次のバイナリ句は、大文字と小文字に関係なくencrypted、 BucketNameプロパティに文字列 が含まれているかどうかを評価します。

Properties.BucketName != /(?i)encrypted/

次のバイナリ句は、ReadCapacityUnitsプロパティが 5,000 以下であるかどうかを評価します。

Properties.ProvisionedThroughput.ReadCapacityUnits <= 5000

ガードルール句を記述するための構文

<query> <operator> [query|value literal] [custom message]

ガードルール句のプロパティ

query

階層データをトラバースするために書き込まれたドット (.) 区切り式。クエリ式には、値のサブセットをターゲットとするフィルター式を含めることができます。クエリを変数に割り当てると、変数を一度書き込んでルールセットの他の場所で参照できるため、クエリ結果にアクセスできます。

クエリの記述とフィルタリングの詳細については、「」を参照してくださいクエリとフィルタリングの定義。

必須: はい

operator

クエリの状態を確認するのに役立つ単項演算子またはバイナリ演算子。バイナリ演算子の左側 (LHS) はクエリで、右側 (RHS) はクエリまたは値リテラルである必要があります。

サポートされているバイナリ演算子: == (Equal) | != (Not equal) | > (Greater than) | >= (Greater than or equal to) | < (Less than) | <= (Less than than) | IN (In a list of form [x, y, z]

サポートされている単項演算子: exists | empty | is_string | is_list | is_struct | not(!)

必須: はい

query|value literal

クエリ、または stringや などのサポートされている値リテラルinteger(64)。

サポートされている値リテラル：

  • すべてのプリミティブタイプ: string、integer(64)、float(64)、bool、char、 regex

  • integer(64)、、float(64)または 範囲を次のように表現するためのすべての特殊なchar範囲タイプ：

    • r[<lower_limit>, <upper_limit>]。これは、次の式kを満たす任意の値に変換されます。 lower_limit <= k <= upper_limit

    • r[<lower_limit>, <upper_limit>）。これは、次の式kを満たす任意の値に変換されます。 lower_limit <= k < upper_limit

    • r(<lower_limit>, <upper_limit>]。これは、次の式kを満たす任意の値に変換されます。 lower_limit < k <= upper_limit

    • r(<lower_limit>, <upper_limit>), これは、次の式kを満たす任意の値に変換されます。 lower_limit < k < upper_limit

  • ネストされたキーと値の構造データの関連付け配列 (マップ）。例:

    { "my-map": { "nested-maps": [ { "key": 10, "value": 20 } ] } }

  • プリミティブ型または関連付け配列型の配列

必須: 条件付き。バイナリ演算子を使用する場合に必要です。

custom message

句に関する情報を提供する文字列。メッセージは validateおよび test コマンドの詳細出力に表示され、階層データのルール評価の理解やデバッグに役立ちます。

必須: いいえ

句でのクエリの使用

クエリの記述の詳細については、クエリとフィルタリングの定義「」および「」を参照してくださいガードルールでの変数の割り当てと参照。

句での演算子の使用

CloudFormation テンプレートの例を次に示しますTemplate-1Template-2。サポートされている演算子の使用方法を示すために、このセクションのクエリと句の例は、これらのサンプルテンプレートを参照しています。

Template-1

Resources:
 S3Bucket:
   Type: AWS::S3::Bucket
   Properties:
     BucketName: MyServiceS3Bucket
     BucketEncryption:
       ServerSideEncryptionConfiguration:
         - ServerSideEncryptionByDefault:
             SSEAlgorithm: 'aws:kms'
             KMSMasterKeyID: 'arn:aws:kms:us-east-1:123456789:key/056ea50b-1013-3907-8617-c93e474e400'
     Tags:
       - Key: stage
         Value: prod
       - Key: service
         Value: myService

Template-2

Resources:
 NewVolume:
   Type: AWS::EC2::Volume
   Properties: 
     Size: 100
     VolumeType: io1
     Iops: 100
     AvailabilityZone:
       Fn::Select:
         - 0
         - Fn::GetAZs: us-east-1
     Tags:
       - Key: environment
         Value: test
   DeletionPolicy: Snapshot

単項演算子を使用する句の例

  • empty – コレクションが空かどうかを確認します。これを使用して、クエリがコレクションになるため、クエリに階層データの値があるかどうかを確認することもできます。文字列値クエリに空の文字列 ("") が定義されているかどうかを確認するために使用することはできません。詳細については、「クエリとフィルタリングの定義」を参照してください。

    次の句は、テンプレートに 1 つ以上のリソースが定義されているかどうかを確認します。論理 ID を持つリソースS3Bucketが で定義されているPASSため、 に評価されますTemplate-1。

    Resources !empty

    次の句は、S3Bucketリソースに 1 つ以上のタグが定義されているかどうかを確認します。S3Bucket には の Tagsプロパティに 2 つのタグが定義されているPASSため、 に評価されますTemplate-1。

    Resources.S3Bucket.Properties.Tags !empty

  • exists – クエリの各出現に値があり、 の代わりに使用できるかどうかを確認します!= null。

    次の句は、 BucketEncryptionプロパティが に定義されているかどうかを確認しますS3Bucket。は S3Bucketで に定義されているPASSため、 に評価BucketEncryptionされますTemplate-1。

    Resources.S3Bucket.Properties.BucketEncryption exists
注記

empty と not existsは、入力データをトラバースするときに、欠落しているプロパティキーtrueがないかを に評価します。たとえば、 のテンプレートで Propertiesセクションが定義されていない場合S3Bucket、 句は にResources.S3Bucket.Properties.Tag empty評価されますtrue。exists および emptyチェックでは、ドキュメント内の JSON ポインタパスはエラーメッセージに表示されません。これらの句の両方に、このトラバーサル情報を保持しない取得エラーがあることがよくあります。

  • is_string – クエリの各出現が stringタイプであるかどうかを確認します。

    次の句は、 S3Bucketリソースの BucketNameプロパティに文字列値が指定されているかどうかをチェックします。文字列値が BucketNameの に指定されているPASSため"MyServiceS3Bucket"、 に評価されますTemplate-1。

    Resources.S3Bucket.Properties.BucketName is_string

  • is_list – クエリの各出現が listタイプであるかどうかを確認します。

    次の句は、S3Bucketリソースの Tagsプロパティにリストが指定されているかどうかを確認します。2 つのキーと値のペアが Tagsで に指定されているPASSため、 に評価されますTemplate-1。

    Resources.S3Bucket.Properties.Tags is_list

  • is_struct – クエリの各出現が構造化データであるかどうかをチェックします。

    次の句は、S3Bucketリソースの BucketEncryptionプロパティに構造化データが指定されているかどうかを確認します。BucketEncryption で ServerSideEncryptionConfigurationプロパティタイプ （オブジェクト） を使用して が指定されPASSるため、 に評価されますTemplate-1。

    Resources.S3Bucket.Properties.BucketEncryption is_struct
注記

逆状態を確認するには、 ( not !) 演算子を is_string、is_list、および is_struct演算子で使用できます。

バイナリ演算子を使用する句の例

次の句は、 のS3Bucketリソースの BucketNameプロパティに指定された値に、大文字と小文字に関係なくencrypt文字列 Template-1が含まれているかどうかを確認します。指定されたバケット名に文字列 が含まれ"MyServiceS3Bucket"ていないPASSため、これは に評価されますencrypt。

Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/

次のTemplate-2句は、 のNewVolumeリソースの Sizeプロパティに指定された値が特定の範囲内にあるかどうかを確認します: 50 <= Size <= 200。が に100指定されているPASSため、 に評価されますSize。

Resources.NewVolume.Properties.Size IN r[50,200]

次のTemplate-2句は、 のNewVolumeリソースの VolumeTypeプロパティに指定された値が io1、io2、または であるかどうかをチェックしますgp3。が にio1指定されているPASSため、 に評価されますNewVolume。

Resources.NewVolume.Properties.NewVolume.VolumeType IN [ 'io1','io2','gp3' ]
注記

このセクションのクエリ例は、論理 IDs S3Bucketと を持つリソースを使用した演算子の使用を示していますNewVolume。多くの場合、リソース名はユーザー定義であり、Infrastructure as Code (IaC) テンプレートで任意の名前を付けることができます。汎用的なルールを記述し、テンプレートで定義されているすべてのAWS::S3::Bucketリソースに適用する場合、使用されるクエリの最も一般的な形式は ですResources.*[ Type == ‘AWS::S3::Bucket’ ]。詳細については、使用状況の詳細についてはクエリとフィルタリングの定義「」を参照し、cloudformation-guardGitHub リポジトリの examples ディレクトリを参照してください。

句でのカスタムメッセージの使用

次の例では、 の 句にカスタムメッセージTemplate-2が含まれています。

Resources.NewVolume.Properties.Size IN r[50,200] 
<<
    EC2Volume size must be between 50 and 200, 
    not including 50 and 200
>>
Resources.NewVolume.Properties.VolumeType IN [ 'io1','io2','gp3' ] <<Allowed Volume Types are io1, io2, and gp3>>

句の組み合わせ

Guard では、新しい行に書き込まれた各句は、結合 (ブールandロジック) を使用して次の句と暗黙的に結合されます。次の例を参照してください。

# clause_A ^ clause_B ^ clause_C
clause_A
clause_B
clause_C

差分を使用して、最初の句のor|OR最後に を指定することで、句を次の句と組み合わせることもできます。

<query> <operator> [query|value literal] [custom message] [or|OR]

Guard 句では、差分が最初に評価され、次に結合が評価されます。ガードルールは、 (or|OR) または true () のいずれかに評価される句 ( and|AND の PASS) の分散の組み合わせとして定義できますfalseFAIL。これは、補助法線形式に似ています。

次の例は、 句の評価の順序を示しています。

# (clause_E v clause_F) ^ clause_G
clause_E OR clause_F
clause_G

# (clause_H v clause_I) ^ (clause_J v clause_K)
clause_H OR
clause_I
clause_J OR
clause_K

# (clause_L v clause_M v clause_N) ^ clause_O
clause_L OR
clause_M OR
clause_N 
clause_O

この例に基づくすべての句は、結合を使用して結合Template-1できます。次の例を参照してください。

Resources.S3Bucket.Properties.BucketName is_string
Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/
Resources.S3Bucket.Properties.BucketEncryption exists
Resources.S3Bucket.Properties.BucketEncryption is_struct
Resources.S3Bucket.Properties.Tags is_list
Resources.S3Bucket.Properties.Tags !empty

ガードルールでのブロックの使用

ブロックは、関連する句、条件、またはルールのセットから冗長性と繰り返しを削除する構成です。ブロックには 3 つのタイプがあります。

  • クエリブロック

  • when ブロック

  • 名前付きルールブロック

クエリブロック

以下は、例 に基づく句ですTemplate-1。句を組み合わせるために結合が使用されました。

Resources.S3Bucket.Properties.BucketName is_string
Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/
Resources.S3Bucket.Properties.BucketEncryption exists
Resources.S3Bucket.Properties.BucketEncryption is_struct
Resources.S3Bucket.Properties.Tags is_list
Resources.S3Bucket.Properties.Tags !empty

各句のクエリ式の一部が繰り返されます。クエリブロックを使用して、同じ初期クエリパスを持つ一連の関連句から、コンポジビリティを向上させ、冗長性と繰り返しを削除できます。次の例に示すように、同じ句のセットを記述できます。

Resources.S3Bucket.Properties {
    BucketName is_string
    BucketName != /(?i)encrypt/
    BucketEncryption exists
    BucketEncryption is_struct
    Tags is_list
    Tags !empty
}

クエリブロックでは、ブロックの前のクエリがブロック内の句のコンテキストを設定します。

ブロックの使用の詳細については、「」を参照してください名前付きルールブロックの作成。

when ブロック

ブロックは、次の形式のwhenブロックを使用して条件付きで評価できます。

  when <condition> {
       Guard_rule_1
       Guard_rule_2
       ...
   }

when キーワードはwhenブロックの開始を指定します。 conditionはガードルールです。ブロックは、条件の評価が true () になった場合にのみ評価されますPASS。

以下は、 に基づくwhenブロックの例ですTemplate-1。

when Resources.S3Bucket.Properties.BucketName is_string {
     Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/
 }

when ブロック内の 句は、 に指定された値が文字列である場合にのみ評価BucketNameされます。次の例に示すように、 に指定された値がテンプレートの Parametersセクションで参照BucketNameされている場合、 whenブロック内の 句は評価されません。

Parameters:
   S3BucketName:
     Type: String
 Resources:
   S3Bucket:
     Type: AWS::S3::Bucket
     Properties:
       BucketName: 
         Ref: S3BucketName
     ...

名前付きルールブロック

ルールのセット (ルールセット) に名前を割り当て、他のルールで名前付きルールブロックと呼ばれるモジュラー検証ブロックを参照できます。名前付きルールブロックの形式は次のとおりです。

  rule <rule name> [when <condition>] {
    Guard_rule_1
    Guard_rule_2
    ...
    }

rule キーワードは、named-rule ブロックの開始を指定します。

rule name は、名前付きルールブロックを一意に識別する人間が読める文字列です。これは、カプセル化する Guard ルールセットのラベルです。この使用では、Guard ルールという用語に句、クエリブロック、whenブロック、名前付きルールブロックが含まれます。ルール名は、カプセル化するルールセットの評価結果を参照するために使用できます。これにより、名前付きルールブロックを再利用できます。ルール名は、 validateおよび test コマンド出力のルールの失敗に関するコンテキストも提供します。ルール名は、ルールファイルの評価出力にブロックの評価ステータス (PASS、FAIL、または SKIP) とともに表示されます。次の例を参照してください。

# Sample output of an evaluation where check1, check2, and check3 are rule names.
template.json Status = **FAIL**
**SKIP rules**
check1 **SKIP**
**PASS rules**
check2 **PASS**
**FAILED rules**
check3 **FAIL**

when キーワードを指定し、その後にルール名の後に条件を指定することで、名前付きルールブロックを条件付きで評価することもできます。

このトピックで前述したwhenブロックの例を次に示します。

rule checkBucketNameStringValue when Resources.S3Bucket.Properties.BucketName is_string {
    Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/
}

名前付きルールブロックを使用すると、前述の内容を次のように記述することもできます。

rule checkBucketNameIsString {
    Resources.S3Bucket.Properties.BucketName is_string
}
rule checkBucketNameStringValue when checkBucketNameIsString {
    Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/
}

名前付きルールブロックを再利用して、他の Guard ルールでグループ化できます。以下にいくつかの例を示します。

rule rule_name_A {
    Guard_rule_1 OR
    Guard_rule_2
    ...
}

rule rule_name_B {
    Guard_rule_3
    Guard_rule_4
    ...
}

rule rule_name_C {
    rule_name_A OR rule_name_B
}

rule rule_name_D {
    rule_name_A
    rule_name_B
}

rule rule_name_E when rule_name_D {
    Guard_rule_5
    Guard_rule_6
    ...
}

組み込み関数の使用

AWS CloudFormation Guard には、文字列操作、JSON 解析、データ型変換などのオペレーションを実行するためにルールで使用できる組み込み関数が用意されています。関数は、変数への割り当てによってのみサポートされます。

キー関数

json_parse(json_string)

テンプレートからインライン JSON 文字列を解析します。解析後、結果のオブジェクトのプロパティを評価できます。

count(collection)

クエリが解決される項目の数を返します。

regex_replace(base_string, regex_to_extract, regex_replacement)

正規表現を使用して文字列の一部を置き換えます。

文字列操作、コレクションオペレーション、データ型変換関数など、使用可能な関数の完全なリストについては、Guard GitHub リポジトリの Functions ドキュメントを参照してください。