@mavogel/awscdk-rootmail 0.0.336 → 0.1.0

package/node_modules/cdk-nag/MIGRATION.md

@@ -0,0 +1,239 @@
+# Migrating from cdk-nag v2 to v3
+
+## Overview
+
+cdk-nag v3 rewrites the core engine from an `IAspect` to an `IPolicyValidationPlugin`. Rule packs now participate in CDK's native [policy validation framework](https://docs.aws.amazon.com/cdk/v2/guide/policy-validation-synthesis.html) instead of emitting annotations during synthesis.
+
+This guide covers every breaking change and the corresponding v3 equivalent.
+
+---
+
+## Minimum CDK Version
+
+| Version | Minimum `aws-cdk-lib` |
+|---------|----------------------|
+| v2      | 2.176.0              |
+| v3      | 2.257.0              |
+
+---
+
+## Registering a NagPack
+
+### v2
+
+```typescript
+import { App, Aspects } from 'aws-cdk-lib';
+import { AwsSolutionsChecks } from 'cdk-nag';
+
+const app = new App();
+Aspects.of(app).add(new AwsSolutionsChecks());
+```
+
+### v3
+
+```typescript
+import { App, Validations } from 'aws-cdk-lib';
+import { AwsSolutionsChecks } from 'cdk-nag';
+
+const app = new App();
+Validations.of(app).addPlugins(new AwsSolutionsChecks(app));
+```
+
+**Key differences:**
+
+- Use `Validations.of(scope).addPlugins(...)` instead of `Aspects.of(scope).add(...)`.
+- The NagPack constructor now takes an optional `scope` as the first argument, followed by `props`.
+
+---
+
+## Acknowledging (Suppressing) Rules
+
+### v2
+
+```typescript
+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
+
+```typescript
+import { Validations } from 'aws-cdk-lib';
+
+Validations.of(myBucket).acknowledge({
+  id: 'AwsSolutions-S1',
+  reason: 'Logging not required.',
+});
+
+// Stack-level acknowledgment
+Validations.of(stack).acknowledge({
+  id: 'AwsSolutions-S1',
+  reason: 'Logging not required for any resource in this stack.',
+});
+```
+
+**Key differences:**
+
+- `NagSuppressions` is removed. Use CDK's built-in `Validations.of(construct).acknowledge(...)`.
+- Each call acknowledges a single rule. There is no bulk array form.
+- Granular finding suppressions still use the `RuleId[FindingId]` format: `Validations.of(resource).acknowledge({ id: 'AwsSolutions-IAM5[Action::s3:*]', reason: '...' })`.
+
+---
+
+## Removed APIs
+
+The following exports no longer exist in v3:
+
+| Removed                        | Replacement                                         |
+|-------------------------------|-----------------------------------------------------|
+| `NagSuppressions`             | `Validations.of(construct).acknowledge(...)`        |
+| `NagPackSuppression`          | Use `{ id, reason }` with `acknowledge()`           |
+| `INagSuppressionIgnore`       | No equivalent (acknowledgments cannot be overridden)|
+| `SuppressionIgnoreAlways`     | Removed                                             |
+| `SuppressionIgnoreNever`      | Removed                                             |
+| `SuppressionIgnoreOr`         | Removed                                             |
+| `INagLogger`                  | Removed — violations surface in `policy-validation-report.json` |
+| `AnnotationLogger`            | Removed                                             |
+| `NagReportLogger`             | Removed                                             |
+| `VALIDATION_FAILURE_ID`       | Rule errors are reported as violations directly     |
+| `NagRulePostValidationStates.SUPPRESSED` | Removed                              |
+
+---
+
+## NagPackProps Changes
+
+| v2 Property                    | v3 Status                                          |
+|-------------------------------|-----------------------------------------------------|
+| `verbose`                     | Retained — controls whether explanations are included in violation descriptions |
+| `logIgnores`                  | Removed — no separate suppression logging          |
+| `reports`                     | Removed — CDK writes `policy-validation-report.json` automatically |
+| `reportFormats`               | Removed                                            |
+| `suppressionIgnoreCondition`  | Removed                                            |
+| `additionalLoggers`           | Removed                                            |
+| `writeSuppressionsToCloudFormation` | **New** — writes acknowledged rules into CloudFormation Metadata for audit trail compatibility with v2 tooling |
+
+---
+
+## Custom NagPack Authors
+
+### v2
+
+```typescript
+import { CfnResource, IAspect } from 'aws-cdk-lib';
+import { IConstruct } from 'constructs';
+import { NagPack, NagPackProps, NagMessageLevel, NagRuleCompliance } from 'cdk-nag';
+
+export class MyPack extends NagPack {
+  constructor(props?: NagPackProps) {
+    super(props);
+    this.packName = 'MyPack';
+  }
+
+  public visit(node: IConstruct): void {
+    if (node instanceof CfnResource) {
+      this.applyRule({
+        info: 'My rule description.',
+        explanation: 'Why this matters.',
+        level: NagMessageLevel.ERROR,
+        rule: (resource) =>
+          resource.cfnResourceType === 'AWS::S3::Bucket'
+            ? NagRuleCompliance.COMPLIANT
+            : NagRuleCompliance.NON_COMPLIANT,
+        node,
+      });
+    }
+  }
+}
+```
+
+### v3
+
+```typescript
+import { CfnResource } from 'aws-cdk-lib';
+import { IConstruct } from 'constructs';
+import { NagPack, NagPackProps, NagMessageLevel, NagRuleCompliance } from 'cdk-nag';
+
+export class MyPack extends NagPack {
+  public readonly name = 'MyPack';
+
+  constructor(scope?: IConstruct, props?: NagPackProps) {
+    super(scope, props);
+    this.packName = 'MyPack';
+  }
+
+  protected checkResource(node: CfnResource): void {
+    this.applyRule({
+      info: 'My rule description.',
+      explanation: 'Why this matters.',
+      level: NagMessageLevel.ERROR,
+      rule: (resource) =>
+        resource.cfnResourceType === 'AWS::S3::Bucket'
+          ? NagRuleCompliance.COMPLIANT
+          : NagRuleCompliance.NON_COMPLIANT,
+      node,
+    });
+  }
+}
+```
+
+**Key differences:**
+
+- Add a `public readonly name` property (required by `IPolicyValidationPlugin`).
+- Constructor signature is `(scope?: IConstruct, props?: NagPackProps)`.
+- Replace `public visit(node: IConstruct)` with `protected checkResource(node: CfnResource)`. The base class handles tree-walking and only calls `checkResource` for `CfnResource` nodes.
+- The `ignoreSuppressionCondition` option on `IApplyRule` is removed.
+
+---
+
+## Validation Output
+
+### v2
+
+Violations appeared as CDK Annotations (warnings/errors) during `cdk synth` and in CSV/JSON report files in the cloud assembly output directory.
+
+### v3
+
+Violations appear in CDK's `policy-validation-report.json` in the cloud assembly. The CDK CLI displays a formatted summary of all violations on `cdk synth` or `cdk deploy`. Reports (`NagReportLogger`) are no longer generated separately.
+
+---
+
+## Audit Trail (CloudFormation Metadata)
+
+If you have existing tooling that reads the `cdk_nag` metadata block from synthesized CloudFormation templates, enable backwards-compatible metadata writing:
+
+```typescript
+Validations.of(app).addPlugins(
+  new AwsSolutionsChecks(app, { writeSuppressionsToCloudFormation: true })
+);
+```
+
+This causes acknowledged rules to be written into each `CfnResource`'s Metadata as:
+
+```json
+{
+  "cdk_nag": {
+    "rules_to_suppress": [
+      { "id": "AwsSolutions-S1", "reason": "..." }
+    ]
+  }
+}
+```
+
+---
+
+## Quick Migration Checklist
+
+- [ ] Update `aws-cdk-lib` to >= 2.257.0
+- [ ] Replace `Aspects.of(scope).add(new Pack())` → `Validations.of(scope).addPlugins(new Pack(scope))`
+- [ ] Replace all `NagSuppressions.addResourceSuppressions(...)` / `addStackSuppressions(...)` → `Validations.of(construct).acknowledge({ id, reason })`
+- [ ] Remove imports of `NagSuppressions`, `NagPackSuppression`, `INagLogger`, `AnnotationLogger`, `NagReportLogger`, `INagSuppressionIgnore`, and related types
+- [ ] If using custom NagPacks: rename `visit()` → `checkResource()`, add `public readonly name`, update constructor signature
+- [ ] If relying on CSV/JSON reports: switch to reading `policy-validation-report.json` from the cloud assembly, or enable `writeSuppressionsToCloudFormation` for template-level metadata
+- [ ] Remove `logIgnores`, `reports`, `reportFormats`, `suppressionIgnoreCondition`, and `additionalLoggers` from NagPack props