cdk-nag の v3 が公開されました！

はじめに

今回は、最近リリースされた cdk-nag の version3 について記載します。今までから移行する上で記載方法なども変更があるようなので、その点も記載していきます。2026/06/12に公開されており、現在の最新版は v3.0.1 となっています。

https://github.com/cdklabs/cdk-nag/tree/main

参考情報

v2→v3のマイグレーション用ガイドをベースに記載していきます。

cdk-nag/MIGRATION.md at main · cdklabs/cdk-nag · GitHub

主な変更点

cdk-nag v3 では内部で評価に利用するエンジンが変更されました。従来はIAspectをベースに synth 時に Annotation を出す独自の方式でした。v3 では CDK ネイティブの policy validation framework (IPolicyValidationPlugin)を利用しています。CDK 標準の検証フレームワークにルールパックが乗る形になったため、登録方法や抑制の書き方が変わっています。

あわせて必要となるaws-cdk-libの最小バージョンも引き上げられました。

移行時はまずaws-cdk-libを 2.257.0 以上へアップグレードすることが前提になります。

NagPackの登録方法の変更

まず NagPack の登録方法が変わりました。従来はAspects.of(app).add(...)で追加していました。

import { App, Aspects } from 'aws-cdk-lib';
import { AwsSolutionsChecks } from 'cdk-nag';

const app = new App();
Aspects.of(app).add(new AwsSolutionsChecks());

これが v3 ではValidations.of(app).addPlugins(...)に変わります。

import { App, Validations } from 'aws-cdk-lib';
import { AwsSolutionsChecks } from 'cdk-nag';

const app = new App();
Validations.of(app).addPlugins(new AwsSolutionsChecks(app));

Aspects.of(scope).add(...)の代わりにValidations.of(scope).addPlugins(...)を使うように変わっています。あわせてAwsSolutionsChecksのコンストラクタが第1引数に scope を取るようになったため、new AwsSolutionsChecks(app)のように app を渡します。

抑制（NagSuppressions）から承認（Acknowledge）への変更

ルールの抑制方法も変わりました。従来はNagSuppressionsクラスで抑制を追加していました。ここでリソース単位やスタック単位での抑制を行えます。

import { NagSuppressions } from 'cdk-nag';

NagSuppressions.addResourceSuppressions(myBucket, [
  { id: 'AwsSolutions-S1', reason: 'Logging not required.' },
]);

NagSuppressions.addStackSuppressions(stack, [
  { id: 'AwsSolutions-S1', reason: 'Logging not required.' },
]);

v3 ではNagSuppressionsが廃止され、CDK 標準のValidations.of(construct).acknowledge(...)に置き換わります。

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

Validations.of(myBucket).acknowledge({
  id: 'AwsSolutions-S1',
  reason: 'Logging not required.',
});

// スタックレベルでの承認
Validations.of(stack).acknowledge({
  id: 'AwsSolutions-S1',
  reason: 'Logging not required for any resource in this stack.',
});

1回のacknowledgeで承認できるのは1ルールのみです。v2 のように配列でまとめて渡す形式は廃止されました。今までスタックに対してまとめてルールを指定する記載をしてた場合は若干冗長な記載にはなりそうです。粒度の細かい抑制は従来通りRuleId[FindingId]形式が使えます。例えば以下のように指定します。

Validations.of(resource).acknowledge({ id: 'AwsSolutions-IAM5[Action::s3:*]', reason: '...' })

その他の変更点

上記以外にも削除された API があります。v3 で削除された API は以下の通りです。想像も入りますが、SuppressionIgnoreAlwaysやSuppressionIgnoreNeverなど一括で上書きするルールがacknowledge側にはないため、代替はないようです。

NagPackPropsも整理されました。verboseは維持されますが、logIgnores、reports、reportFormats、suppressionIgnoreCondition、additionalLoggersは削除されています。代わりにwriteSuppressionsToCloudFormationが追加されました。これは v2 のツールが参照するcdk_nagメタデータを後方互換のために CloudFormation テンプレートへ書き出すためのオプションです。

複数のプロパティが削除されたことで、記載はかなりシンプルになりそうです。ただ、今までこのプロパティを使ってレポート出力やセキュリティポリシー適用状況の管理などを行なっていた場合は注意が必要です。現在は代替手段があるので、上記を使いつつ、徐々に別の仕組みへ移行が必要そうです。

検証結果の出力先も変わりました。v2 では synth 時の Annotation と CSV/JSON レポートでしたが、v3 では cloud assembly のpolicy-validation-report.jsonに出力されます。cdk synthやcdk deployの実行時には違反のサマリが表示されます。

カスタム NagPack を自作している場合も対応が必要です。visit()をprotected checkResource(node: CfnResource)に置き換え、public readonly nameを追加し、コンストラクタを(scope?, props?)のシグネチャへ変更します。詳細は MIGRATION.md を参照してください。

所感

内部で評価に利用するエンジンが CDK 標準の policy validation framework に統合されたことで、cdk-nag が CDK 本体の仕組みに乗る形になったのは保守性の観点では良い変更だと感じます。ただ、既存で出力できていた内容が無くなっていたり、NagSuppressionsの書き換えが必要です。cdk-nagで独自の管理をしっかり入れている場合は、既存プロジェクトの移行にはそれなりの手間がかかりそうです。

移行の際はまずaws-cdk-libのバージョン引き上げてから、対応方法を確認してみてください。このブログが多少でも参考になれば幸いです。