feat(iam): add feature flag to validate PolicyStatement SID is alphanumeric

- Add IAM_POLICY_STATEMENT_VALIDATE_SID feature flag
- Validate SIDs are alphanumeric (A-Z, a-z, 0-9) when flag enabled
- Fix invalid SIDs in aws-ecs cluster.ts
- Add comprehensive test coverage for SID validation

Closes #34819

Author: camerondurham

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## Unreleased
+
+### Features
+
+* **iam:** add feature flag to validate PolicyStatement SID is alphanumeric ([#34819](https://github.com/aws/aws-cdk/issues/34819))
+  - New feature flag `@aws-cdk/aws-iam:policyStatementValidateSid` enforces IAM SID validation
+  - SIDs must be alphanumeric (A-Z, a-z, 0-9) per AWS IAM requirements
+  - Validation occurs at synthesis time when flag is enabled
+  - Fixed invalid SIDs in aws-ecs cluster.ts to be alphanumeric
+
 ## [1.158.0](https://github.com/aws/aws-cdk/compare/v1.157.0...v1.158.0) (2022-05-27)
 
 

packages/aws-cdk-lib/aws-ecs/lib/cluster.ts

@@ -392,14 +392,14 @@ export class Cluster extends Resource implements ICluster {
     };
 
     key.addToResourcePolicy(new PolicyStatement({
-      sid: 'Allow generate data key access for Fargate tasks.',
+      sid: 'AllowGenerateDataKeyAccessForFargateTasks',
       principals: [new ServicePrincipal('fargate.amazonaws.com')],
       resources: ['*'],
       actions: ['kms:GenerateDataKeyWithoutPlaintext'],
       conditions: clusterConditions,
     }));
     key.addToResourcePolicy(new PolicyStatement({
-      sid: 'Allow grant creation permission for Fargate tasks.',
+      sid: 'AllowGrantCreationPermissionForFargateTasks',
       principals: [new ServicePrincipal('fargate.amazonaws.com')],
       resources: ['*'],
       actions: ['kms:CreateGrant'],

packages/aws-cdk-lib/aws-iam/lib/policy-document.ts

@@ -78,6 +78,13 @@ export class PolicyDocument implements cdk.IResolvable {
     this.freezeStatements();
     this._maybeMergeStatements(context.scope);
 
+    // Validate statement SIDs if feature flag is enabled
+    if (cdk.FeatureFlags.of(context.scope).isEnabled(cxapi.IAM_POLICY_STATEMENT_VALIDATE_SID)) {
+      for (const statement of this.statements) {
+        statement._validateSid();
+      }
+    }
+
     // In the previous implementation of 'merge', sorting of actions/resources on
     // a statement always happened, even  on singular statements. In the new
     // implementation of 'merge', sorting only happens when actually combining 2

packages/aws-cdk-lib/aws-iam/lib/policy-statement.ts

@@ -232,6 +232,16 @@ export class PolicyStatement {
     }
   }
 
+  /**
+   * Validate that the SID is alphanumeric
+   * @internal
+   */
+  public _validateSid() {
+    if (this._sid !== undefined && !cdk.Token.isUnresolved(this._sid) && !/^[0-9A-Za-z]*$/.test(this._sid)) {
+      throw new UnscopedValidationError(`Statement ID (sid) must be alphanumeric. Got '${this._sid}'. The Sid element supports ASCII uppercase letters (A-Z), lowercase letters (a-z), and numbers (0-9).`);
+    }
+  }
+
   private validatePolicyActions(actions: string[]) {
     // In case of an unresolved list of actions return early
     if (cdk.Token.isUnresolved(actions)) return;

packages/aws-cdk-lib/aws-iam/test/policy-statement.test.ts

@@ -1,4 +1,6 @@
+import * as cdk from '../../core';
 import { Stack } from '../../core';
+import * as cxapi from '../../cx-api';
 import { AnyPrincipal, Group, PolicyDocument, PolicyStatement, Effect } from '../lib';
 
 describe('IAM policy statement', () => {
@@ -260,4 +262,93 @@ describe('IAM policy statement', () => {
       expect(mod).toThrow(/can no longer be modified/);
     }
   });
+
+  describe('SID validation', () => {
+    test('does not validate when feature flag is disabled', () => {
+      const app = new cdk.App();
+      const stack = new Stack(app, 'Stack');
+      const doc = new PolicyDocument();
+      doc.addStatements(new PolicyStatement({
+        sid: 'Invalid-SID-With-Dashes',
+        actions: ['s3:GetObject'],
+        resources: ['*'],
+      }));
+
+      expect(() => stack.resolve(doc)).not.toThrow();
+    });
+
+    test('validates alphanumeric SID when feature flag is enabled', () => {
+      const app = new cdk.App({
+        context: { [cxapi.IAM_POLICY_STATEMENT_VALIDATE_SID]: true },
+      });
+      const stack = new Stack(app, 'Stack');
+      const doc = new PolicyDocument();
+      doc.addStatements(new PolicyStatement({
+        sid: 'ValidSID123',
+        actions: ['s3:GetObject'],
+        resources: ['*'],
+      }));
+
+      expect(() => stack.resolve(doc)).not.toThrow();
+    });
+
+    test('throws error for invalid SID when feature flag is enabled', () => {
+      const app = new cdk.App({
+        context: { [cxapi.IAM_POLICY_STATEMENT_VALIDATE_SID]: true },
+      });
+      const stack = new Stack(app, 'Stack');
+      const doc = new PolicyDocument();
+      doc.addStatements(new PolicyStatement({
+        sid: 'Invalid-SID',
+        actions: ['s3:GetObject'],
+        resources: ['*'],
+      }));
+
+      expect(() => stack.resolve(doc)).toThrow(/Statement ID \(sid\) must be alphanumeric/);
+    });
+
+    test('allows empty SID', () => {
+      const app = new cdk.App({
+        context: { [cxapi.IAM_POLICY_STATEMENT_VALIDATE_SID]: true },
+      });
+      const stack = new Stack(app, 'Stack');
+      const doc = new PolicyDocument();
+      doc.addStatements(new PolicyStatement({
+        sid: '',
+        actions: ['s3:GetObject'],
+        resources: ['*'],
+      }));
+
+      expect(() => stack.resolve(doc)).not.toThrow();
+    });
+
+    test('allows undefined SID', () => {
+      const app = new cdk.App({
+        context: { [cxapi.IAM_POLICY_STATEMENT_VALIDATE_SID]: true },
+      });
+      const stack = new Stack(app, 'Stack');
+      const doc = new PolicyDocument();
+      doc.addStatements(new PolicyStatement({
+        actions: ['s3:GetObject'],
+        resources: ['*'],
+      }));
+
+      expect(() => stack.resolve(doc)).not.toThrow();
+    });
+
+    test('allows tokens in SID', () => {
+      const app = new cdk.App({
+        context: { [cxapi.IAM_POLICY_STATEMENT_VALIDATE_SID]: true },
+      });
+      const stack = new Stack(app, 'Stack');
+      const doc = new PolicyDocument();
+      doc.addStatements(new PolicyStatement({
+        sid: cdk.Fn.ref('SomeParameter'),
+        actions: ['s3:GetObject'],
+        resources: ['*'],
+      }));
+
+      expect(() => stack.resolve(doc)).not.toThrow();
+    });
+  });
 });

packages/aws-cdk-lib/cx-api/lib/features.ts

@@ -132,6 +132,7 @@ export const Enable_IMDS_Blocking_Deprecated_Feature = '@aws-cdk/aws-ecs:enableI
 export const Disable_ECS_IMDS_Blocking = '@aws-cdk/aws-ecs:disableEcsImdsBlocking';
 export const ALB_DUALSTACK_WITHOUT_PUBLIC_IPV4_SECURITY_GROUP_RULES_DEFAULT = '@aws-cdk/aws-elasticloadbalancingV2:albDualstackWithoutPublicIpv4SecurityGroupRulesDefault';
 export const IAM_OIDC_REJECT_UNAUTHORIZED_CONNECTIONS = '@aws-cdk/aws-iam:oidcRejectUnauthorizedConnections';
+export const IAM_POLICY_STATEMENT_VALIDATE_SID = '@aws-cdk/aws-iam:policyStatementValidateSid';
 export const ENABLE_ADDITIONAL_METADATA_COLLECTION = '@aws-cdk/core:enableAdditionalMetadataCollection';
 export const LAMBDA_CREATE_NEW_POLICIES_WITH_ADDTOROLEPOLICY = '@aws-cdk/aws-lambda:createNewPoliciesWithAddToRolePolicy';
 export const SET_UNIQUE_REPLICATION_ROLE_NAME = '@aws-cdk/aws-s3:setUniqueReplicationRoleName';
@@ -1469,6 +1470,20 @@ export const FLAGS: Record<string, FlagInfo> = {
     compatibilityWithOldBehaviorMd: 'Disable the feature flag to allow unsecure OIDC connection.',
   },
 
+  //////////////////////////////////////////////////////////////////////
+  [IAM_POLICY_STATEMENT_VALIDATE_SID]: {
+    type: FlagType.BugFix,
+    summary: 'Validate PolicyStatement SID is alphanumeric',
+    detailsMd: `
+      When enabled, PolicyStatement SID validation enforces alphanumeric characters only (A-Z, a-z, 0-9)
+      per IAM requirements. Invalid SIDs will throw an error at synthesis time.
+
+      When disabled, no SID validation occurs, maintaining backward compatibility with existing code
+      that may use invalid SID characters.`,
+    introducedIn: { v2: 'V2NEXT' },
+    recommendedValue: true,
+  },
+
   //////////////////////////////////////////////////////////////////////
   [ENABLE_ADDITIONAL_METADATA_COLLECTION]: {
     type: FlagType.VisibleContext,