feat(core): add Template Transform API for post-resolution template modification

[lousydropout]

Issue

Partially addresses #17377 by introducing synthesis-time template transforms, fulfilling the request for a way to inspect and modify the final CloudFormation template before it is written. Deploy-time hooks remain out of scope.

Reason for this change

Right now, CDK has ways to customize constructs before synthesis and ways to validate synthesized output through metadata checks. But there is no way to inspect or update the final CloudFormation template right before it’s saved.

This capability enables use cases such as:

• checking the final template for policy or security issues
• adding organization-required metadata
• catching problems that only appear after all tokens are resolved
• making small adjustments to the template before deployment

Description of changes

This PR introduces Template Transforms, a simple feature that lets users register functions on the App that run right before each stack’s template is written out.

New APIs:

• ITemplateTransform -- interface with transformTemplate(stack, template)
• TemplateTransforms -- stores the transforms
• App.addTemplateTransform() -- adds a transform to the app

Modified APIs:
None. This PR does not modify any existing API.

How it works:

• Runs after all values are resolved
• Runs before the template is written to cdk.out
• Transforms run in the order they were added
• A transform may:
  • change the template directly
  • return a replacement template
  • throw an error itself to fail synthesis
  • or add annotations (e.g. addError) for validation that allows templates to be written but causes the CLI to fail after synthesis
• Does nothing unless a transform is added

This feature is fully opt-in and non-breaking. If a user does not register any template transforms, no objects or symbols are created unless the user registers a transform and no extra code paths run during synthesis. This is enforced by a TemplateTransforms.hasAny() check in Stack._toCloudFormation(), which completely skips the transform logic unless transforms have been explicitly added. Applications that do not use this API see zero behavioral or performance change.

Files changed:

• template-transform.ts - new file defining the transform interfaces and registry
• app.ts - added the addTemplateTransform() method
• stack.ts - added an opt-in branch to invoke template transforms during synthesis
• index.ts - added export * from "./template-transform"
• Documentation updates

Describe any new or updated permissions being added

N/A - This feature does not introduce any new IAM permissions.

Description of how you validated changes

• 22 unit tests checking registration, hasAny() opt-in behavior, ordering, mutation, errors, and nested stacks

• Integration test verifying output changes

• Manual testing using a sample CDK app with a local build of aws-cdk-lib linked into a local CDK CLI:

  • confirmed transforms run at the right time
  • confirmed template updates show up in cdk.out
  • confirmed errors and annotations behave correctly

• yarn build and yarn rosetta:extract --strict (from within packages/aws-cdk-lib) pass

Usage example

This example demonstrates how template transforms can enforce guardrails during synthesis. The transforms perform:

• Public ingress detection: Adds an error annotation if any Security Group allows 0.0.0.0/0 or ::/0, causing the CLI to fail after synthesis.
• Hard-coded IAM ARN detection: Adds an error annotation if any IAM policy contains literal "arn:" values instead of token-based references.
• Automatic execution on every stack during synthesis, using the fully resolved template.

import * as cdk from "aws-cdk-lib";
import { AppStack } from "../lib/app-stack";

const app = new cdk.App();

// Prevent security group being opened to everyone
class NoPublicIngress implements cdk.ITemplateTransform {
  transformTemplate(stack: cdk.Stack, template: any): void {
    console.log("[NoPublicIngress] Reviewing security group practices")
    const resources = template.Resources ?? {};
  
    for (const logicalId of Object.keys(resources)) {
      const resource: any = resources[logicalId];
  
      if (resource.Type !== "AWS::EC2::SecurityGroup") continue;
  
      const ingress = resource.Properties?.SecurityGroupIngress ?? [];
      
      for (const rule of ingress) {
        if (rule.CidrIp === "0.0.0.0/0" || rule.CidrIpv6 === "::/0") {
          // Add an error annotation: this will allow the template to be written,
          // but the CLI will fail after synthesis and block deployment
          cdk.Annotations.of(stack).addError(`Security Group ${logicalId} in stack ${stack.stackName} allows public ingress (${cidr4 ?? cidr6}).`);
        }
      }
    }
  }
}

// Prevent unsafe IAM policies that use hard-coded ARNs instead of dynamic references
class BlockHardCodedIamArns implements cdk.ITemplateTransform {
  public transformTemplate(stack: cdk.Stack, template: any): void {
    console.log("[BlockHardCodedIamArns] Reviewing IAM references")
    const resources = template.Resources || {};

    for (const logicalId of Object.keys(resources)) {
      const resource = resources[logicalId];

      if (resource.Type === "AWS::IAM::Policy") {
        const document = resource.Properties?.PolicyDocument;
        if (document) {
          // Scan policy for hard-coded ARN values.
          // Tokens are resolved at this point, so any string starting with "arn:" is literal.
          const json = JSON.stringify(document);
          if (json.indexOf("arn:") !== -1) {
            // Add an error annotation: this will allow the template to be written,
            // but the CLI will fail after synthesis and block deployment
            cdk.Annotations.of(stack).addError(`IAM Policy ${logicalId} contains a hard-coded ARN. Use Fn.importValue, Ref, or GetAtt instead.`);
          }
        }
      }
    }
  }
}


// Add the compliance checks
app.addTemplateTransform(new NoPublicIngress());
app.addTemplateTransform(new BlockHardCodedIamArns());

new AppStack(app, "AppStack", {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT,
    region:  process.env.CDK_DEFAULT_REGION,
  },
});

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license.

[aws-cdk-automation]

(This review is outdated)

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.