(cli): Support a least-privilege diff-only IAM role for `cdk diff`
- 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
Assessment
This issue has not been assessed yet.