CDK Aspect Integration

What is the CDK Aspect?

Pair with the Validations Plugin (synth-time enforcement)

On aws-cdk-lib ≥ 2.251.0 you can also register CDK Insights as a native CDK Validations plugin. cdk synth will then fail with a CDK Insights report if any rules trigger — useful for blocking deploys in CI without an extra step.

The plugin and the aspect are complementary, not alternatives: the aspect captures source locations for richer findings, the plugin enforces them at synth time. Most projects want both.

import { App, Validations } from 'aws-cdk-lib';
import { CdkInsightsPolicyValidationPlugin } from 'cdk-insights';

const app = new App();
Validations.of(app).addPlugins(new CdkInsightsPolicyValidationPlugin());

Scope it with selectedServices, minimumSeverity, or customRules if you only want a subset of findings to block synth.

The plugin honours the same suppressions as cdk-insights scan — .cdk-insights.json (ignoreRules / ignorePaths) and inline Validations.of(scope).acknowledge(...) entries — so findings suppressed in the CLI are also suppressed at synth time.

cdk-nag integration (without blocking deploys)

The CDK Insights aspect captures cdk-nag findings into the cdk-insights findings stream without letting cdk-nag's default Annotations.addError abort your synth. You get the full breadth of cdk-nag rule packs as part of your cdk-insights report, and your CI can decide for itself which severities to fail on (via --failOnCritical).

You do not need to install cdk-nag separately. CDK Insights bundles cdk-nag at runtime, so the AwsSolutions-* rule pack and suppressNagRules work out of the box once you add the aspect. Only install cdk-nag directly if you also want to call NagSuppressions.addResourceSuppressions(...) yourself for per-resource suppressions.

cdk-nag severity is preserved (NagMessageLevel.ERROR → HIGH, WARN → MEDIUM), with a curated CRITICAL override list for genuinely deploy-blocking rules.

Suppress common boilerplate noise

cdkBoilerplateSuppressions: true auto-suppresses cdk-nag findings that consistently fire on AWS-recommended boilerplate (managed policies like AwsSolutions-IAM4, current LTS Lambda runtimes via AwsSolutions-L1). The list updates with each cdk-insights release. Anything not in the curated list continues to surface normally.

Aspects.of(app).add(createCdkInsightsAspect({
  cdkBoilerplateSuppressions: true,
}));

Project-specific suppressions

suppressNagRules takes an array of cdk-nag rule IDs to suppress globally. Two forms — string shorthand for quick triage, object form (with a written reason) for checked-in code:

Aspects.of(app).add(createCdkInsightsAspect({
  cdkBoilerplateSuppressions: true,
  suppressNagRules: [
    // String shorthand — generic auto-reason, fine for triage
    'AwsSolutions-APIG2',
    // Object form — written justification, recommended for prod
    {
      id: 'AwsSolutions-COG2',
      reason: 'MFA is opt-in by product policy; see RFC-0042.',
    },
  ],
}));

Both options compose — enable both simultaneously. For finer-grained control (per-resource or per-appliesTo-pattern), call NagSuppressions.addResourceSuppressions(...) from cdk-nag directly after constructing your stacks.

Aspects vs. Mixins

aws-cdk-lib ships two visitor-style APIs that both mutate constructs: Aspects (declarative, applied at synth) and Mixins (imperative, applied immediately at .with() call time). They're complementary, not competitors.

For CDK Insights this matters in one direction only: the CDK Insights aspect runs at synth, after every mixin has already been applied. So the aspect always sees the final post-mixin state of your constructs — there is no ordering footgun, no "did the mixin happen yet?" question. Findings are attributed to applied mixins automatically via the aws:cdk:analytics:mixin manifest stream.

See the CDK Mixins page for how cdk-insights detects mixin-specific footguns at template level.

Best Practices