cdk-insights 1.16.1 → 1.18.0

package/README.md

@@ -172,6 +172,34 @@ 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 (`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.
+
+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` | 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.
+
+Default is `false` — opt-in is conservative and additive.
+
 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

@@ -5,6 +5,13 @@ import type { IConstruct } from 'constructs';
 declare const CDK_INSIGHTS_METADATA_VERSION = "2.2.0";
 /** Prefix used to identify cdk-insights annotations in CloudFormation metadata */
 declare const CDK_INSIGHTS_ANNOTATION_PREFIX = "cdk-insights::";
+/**
+ * Sub-prefix for nag findings captured by `CdkInsightsNagDelegate` and emitted
+ * as Info annotations. Format: `cdk-insights::nagFinding::<json>`. The scan-side
+ * parser branches on this so nag findings flow through the same findings stream
+ * as cdk-insights' native rules instead of polluting CDK's error/warning channel.
+ */
+declare const CDK_INSIGHTS_NAG_FINDING_PREFIX = "cdk-insights::nagFinding::";
 /** Confidence level for source location detection */
 export type SourceLocationConfidence = 'high' | 'medium' | 'low';
 /** Source location information for a construct */
@@ -147,6 +154,39 @@ 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;
 }
 /**
  * Helper function to check if CDK stack traces are enabled.
@@ -168,6 +208,38 @@ export declare const createCdkInsightsLogger: (options?: CdkInsightsLoggerOption
  * Useful for development and debugging.
  */
 export declare const createExtremelyHelpfulConsoleLogger: (options?: CdkInsightsLoggerOptions) => INagLogger;
+/**
+ * Captures a non-compliant nag finding as a cdk-insights Info annotation.
+ *
+ * The on-the-wire shape is intentionally small and stable — the scan-side
+ * parser depends on it. Severity is mapped from cdk-nag's binary
+ * `NagMessageLevel` (ERROR/WARN) into cdk-insights' richer Severity enum:
+ *
+ *   - `NagMessageLevel.ERROR` → `HIGH` (rule pack author rated it security-critical)
+ *   - `NagMessageLevel.WARN`  → `MEDIUM` (advisory)
+ *
+ * `HIGH` is the conservative choice for ERROR — it preserves today's behaviour
+ * when the Validation Plugin is set to `minimumSeverity: "CRITICAL"` (nothing
+ * blocks deploy from nag), while letting users tighten to `HIGH` later to
+ * promote ERROR-rated nag findings into deploy gates.
+ */
+interface CdkInsightsNagFinding {
+    source: 'cdk-nag';
+    ruleId: string;
+    ruleOriginalName: string;
+    ruleInfo: string;
+    ruleExplanation: string;
+    /** Mapped from NagMessageLevel: ERROR→HIGH, WARN→MEDIUM. */
+    severity: 'HIGH' | 'MEDIUM';
+    /** Original cdk-nag level — kept so consumers can recover the source signal. */
+    level: 'Error' | 'Warning';
+    /** Sub-finding identifier from rules that emit multiple findings per resource. */
+    findingId?: string;
+    /** Construct path of the resource that failed the rule. */
+    resourcePath: string;
+    /** CloudFormation logical ID of the resource. */
+    logicalId: string;
+}
 /**
  * Creates a CDK Insights aspect using functional composition.
  * This is the recommended approach for new projects.
@@ -230,7 +302,8 @@ export declare class CdkInsightsAspect extends NagPack implements IAspect {
     visit(node: IConstruct): void;
 }
 /** Re-export constants for external use */
-export { CDK_INSIGHTS_METADATA_VERSION, CDK_INSIGHTS_ANNOTATION_PREFIX };
+export { CDK_INSIGHTS_METADATA_VERSION, CDK_INSIGHTS_ANNOTATION_PREFIX, CDK_INSIGHTS_NAG_FINDING_PREFIX, };
+export type { CdkInsightsNagFinding };
 /**
  * Clears all internal caches. Useful for testing or when processing
  * multiple independent CDK apps in the same process.