合成時の検証検証とはアプリケーションデベロッパー向けコンストラクト作成者の場合: 警告とエラーを直接追加するプラグイン作成者向け

AWS 合成時の CDK 検証

合成時の検証

AWS CDK アプリケーションは、合成時に CloudFormation テンプレートの形式でインフラストラクチャの説明を生成します。これらのテンプレートは、合成直後に検証されます。 AWS CDK には一連の検証ルールが組み込まれており、CDK Nag などの他の CDK 固有の検証ツールや、AWS CloudFormation Guard や OPA など、組織が既に使用しているポリシー検証ツールで拡張できます。違反がある場合、合成は失敗してレポートがコンソールに出力されます。合成されたテンプレートのオフライン検証を使用すると、インフラストラクチャの潜在的な問題を早期に検出して修正できます。検証を使用して、デプロイの失敗、一般的な設定ミス、または会社の標準への準拠の失敗につながる問題を見つけます。

注記

以前のBeta1インターフェイス (IPolicyValidationPluginBeta1、、の PolicyValidationPluginReportBeta1policyValidationBeta1プロパティなどStage) は、安定したサフィックスなしの同等のもの (、など) IPolicyValidationPluginに段階的に拡張されていますPolicyValidationPluginReport。Beta1 インターフェイスは廃止されましたが、引き続き機能します。検証プラグインを登録する推奨方法は、 policyValidationBeta1プロパティではなく Validations クラスを使用することです。

検証とは

合成時に AWS CDK によって実行される検証は、デベロッパーエクスペリエンスを向上させるためのベストエフォート検証であり、それ自体が完全な標準コンプライアンスメカニズムではありません。CDK アプリによって正常に生成されたテンプレートを検証しますが、合成以外で発生するアクションには影響しません。たとえば、コンソールで直接実行されたアクションや、サービス APIsアクションなどです。さらに、CDK アプリケーションは汎用プログラミング言語で記述されるため、デベロッパーは必要に応じて検証メカニズムをバイパスできます。そのため、CDK 検証は早期検証のためのシフト左メカニズムであり、AWS CloudFormation フックや AWS Config などの必要なルールセットを検証するための別のメカニズムと組み合わせて使用する必要があります。

アプリケーションデベロッパー向け

検証プラグインの追加

検証は検証プラグインによって実行されます。AWS リソースの包括的なルールセットを使用するデフォルトのプラグインは、@aws/cloudformation-validate に基づいて自動的にアプリケーションに追加されます。アプリケーションにプラグインを追加する場合は、 Validations クラスを使用します。


import { Validations } from 'aws-cdk-lib';
import { CfnGuardValidator } from '@cdklabs/cdk-validator-cfnguard';

const app = new App();

// Add a validation plugin to the entire app
Validations.of(app).addPlugins(new CfnGuardValidator());

// Or add to a particular stage
const prodStage = new Stage(app, 'ProdStage');
Validations.of(prodStage).addPlugins(new CfnGuardValidator());

合成の直後、この方法で登録されたすべてのプラグインが呼び出され、定義したスコープで生成されたすべてのテンプレートが検証されます。特に、App オブジェクトにテンプレートを登録した場合、すべてのテンプレートが検証の対象となります。

警告

プラグインは、実行中にマシンにフルアクセスできます。信頼できるソースからのプラグインであることを確認するのは、プラグインのコンシューマーであるお客様の責任です。

検証レポート

AWS CDK アプリを合成すると、検証プラグインが呼び出され、結果が出力されます。レポートの例が以下に示されています。


lib/my-custom-l3-construct.ts:10:5
ERROR [CT.S3.PR.1]: Require an Amazon S3 bucket to have block public access settings configured (cdk-validator-cfnguard)
   MyStack/MyCustomL3Construct/Bucket/Resource (MyCustomL3ConstructBucket8C61BCA7) constructs.Construct
   Suggested fix: [FIX]: The parameters 'BlockPublicAcls', 'BlockPublicPolicy', 'IgnorePublicAcls', 'RestrictPublicBuckets' must be set to true under the bucket-level 'PublicAccessBlockConfiguration'.
   Acknowledge with 'cdk-validator-cfnguard::s3_bucket_level_public_access_prohibited_check'

lib/my-custom-l3-construct.ts:10:5
ERROR [CT.S3.PR.10]: Require an Amazon S3 bucket to have server-side encryption configured using an AWS KMS key (cdk-validator-cfnguard)
   MyStack/MyCustomL3Construct/Bucket/Resource (MyCustomL3ConstructBucket8C61BCA7) constructs.Construct
   Suggested fix: [FIX]: Set an encryption rule in 'BucketEncryption.ServerSideEncryptionConfiguration' with a 'ServerSideEncryptionByDefault.SSEAlgorithm' configuration of 'aws:kms' or 'aws:kms:dsse'
   Acknowledge with 'cdk-validator-cfnguard::s3_bucket_default_encryption_kms_check'

...

デフォルトでは、レポートは人間が読み取れる形式で出力されます。JSON 形式のレポートが必要な場合、CLI を介して @aws-cdk/core:validationReportJson を使用して有効にするか、アプリケーションに直接渡します。


const app = new App({
  context: { '@aws-cdk/core:validationReportJson': true },
});

または、プロジェクトディレクトリ内の cdk.jsonまたは cdk.context.json ファイルを使用して、このコンテキストキーと値のペアを設定できます (コンテキスト値と AWS CDK を参照）。

JSON 形式を選択すると、 AWS CDK はポリシー検証レポートをクラウドアセンブリディレクトリpolicy-validation-report.jsonのというファイルに出力します。デフォルトの人間が読める形式の場合、レポートは標準出力で出力されます。

警告の確認

警告またはエラーを評価し、適用されないと判断した場合は、 acknowledgeメソッドを使用して抑制できます。抑制はスコープベースであり、指定されたスコープ内のすべてのコンストラクトに適用されます。


import { Validations } from 'aws-cdk-lib';

Validations.of(myConstruct).acknowledge({
  id: 'PluginName::MyWarningId',
  reason: 'This is acceptable for our use case',
});

は::区切り文字idを使用して、検証ソースプレフィックスをルール名 ( Construct-Annotations::やなどAwsSolutions-S1::) から区切ります。

AWS CloudFormation Guard プラグイン

CfnGuardValidator プラグインを使用すると、「AWS CloudFormation Guard」を使用してポリシーの検証を実行できます。CfnGuardValidator プラグインには、厳選された一連の「AWS Control Tower プロアクティブコントロール」が組み込まれています。現在のルールのセットは、「プロジェクトドキュメント」にあります。「合成時のポリシー検証」で説明したように、組織は「AWS CloudFormation フック」を使用してより権威的な検証方法を設定することをお勧めします。

「AWS Control Tower 」の顧客の場合、これらの同じプロアクティブコントロールは組織全体にデプロイできます。 AWS Control Tower 環境で AWS Control Tower プロアクティブコントロールを有効にすると、コントロールは AWS CloudFormation を介してデプロイされた非準拠リソースのデプロイを停止できます。マネージドプロアクティブコントロールとその仕組みの詳細については、「AWS Control Tower キュメント」を参照してください。

これらの AWS CDK バンドルコントロールとマネージド AWS Control Tower プロアクティブコントロールは、一緒に使用するのが最適です。このシナリオでは、 AWS Control Tower クラウド環境でアクティブなものと同じプロアクティブコントロールを使用して、この検証プラグインを設定できます。その後、cdk synthローカルで実行することで、 AWS CDK アプリケーションが AWS Control Tower コントロールを渡すという信頼をすばやく得ることができます。

AWS CDK Nag プラグイン

CDK Nag を使用して、インフラストラクチャを HIPAA、PCI DSS などのさまざまな標準に照らしてチェックできます。cdk-nag のバージョン 3.x は、CDK の標準化された検証メカニズムと統合されています。

コンストラクト作成者の場合: 警告とエラーを直接追加する

Validations クラスには、カスタム警告とエラーをコンストラクトに直接追加する方法も用意されています。このメカニズムを使用して、検証プラグインを実装することなく、コンストラクトで設定ミスを直接レポートできます。この方法で追加した検証とエラーは、検証プラグインによって検出された違反とともに報告されます。


import { Validations } from 'aws-cdk-lib';

const bucket = new s3.Bucket(this, 'MyBucket');

// Add a warning
Validations.of(bucket).addWarning('MyWarningId', 'This bucket does not have versioning enabled');

// Add an error (will cause synthesis to fail)
Validations.of(bucket).addError('MyErrorId', 'This bucket must have encryption enabled');

プラグイン作成者向け

AWS CDK コアフレームワークは、プラグインの登録と呼び出し、フォーマットされた検証レポートの表示を担当します。プラグインの責任は、 AWS CDK フレームワークと、プラグインがシェルアウトするなどの外部ポリシー検証ツールとの間の変換レイヤーとして機能することです。プラグインは、 AWS CDK でサポートされている任意の言語で作成できます。複数の言語で消費される可能性のあるプラグインを作成する場合は、JSII を使用して各 AWS CDK 言語にプラグインを発行TypeScriptできるように、プラグインを作成することをお勧めします。

プラグインの作成

AWS CDK コアモジュールとポリシーツール間の通信プロトコルは、 IPolicyValidationPluginインターフェイスによって定義されます。新しいプラグインを作成するには、このインターフェイスを実装するクラスを記述する必要があります。実装する必要があるものは 2 つあり、プラグイン名 (name プロパティを上書きすることで実装) および validate() メソッドです。

フレームワークは validate() を呼び出し、IPolicyValidationContext オブジェクトを渡します。検証するテンプレートの場所は templatePaths によって指定されます。プラグインは PolicyValidationPluginReport のインスタンスを返します。このオブジェクトは、合成の最後にユーザーが受け取るレポートを表します。


validate(context: IPolicyValidationContext): PolicyValidationPluginReport {
  // First read the templates using context.templatePaths...
  // ...then perform the validation, and then compose and return the report.
  // Using hard-coded values here for better clarity:
  return {
    success: false,
    violations: [{
      ruleName: 'CKV_AWS_117',
      description: 'Ensure that AWS Lambda function is configured inside a VPC',
      fix: 'https://docs.bridgecrew.io/docs/ensure-that-aws-lambda-function-is-configured-inside-a-vpc-1',
      violatingResources: [{
        resourceName: 'MyFunction3BAA72D1',
        templatePath: '/home/johndoe/myapp/cdk.out/MyService.template.json',
        locations: 'Properties/VpcConfig',
      }],
    }],
  };
}

プラグインは、クラウドアセンブリのものを一切変更できないことに注意してください。変更しようとすると合成が失敗します。

プラグインがシェルアウトする外部ツールに依存している場合は、一部のデベロッパーがワークステーションにまだそのツールをインストールしていない可能性があることに注意してください。わずらわしさを最小限に抑えるには、プラグインパッケージと共にインストールスクリプトを指定して、インストールプロセスを自動化します。

適用除外の処理

組織に適用除外を処理するメカニズムがある場合、検証プラグインの一部として実装できます。

実現可能な適用除外メカニズムを説明するシナリオの例

特定のシナリオを除き、ある組織にはパブリック Amazon S3 バケットが許可されないというルールがあります。
デベロッパーはこれらのシナリオのいずれかに該当する Amazon S3 バケットを作成し、適用除外を要求します (チケットの作成など)。
セキュリティのツールは、適用除外を登録する内部システムから読み取る方法を知っています

このシナリオでは、デベロッパーは内部システムで例外を要求し、その例外を「登録」する方法が必要になります。ガードプラグインの例に追加すると、内部チケットシステムに一致する適用除外がある違反をフィルタリングすることにより、適用除外を処理するプラグインを作成できます。

実装例については、既存のプラグインを参照してください。

@cdklabs/cdk-validator-cfnguard

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

AWS CDK アプリケーションのデプロイ

CDK Pipelines の作成