cdk-insights 1.16.0 → 1.17.0

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 */
@@ -168,6 +175,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 +269,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.