cdk-insights 1.17.0 → 1.19.0

package/README.md

@@ -172,6 +172,75 @@ Aspects.of(app).add(createCdkInsightsAspect());
 app.synth();
 ```
 
+The aspect runs `cdk-nag`'s `AwsSolutionsChecks` rule pack alongside cdk-insights' own rules. As of 1.17.0, those findings are emitted as **non-blocking Info annotations** (`cdk-insights::nagFinding::*`) instead of cdk-nag's default Error/Warning annotations — the Validations Plugin (below) remains the actual deploy gate, configured per severity.
+
+##### Auto-suppress CDK / AWS boilerplate
+
+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 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:
+
+```ts
+Aspects.of(app).add(createCdkInsightsAspect({
+  cdkBoilerplateSuppressions: true,
+}));
+```
+
+This attaches `NagSuppressions` (with named justifications and `appliesTo` filters) before cdk-nag evaluates each construct, so the matching findings are never emitted. Anything outside the boilerplate set continues to surface — if a role has `AWSLambdaBasicExecutionRole` *and* a custom managed policy, only the boilerplate one is suppressed; the custom policy still produces a finding.
+
+| Rule | What's suppressed | What still fires |
+|---|---|---|
+| `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

@@ -154,6 +154,77 @@ export interface CdkInsightsAspectOptions {
      * around the construct definition for quick reference.
      */
     includeCodeSnippets?: boolean;
+    /**
+     * Auto-suppress cdk-nag findings for well-known CDK / AWS boilerplate
+     * patterns (default: false). When `true`, the aspect attaches
+     * `NagSuppressions` to matching constructs **before** cdk-nag evaluates
+     * its rules, so the suppressed findings disappear from scan output
+     * entirely. Each suppression carries a named justification.
+     *
+     * Currently covers two universally-noisy rules:
+     *
+     *   - **`AwsSolutions-IAM4`** for the AWS-managed 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. The suppression uses `appliesTo`
+     *     so any *other* managed policy attached to the same role still
+     *     surfaces a finding.
+     *
+     *   - **`AwsSolutions-L1`** for current AWS Lambda LTS runtimes
+     *     (Node 18/20/22, Python 3.11/3.12/3.13, Java 17/21, .NET 8).
+     *     cdk-nag's "latest runtime" check is heuristic and lags new LTS
+     *     releases; this allowlist updates with cdk-insights releases.
+     *
+     * Anything not in the lists above continues to surface normally — opt-in
+     * is conservative and additive.
+     *
+     * Recommended for any project that uses cdk-insights' aspect. To
+     * extend with project-specific suppressions, call
+     * `NagSuppressions.addResourceSuppressions(...)` from `cdk-nag` after
+     * 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.
@@ -265,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;
 }