feat: display CloudFormation Guard Hook failures

packages/@aws-cdk-testing/cli-integ/resources/cdk-apps/guard-hook-app/app.js

@@ -0,0 +1,99 @@
+const cdk = require('aws-cdk-lib/core');
+const s3 = require('aws-cdk-lib/aws-s3');
+const iam = require('aws-cdk-lib/aws-iam');
+const s3deploy = require('aws-cdk-lib/aws-s3-deployment');
+
+const stackPrefix = process.env.STACK_NAME_PREFIX;
+if (!stackPrefix) {
+  throw new Error('the STACK_NAME_PREFIX environment variable is required');
+}
+
+const guardRuleKey = 'rules/AWS_S3_Bucket_AccessControl.guard';
+
+const guardRuleContent = `rule AWS_S3_Bucket_AccessControl
+{
+    let resources = Resources.*[ Type == "AWS::S3::Bucket" ]
+    %resources[*] {
+        Properties.AccessControl not exists
+        <<
+            AccessControl is deprecated
+        >>
+    }
+}`;
+
+// Setup Guard Hook that will evaluate and fail the test stack
+class GuardHookSetupStack extends cdk.Stack {
+  constructor(scope, id, props) {
+    super(scope, id, props);
+
+    // S3 bucket for Guard rules
+    const rulesBucket = new s3.Bucket(this, 'RulesBucket', {
+      removalPolicy: cdk.RemovalPolicy.DESTROY,
+      autoDeleteObjects: true,
+    });
+
+    // S3 bucket for Guard logs
+    const logsBucket = new s3.Bucket(this, 'LogsBucket', {
+      removalPolicy: cdk.RemovalPolicy.DESTROY,
+      autoDeleteObjects: true,
+    });
+
+    // Upload Guard rule to rules bucket
+    new s3deploy.BucketDeployment(this, 'UploadGuardRule', {
+      sources: [s3deploy.Source.data(guardRuleKey, guardRuleContent)],
+      destinationBucket: rulesBucket,
+    });
+
+    // IAM role for Guard Hook execution
+    const hookRole = new iam.Role(this, 'GuardHookExecutionRole', {
+      assumedBy: new iam.ServicePrincipal('hooks.cloudformation.amazonaws.com'),
+    });
+    hookRole.addToPolicy(new iam.PolicyStatement({
+      effect: iam.Effect.ALLOW,
+      actions: ['s3:ListBucket', 's3:GetObject', 's3:GetObjectVersion'],
+      resources: [rulesBucket.bucketArn, rulesBucket.arnForObjects('*')],
+    }));
+    hookRole.addToPolicy(new iam.PolicyStatement({
+      effect: iam.Effect.ALLOW,
+      actions: ['s3:PutObject'],
+      resources: [logsBucket.arnForObjects('*')],
+    }));
+
+    // Guard Hook - activates and configures the AWS Guard Hook in this account/region
+    new cdk.CfnGuardHook(this, 'GuardHook', {
+      alias: 'Private::Guard::TestHook',
+      executionRole: hookRole.roleArn,
+      failureMode: 'FAIL',
+      hookStatus: 'ENABLED',
+      ruleLocation: {
+        uri: `s3://${rulesBucket.bucketName}/${guardRuleKey}`,
+      },
+      logBucket: logsBucket.bucketName,
+      targetOperations: ['RESOURCE'],
+      stackFilters: {
+        filteringCriteria: "ANY",
+        stackNames: {
+          // Do not evalute this stack with the hook
+          exclude: [cdk.Aws.STACK_NAME]
+        }
+      }
+    });
+  }
+}
+
+class GuardHookTestStack extends cdk.Stack {
+  constructor(scope, id, props) {
+    super(scope, id, props);
+
+    // This bucket violates the Guard rule by using the deprecated AccessControl property
+    new s3.CfnBucket(this, 'NonCompliantBucket', {
+      accessControl: 'Private',
+    });
+  }
+}
+
+const app = new cdk.App();
+new GuardHookSetupStack(app, `${stackPrefix}-guard-hook-setup`);
+new GuardHookTestStack(app, `${stackPrefix}-guard-hook-test`);
+
+app.synth();

packages/@aws-cdk-testing/cli-integ/resources/cdk-apps/guard-hook-app/cdk.json

@@ -0,0 +1,4 @@
+{
+  "app": "node app.js",
+  "versionReporting": false
+}

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/deploy/cdk-deploy-guard-hook-failure-displays-annotations.integtest.ts

@@ -0,0 +1,22 @@
+import { integTest, withSpecificFixture } from '../../../lib';
+
+jest.setTimeout(2 * 60 * 60_000);
+
+integTest(
+  'deploy with guard hook failure displays hook annoations',
+  withSpecificFixture('guard-hook-app', async (fixture) => {
+    // Deploy the setup stack which creates the Guard Hook via CloudFormation
+    await fixture.cdkDeploy('guard-hook-setup');
+
+    // Attempt to deploy non-compliant stack (should fail due to Guard Hook)
+    const deployOutput = await fixture.cdkDeploy('guard-hook-test', {
+      options: ['--no-rollback'],
+      allowErrExit: true,
+    });
+    expect(deployOutput).toContain('CREATE_FAILED');
+    expect(deployOutput).toContain('NonCompliant Rules:');
+    expect(deployOutput).toContain('[AWS_S3_Bucket_AccessControl]');
+    expect(deployOutput).toContain('• Check was not compliant as property [/Resources/NonCompliantBucket/Properties/AccessControl[L:0,C:91]] existed.');
+    expect(deployOutput).toContain('Remediation: AccessControl is deprecated');
+  }),
+);

packages/@aws-cdk/toolkit-lib/lib/api/aws-auth/sdk.ts

@@ -115,6 +115,8 @@ import type {
   ExecuteStackRefactorCommandOutput,
   DescribeEventsCommandOutput,
   DescribeEventsCommandInput,
+  GetHookResultCommandInput,
+  GetHookResultCommandOutput,
 } from '@aws-sdk/client-cloudformation';
 import {
   paginateDescribeEvents,
@@ -157,6 +159,7 @@ import {
   DetectStackResourceDriftCommand,
   waitUntilStackRefactorCreateComplete,
   waitUntilStackRefactorExecuteComplete,
+  GetHookResultCommand,
 } from '@aws-sdk/client-cloudformation';
 import type { OperationEvent } from '@aws-sdk/client-cloudformation/dist-types/models/models_0';
 import type {
@@ -497,6 +500,7 @@ export interface ICloudFormationClient {
   executeStackRefactor(input: ExecuteStackRefactorCommandInput): Promise<ExecuteStackRefactorCommandOutput>;
   waitUntilStackRefactorCreateComplete(input: DescribeStackRefactorCommandInput): Promise<WaiterResult>;
   waitUntilStackRefactorExecuteComplete(input: DescribeStackRefactorCommandInput): Promise<WaiterResult>;
+  getHookResult(input: GetHookResultCommandInput): Promise<GetHookResultCommandOutput>;
 }
 
 export interface ICloudWatchLogsClient {
@@ -848,6 +852,8 @@ export class SDK {
           input,
         );
       },
+      getHookResult: (input: GetHookResultCommandInput): Promise<GetHookResultCommandOutput> =>
+        client.send(new GetHookResultCommand(input)),
     };
   }
 

packages/@aws-cdk/toolkit-lib/lib/api/deployments/deploy-stack.ts

@@ -594,6 +594,7 @@ class FullCloudFormationDeployment {
       resourcesTotal: expectedChanges,
       ioHelper: this.ioHelper,
       changeSetCreationTime: startTime,
+      envResources: this.options.envResources,
     });
     await monitor.start();
 

packages/@aws-cdk/toolkit-lib/lib/api/stack-events/stack-activity-monitor.ts

@@ -8,6 +8,7 @@ import type { StackActivity } from '../../payloads/stack-activity';
 import { DeploymentErrorCodes } from '../../toolkit/toolkit-error';
 import { isCancellationEvent, isErrorEvent, isRegularResourceEvent } from '../../util';
 import type { ICloudFormationClient } from '../aws-auth/private';
+import type { EnvironmentResources } from '../environment';
 import { IO, type IoHelper } from '../io/private';
 import { resourceMetadata } from '../resource-metadata/resource-metadata';
 
@@ -62,6 +63,14 @@ export interface StackActivityMonitorProps {
    * @default 2_000
    */
   readonly pollingInterval?: number;
+
+  /**
+   * Environment resources, used to look up the bootstrap toolkit version when
+   * diagnosing Guard Hook annotation fetch failures.
+   *
+   * @default - Bootstrap version is not reported in error messages
+   */
+  readonly envResources?: EnvironmentResources;
 }
 
 /**
@@ -110,6 +119,8 @@ export class StackActivityMonitor {
   private readonly ioHelper: IoHelper;
   private readonly stackName: string;
   private readonly stack: CloudFormationStackArtifact;
+  private readonly cfn: ICloudFormationClient;
+  private readonly envResources?: EnvironmentResources;
 
   constructor({
     cfn,
@@ -119,10 +130,13 @@ export class StackActivityMonitor {
     resourcesTotal,
     changeSetCreationTime,
     pollingInterval = 2_000,
+    envResources,
   }: StackActivityMonitorProps) {
     this.ioHelper = ioHelper;
     this.stack = stack;
     this.stackName = stackName;
+    this.cfn = cfn;
+    this.envResources = envResources;
 
     this.progressMonitor = new StackProgressMonitor(resourcesTotal);
     this.pollingInterval = pollingInterval;
@@ -231,6 +245,77 @@ export class StackActivityMonitor {
     return resourceMetadata(this.stack, logicalId);
   }
 
+  /**
+   * Trims leading/trailing whitespace, collapses all internal whitespace
+   * (including newlines) to a single space, and truncates to `maxChars`
+   * characters, appending `[...truncated]` when the original was longer.
+   */
+  private normalizeMessage(message: string, maxChars: number = 400): string {
+    const normalized = message.trim().replace(/\s+/g, ' ');
+    return normalized.length > maxChars
+      ? normalized.substring(0, maxChars) + '[...truncated]'
+      : normalized;
+  }
+
+  /**
+   * Fetches Guard Hook annotation details via GetHookResult API and formats them
+   * into a human-readable string. Returns undefined if the fetch fails or there
+   * are no failed annotations.
+   */
+  private async fetchGuardHookAnnotations(hookInvocationId: string): Promise<string | undefined> {
+    try {
+      const result = await this.cfn.getHookResult({ HookResultId: hookInvocationId });
+      const annotations = result.Annotations ?? [];
+      const failedAnnotations = annotations.filter((a) => a.Status === 'FAILED');
+      if (failedAnnotations.length === 0) {
+        return undefined;
+      }
+
+      const lines: string[] = ['NonCompliant Rules:', ''];
+      for (const annotation of failedAnnotations) {
+        if (annotation.AnnotationName) {
+          lines.push(`[${annotation.AnnotationName}]`);
+        }
+        if (annotation.StatusMessage) {
+          lines.push(`• ${this.normalizeMessage(annotation.StatusMessage)}`);
+        }
+        if (annotation.RemediationMessage) {
+          lines.push(`Remediation: ${this.normalizeMessage(annotation.RemediationMessage)}`);
+        }
+        lines.push('');
+      }
+      return lines.join('\n').trimEnd();
+    } catch (e: any) {
+      const errorMessage = e instanceof Error ? e.message : String(e);
+
+      const isPermissionsError =
+        e.name === 'AccessDeniedException' ||
+        (typeof errorMessage === 'string' && errorMessage.toLowerCase().includes('not authorized to perform: cloudformation:gethookresult'));
+
+      if (isPermissionsError && this.envResources) {
+        let currentVersion: number | undefined = undefined;
+        try {
+          currentVersion = (await this.envResources.lookupToolkit()).version;
+        } catch {
+          // ignore errors looking up the bootstrap version
+        }
+
+        await this.ioHelper.defaults.warn(
+          util.format(
+            `Failed to fetch result details for Hook invocation ${hookInvocationId}: ${errorMessage}. Make sure you have permissions to call the GetHookResult API, or re-bootstrap your environment by running 'cdk bootstrap' to update the Bootstrap CDK Toolkit stack.
+            'Bootstrap toolkit stack version 31 or later is needed; current version: ${currentVersion ?? 'unknown'}.`,
+          ),
+        );
+      } else {
+        await this.ioHelper.defaults.warn(
+          util.format('Failed to fetch Guard Hook details for invocation %s: %s', hookInvocationId, errorMessage),
+        );
+      }
+
+      return undefined;
+    }
+  }
+
   /**
    * Reads all new events from the stack history
    *
@@ -242,6 +327,14 @@ export class StackActivityMonitor {
     for (const resourceEvent of pollEvents) {
       this.progressMonitor.process(resourceEvent.event);
 
+      // If this is a failed Guard Hook event with an invocation ID, fetch annotations
+      if (resourceEvent.event.HookInvocationId) {
+        const annotations = await this.fetchGuardHookAnnotations(resourceEvent.event.HookInvocationId);
+        if (annotations) {
+          resourceEvent.event.HookStatusReason = annotations;
+        }
+      }
+
       const activity: StackActivity = {
         deployment: monitorId,
         event: resourceEvent.event,