cdk-insights 1.18.0 → 1.19.0

package/README.md

@@ -178,8 +178,8 @@ The aspect runs `cdk-nag`'s `AwsSolutionsChecks` rule pack alongside cdk-insight
 
 cdk-nag's `AwsSolutionsChecks` rule pack flags two patterns that are universally noisy for CDK consumers — they're either AWS-recommended defaults or stale rule heuristics:
 
-- **`AwsSolutions-IAM4`** flags any AWS-managed policy attached to a role, including the standard Lambda execution policies CDK auto-attaches based on event sources (`AWSLambdaBasicExecutionRole`, `AWSLambdaVPCAccessExecutionRole`, `AWSLambdaSQSQueueExecutionRole`, `AWSLambdaDynamoDBExecutionRole`, `AWSLambdaKinesisExecutionRole`). Each is narrowly scoped to a single AWS service — replacing them with customer-managed copies is busywork with no security gain.
-- **`AwsSolutions-L1`** asserts that Lambda runtimes match cdk-nag's known "latest" list, which lags actual AWS LTS releases. Node 20.x / 22.x, Python 3.11–3.13, Java 17/21, .NET 8 are all current AWS LTS at time of writing but get flagged depending on how recent your `aws-cdk-lib` version is.
+- **`AwsSolutions-IAM4`** flags any AWS-managed policy attached to a role, including the standard Lambda execution policies CDK auto-attaches based on event sources or tracing configuration. Each is narrowly scoped to a single AWS service — replacing them with customer-managed copies is busywork with no security gain.
+- **`AwsSolutions-L1`** asserts that Lambda runtimes match cdk-nag's known "latest" list, which lags actual AWS LTS releases. Node 20.x / 22.x, Python 3.11–3.13, Java 17/21, .NET 8, Ruby 3.3/3.4, and `provided.al2023` are all current AWS LTS at time of writing but get flagged depending on how recent your `aws-cdk-lib` version is.
 
 Pass `cdkBoilerplateSuppressions: true` to short-circuit both:
 
@@ -193,13 +193,54 @@ This attaches `NagSuppressions` (with named justifications and `appliesTo` filte
 
 | Rule | What's suppressed | What still fires |
 |---|---|---|
-| `AwsSolutions-IAM4` | The 5 AWS-managed Lambda execution policy ARNs above | Any other managed policy attached to the same role |
-| `AwsSolutions-L1` | Node 18/20/22, Python 3.11/3.12/3.13, Java 17/21, .NET 8 | Anything outside the LTS allowlist (older runtimes, unsupported ones, custom families) |
-
-To extend with project-specific suppressions, call `NagSuppressions.addResourceSuppressions(...)` from `cdk-nag` after constructing your stacks. Project decisions like "MFA is opt-in by product policy" belong in the consumer codebase, with a written justification.
+| `AwsSolutions-IAM4` | 11 AWS-managed Lambda execution policy ARNs: `AWSLambdaBasicExecutionRole`, `AWSLambdaVPCAccessExecutionRole`, `AWSLambdaENIManagementAccess`, `AWSLambdaSQSQueueExecutionRole`, `AWSLambdaDynamoDBExecutionRole`, `AWSLambdaKinesisExecutionRole`, `AWSLambdaMSKExecutionRole`, `AWSLambdaAMQExecutionRole`, `AWSLambdaSelfManagedKafkaExecutionRole`, `AWSLambdaInvocation-DynamoDB`, `AWSXRayDaemonWriteAccess` | Any other managed policy attached to the same role |
+| `AwsSolutions-L1` | `nodejs18.x` / `nodejs20.x` / `nodejs22.x`, `python3.11` / `python3.12` / `python3.13`, `java17` / `java21`, `dotnet8`, `ruby3.3` / `ruby3.4`, `provided.al2023` | Anything outside the LTS allowlist (older runtimes, unsupported ones, custom families) |
 
 Default is `false` — opt-in is conservative and additive.
 
+##### Suppress arbitrary cdk-nag rules
+
+For rules outside the boilerplate set — context-dependent ones like `AwsSolutions-COG2` (MFA), `AwsSolutions-DDB3` (PITR), or any rule the project has reviewed and consciously accepted — pass `suppressNagRules`:
+
+```ts
+Aspects.of(app).add(createCdkInsightsAspect({
+  cdkBoilerplateSuppressions: true,
+  suppressNagRules: [
+    // String shorthand — gets a generic auto-reason. Fine for triage.
+    'AwsSolutions-APIG2',
+    // Object form — written justification. **Recommended for prod code.**
+    {
+      id: 'AwsSolutions-COG2',
+      reason: 'MFA opt-in by product policy; mandatory MFA blocks onboarding for new users. See RFC-0042.',
+    },
+  ],
+}));
+```
+
+Both options compose. The aspect walks up to the construct-tree root on the first visit and applies the suppressions with `applyToChildren: true`, so the rule is honoured for every descendant resource regardless of stack.
+
+For finer-grained control (per-resource, per-`appliesTo`-pattern), use `NagSuppressions.addResourceSuppressions(...)` from `cdk-nag` directly after constructing your stacks. Common patterns we don't auto-suppress because they need consumer context:
+
+```ts
+import { NagSuppressions } from 'cdk-nag';
+
+// DDB grant{Read,Write}Data auto-attaches Resource::<TableArn>/index/*
+// for GSI access. DynamoDB IAM has no index-level scope distinct from
+// the table; the wildcard is unavoidable. Apply per-stack with reason.
+NagSuppressions.addStackSuppressions(myStack, [
+  {
+    id: 'AwsSolutions-IAM5',
+    reason: 'DDB grantRead/Write expands to <TableArn>/index/* for GSI access — DynamoDB IAM has no index-level scope.',
+  },
+]);
+
+// COG2 (mandatory MFA) — product-policy decision, not a defect
+NagSuppressions.addResourceSuppressionsByPath(myStack,
+  '/MyStack/MyUserPool/Resource',
+  [{ id: 'AwsSolutions-COG2', reason: 'MFA opt-in by product policy.' }],
+);
+```
+
 For accurate `file:line` source attribution, CDK needs to record per-construct stack traces during synth. Three ways to enable this, easiest first:
 
 - **`npx cdk-insights setup`** writes `"@aws-cdk/core:stackTrace": true` into your `cdk.json` `context` block — durable across every `cdk synth` invocation, no env-var dance. Recommended.

package/dist/aspects/CdkInsightsAspect.d.ts

@@ -187,6 +187,44 @@ export interface CdkInsightsAspectOptions {
      * constructing your stacks.
      */
     cdkBoilerplateSuppressions?: boolean;
+    /**
+     * Additional cdk-nag rule IDs to suppress globally across the construct
+     * tree. Applied via `NagSuppressions` on the App root with
+     * `applyToChildren: true`, so the suppression is honoured for every
+     * descendant resource regardless of stack.
+     *
+     * Two entry forms:
+     *
+     * - **String shorthand** (`'AwsSolutions-APIG2'`) — gets a generic
+     *   auto-reason. Use for quick experiments / triage.
+     * - **Object form** (`{ id: '...', reason: '...' }`) — carries an
+     *   explicit written justification. **Recommended for checked-in
+     *   code** so suppressions are auditable.
+     *
+     * Composes with `cdkBoilerplateSuppressions`; both can be enabled
+     * simultaneously. For finer-grained control (per-resource, per-
+     * `appliesTo`-pattern), use `NagSuppressions.addResourceSuppressions(...)`
+     * from `cdk-nag` directly after constructing your stacks.
+     *
+     * @example
+     * ```ts
+     * Aspects.of(app).add(createCdkInsightsAspect({
+     *   suppressNagRules: [
+     *     // String shorthand — generic auto-reason, fine for triage
+     *     'AwsSolutions-APIG2',
+     *     // Object form — written justification, recommended for prod code
+     *     {
+     *       id: 'AwsSolutions-COG2',
+     *       reason: 'MFA is opt-in by product policy; see RFC-0042.',
+     *     },
+     *   ],
+     * }));
+     * ```
+     */
+    suppressNagRules?: Array<string | {
+        id: string;
+        reason: string;
+    }>;
 }
 /**
  * Helper function to check if CDK stack traces are enabled.
@@ -298,6 +336,7 @@ export declare class ExtremelyHelpfulConsoleLogger implements INagLogger {
 export declare class CdkInsightsAspect extends NagPack implements IAspect {
     private readonly delegate;
     private readonly options;
+    private readonly userSuppressionsApplied;
     constructor(props?: NagPackProps & CdkInsightsAspectOptions);
     visit(node: IConstruct): void;
 }