cdk-insights 1.6.0 → 1.7.0

package/README.md

@@ -146,21 +146,59 @@ Create a `.cdk-insights.json` in your project root, or run:
 npx cdk-insights config setup
 ```
 
-### CDK Aspect (Enhanced Analysis)
+### In-App Integration
 
-For precise file/line metadata and richer context, add the aspect in your CDK app:
+CDK Insights ships two integration points; they are complementary, and most projects want both. Install them interactively with:
+
+```bash
+npx cdk-insights setup
+```
+
+| Integration | When to use | What you get |
+|-------------|-------------|--------------|
+| **Aspect** | Always — pairs with `cdk-insights scan` | Precise file/line metadata, source-location tracking, richer findings |
+| **Validations plugin** (`aws-cdk-lib` ≥ 2.251.0) | When you want CI to fail on synth | `cdk synth` blocks on findings; native CDK plugin surface; one less CI step |
+
+#### Aspect — for precise findings
 
 ```ts
 import { App, Aspects } from 'aws-cdk-lib';
-import { CdkInsightsAspect } from 'cdk-insights';
+import { createCdkInsightsAspect } from 'cdk-insights';
 
 const app = new App();
-Aspects.of(app).add(new CdkInsightsAspect());
+Aspects.of(app).add(createCdkInsightsAspect());
 // define stacks...
 app.synth();
 ```
 
-Run synth with `CDK_DEBUG=true` so CDK records stack traces for each construct. On `aws-cdk-lib` ≥ 2.252.0, findings on deferred or post-construction property assignments (lifecycle rules, env vars, role policies, `Lazy.string`/`Lazy.any` values) now point at the property setter line — not the construct constructor — automatically. Older CDKs continue to work; you'll just get construct-level attribution.
+Run synth with `CDK_DEBUG=true` so CDK records stack traces for each construct. On `aws-cdk-lib` ≥ 2.252.0, findings on deferred or post-construction property assignments (lifecycle rules, env vars, role policies, `Lazy.string`/`Lazy.any` values) point at the property setter line — not the construct constructor — automatically. Older CDKs continue to work; you'll just get construct-level attribution.
+
+#### Validations plugin — for synth-time enforcement
+
+Requires `aws-cdk-lib` ≥ 2.251.0:
+
+```ts
+import { App, Validations } from 'aws-cdk-lib';
+import { CdkInsightsPolicyValidationPlugin } from 'cdk-insights';
+
+const app = new App();
+Validations.of(app).addPlugins(new CdkInsightsPolicyValidationPlugin());
+// define stacks...
+app.synth();
+```
+
+`cdk synth` will fail with a CDK Insights report if any rules trigger. Pass `selectedServices`, `minimumSeverity`, or `customRules` to scope what counts as a synth-time block:
+
+```ts
+new CdkInsightsPolicyValidationPlugin({
+  selectedServices: ['IAM', 'S3'],
+  minimumSeverity: 'HIGH',
+});
+```
+
+The plugin sees synthesized templates only — no construct tree. Pair it with the aspect (above) when you also want source-location capture in the `cdk-insights scan` report.
+
+The plugin honours the same suppressions as `cdk-insights scan` — `.cdk-insights.json` (`ignoreRules` / `ignorePaths`) and inline `Validations.of(scope).acknowledge(...)` entries are both respected, so a finding suppressed in the CLI is also suppressed at synth time. Pass `ignoreProjectConfig: true` or `ignoreInlineAcknowledgements: true` to opt out of either source.
 
 ### Suppressing Findings
 

package/dist/analysis/static/awsServices/ECS/logging/ecsServiceConnectAccessLogs.d.ts

@@ -0,0 +1,2 @@
+import type { AnalysisResults, CloudFormationStack, CreateFindingFunction } from '../../../../../types/analysis.types';
+export declare const checkECSServiceConnectAccessLogs: (template: CloudFormationStack, createFinding: CreateFindingFunction) => AnalysisResults;

package/dist/analysis/static/awsServices/ECS/logging/ecsServiceConnectAccessLogs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/analysis/static/staticAnalysis.d.ts

@@ -1,6 +1,6 @@
+import type { CustomRuleDefinition } from '../../rules/customRules.types';
 import type { AnalysisResults, CloudFormationStack, CreateFindingFunction, ServiceName, Severity } from '../../types/analysis.types';
 import type { ConstructMetadata } from './solutionConstructs/loadConstructMetadata';
-import type { CustomRuleDefinition } from '../../rules/customRules.types';
 export type AnalysisStatistics = {
     totalResources: number;
     analyzedResources: number;

package/dist/analysis/templateLevel/checks/schemaDrift/checkSchemaDrift.d.ts

@@ -3,16 +3,39 @@ import type { AnalysisResults, CloudFormationStack, CreateFindingFunction } from
 import type { RuleRegistry } from '../../../../types/rules.types';
 type RuleRegistryLike = RuleRegistry;
 type SchemaChangeRegistry = Record<string, SchemaChange[]>;
+/**
+ * Two finding kinds share the same registry and traversal:
+ *   - `regression`: a previously-readable property was removed or renamed,
+ *     so an existing rule may have silently lost coverage.
+ *   - `coverage-gap`: a new property was added on a resource type we already
+ *     have rules for, so a maintainer should *consider* whether a rule should
+ *     evaluate it. Lower urgency, lower noise — only fires for resource types
+ *     already on our radar.
+ */
+export type SchemaDriftKind = 'regression' | 'coverage-gap';
 /**
  * Inner function exposed for unit tests so cdkVersion and the registries can be
- * injected directly. Production callers should use `checkSchemaDrift`.
+ * injected directly. Production callers should use the named wrapper for the
+ * specific finding kind they want to surface.
+ *
+ * @param kind - Which finding category to emit. Defaults to `regression` for
+ *   backwards compatibility with the original single-kind behaviour.
  */
-export declare const findSchemaDriftFindings: (template: CloudFormationStack, createFinding: CreateFindingFunction, cdkVersion: string | null, schemaChanges?: SchemaChangeRegistry, rules?: RuleRegistryLike) => AnalysisResults;
+export declare const findSchemaDriftFindings: (template: CloudFormationStack, createFinding: CreateFindingFunction, cdkVersion: string | null, kind?: SchemaDriftKind, schemaChanges?: SchemaChangeRegistry, rules?: RuleRegistryLike) => AnalysisResults;
 /**
  * Template-level check: surface known L1 schema-drift events that may have
- * affected rule coverage in the user's CDK version.
+ * silently invalidated rule coverage in the user's CDK version (removed or
+ * renamed properties on covered resource types).
  *
  * Silent fallback when the user's aws-cdk-lib version cannot be resolved.
  */
 export declare const checkSchemaDrift: (template: CloudFormationStack, createFinding: CreateFindingFunction) => AnalysisResults;
+/**
+ * Template-level check: surface newly-added L1 properties on resource types
+ * already covered by cdk-insights rules. Hint to maintainers/users that a new
+ * rule may be worth opening — not a regression.
+ *
+ * Silent fallback when the user's aws-cdk-lib version cannot be resolved.
+ */
+export declare const checkSchemaDriftCoverageGaps: (template: CloudFormationStack, createFinding: CreateFindingFunction) => AnalysisResults;
 export {};

package/dist/cli/commands/setup.d.ts

@@ -0,0 +1,12 @@
+import type { CommandModule } from 'yargs';
+type IntegrationChoice = 'aspect-and-plugin' | 'plugin-only' | 'aspect-only' | 'cdk-nag-only' | 'skip';
+interface SnippetParts {
+    imports: string[];
+    body: string[];
+}
+export declare const buildSnippet: (choice: IntegrationChoice, isJavaScript: boolean) => SnippetParts;
+export declare const alreadyInstalled: (source: string, parts: SnippetParts) => boolean;
+export declare const insertSnippet: (source: string, parts: SnippetParts) => string | null;
+export declare const setupCommand: CommandModule;
+export declare const setupCdkNagCommand: CommandModule;
+export {};

package/dist/cli/commands/setup.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/commands/setupCdkNag.d.ts

@@ -1,2 +1 @@
-import type { CommandModule } from 'yargs';
-export declare const setupCdkNagCommand: CommandModule;
+export { setupCdkNagCommand } from './setup';

package/dist/constants/cdkSchemaChanges.d.ts

@@ -27,6 +27,15 @@ export type SchemaChange = {
         from: string;
         to: string;
     }[];
+    /**
+     * Properties newly added in this release. Treated as a coverage *hint*, not
+     * a regression: the `coverage-gap` finding kind only fires when the
+     * `resourceType` is already targeted by at least one existing rule, so users
+     * are not nagged about resources they don't analyse. Use this to capture
+     * additions that look security-, cost-, reliability-, or compliance-relevant
+     * and may warrant a new rule. Exhaustive coverage is explicitly not the goal.
+     */
+    addedProperties?: string[];
     /**
      * Names of GetAtt return attributes that were removed. Recorded for
      * completeness, but does not drive findings on its own — rules don't read
@@ -46,8 +55,10 @@ export type SchemaChange = {
 /**
  * Map of aws-cdk-lib version → schema changes introduced in that release.
  *
- * Adding an entry: include the release tag link, only populate `removedProperties`
- * / `renamedProperties` if the change touches CFN-level properties (those drive
- * findings). Attributes/types are recorded for traceability but stay silent.
+ * Adding an entry: include the release tag link. Populate `removedProperties` /
+ * `renamedProperties` for regressions that may have invalidated rule coverage,
+ * and `addedProperties` for newly-introduced properties that look worth a new
+ * rule (security, cost, reliability, compliance). Attributes/types are
+ * recorded for traceability but stay silent.
  */
 export declare const CDK_L1_SCHEMA_CHANGES: Record<string, SchemaChange[]>;