aws / aws/aws-cdk-cli

(cli): Support a least-privilege diff-only IAM role for `cdk diff`

Open
#1,123 2 comments 4 reactions 0 assignees View on GitHub
aws-cdk effort/medium feature-request p2
Dominant language
TypeScript
Stars
105
Forks
122
Avg merge
1d 17h
Merged PRs (30d)
71

Description

### Describe the feature

There is currently no way to run `cdk diff` using a read-only or least-privilege IAM role when using the AWS CDK CLI.

Even though `cdk diff` is a non-deploying operation, the CLI requires permissions equivalent to deployment roles (including assuming deploy and asset publishing roles). This makes it difficult to use `cdk diff` safely in CI environments.

I am proposing support in the CDK CLI for a diff-only IAM role that allows secure execution of `cdk diff` without granting full deployment capabilities.

### Use Case

In CI pipelines, I want to run `cdk diff` automatically to provide visibility into infrastructure changes without introducing a manual approval gate.

Using a role with deployment-level permissions in CI is risky: if the workflow is modified or compromised, the role could be abused to deploy or modify infrastructure.

Today, there is no secure alternative:
- `cdk diff` creates a CloudFormation change set
- This requires assuming the deploy role
- For stacks with assets, the CLI also attempts to assume file-publishing and image-publishing roles

As a result, it is currently impossible to run `cdk diff` with a read-only or least-privilege role using the CDK CLI, unless one builds a custom diff workflow outside the CLI.

### Proposed Solution

Add first-class support in the CDK CLI for a diff-only role with limited permissions.

Conceptually, this role would:
- Allow creation of CloudFormation change sets
- Explicitly deny `cloudformation:ExecuteChangeSet`
- Allow asset-related actions required for diffing:
- S3 uploads for `Code.fromAsset`
- Optional asset handling only when relevant
- Have no permissions to deploy, update, or delete stacks

Possible implementation approaches:
- Bootstrap an optional `diff-role` alongside existing toolkit roles
- Allow explicitly specifying a diff role via CLI flags (e.g. `cdk diff --role-arn ...`)
- Automatically select a diff role when running `cdk diff`

This would preserve accurate change-set–based diffs while significantly improving security for CI usage.

### Other Information

_No response_

### Acknowledgements

- [ ] I may be able to implement this feature request
- [ ] This feature might incur a breaking change

### CDK version used

2.1105.0

### Environment details (OS name and version, etc.)

Ubuntu 24.04

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.