Visibility in IAM in and across AWS accounts
npm install @cloud-copilot/iam-lens   
Get visibility into the IAM permissions in your AWS organizations and accounts. Use your actual AWS IAM policies (downloaded via iam-collect) and evaluate the effective permissions.
1. Quick Start
2. What is iam-lens?
3. Why use it?
4. Getting Started
5. Commands
- simulate - Simulate a request
- who-can - Find who can perform an action on a resource
- principal-can - Get a consolidated policy of all permissions for a principal
- Global CLI Options
6. Contributing & Support
7. Acknowledgements
``bashInstall
npm install -g @cloud-copilot/iam-collect @cloud-copilot/iam-lens
What is iam-lens?
iam-lens lets you simulate and audit real IAM requests against your collected IAM data from your AWS accounts (collected via iam-collect) and understand the effective permissions that apply to a principal or resource.
Why use it?
- Understand the permissions that are actually in place.
- Verify allowed and denied outcomes after all policies are deployed.
- Discover every principal that can access a given resource.
- Audit complex policy combinations across all your AWS accounts and orgs.
- Debug complex conditions locally without deployment or network calls.
Getting Started
1. Download Your Policies with iam-collect to get all policies from your AWS accounts. iam-collect is highly configurable and can be customized to collect the policies you need. It only downloads information to your file system or an S3 bucket, so you're in full control of your data.
bash
npm install -g @cloud-copilot/iam-collect
iam-collect init
iam-collect download
`To see the effect of SCPs and RCPs, you should download data from your management account; or an account with permission to download organization information. Download data for member accounts you want to analyze.
will analyze cross-account and cross-organization requests if the data is available.You can download information for as many accounts, organizations, and regions as you like. The more data you have, the more accurate your answers will be.
2. Install iam-lens
`bash
npm install -g @cloud-copilot/iam-lens
`3. Execute Commands with
to simulate requests, discover permissions, and audit your IAM policies.Simulate a request:
`bash
iam-lens simulate \
--principal arn:aws:iam::123456789012:role/ExampleRole \
--resource arn:aws:s3:::example-bucket/secret-file.txt \
--action s3:GetObject
`or
Discover who can perform an action on a resource:
bash
iam-lens who-can \
--resource arn:aws:iam::111111111111:role/ImportantRole \
--actions sts:AssumeRole iam:PassRole
`Commands
$3
Evaluates whether a principal can perform a specified action on a resource (or account for wildcard only actions). Returns a decision:
, ImplicitlyDenied, or ExplicitlyDenied. All condition keys are supported and many context keys are set automatically.`bash
Simple simulate: can this role list objects in the bucket?
iam-lens simulate \
--principal arn:aws:iam::111111111111:role/MyRole \
--resource arn:aws:s3:::my-bucket \
--action s3:ListBucketSimulate a wildcard action (ListAllMyBuckets) – this will assume the principals account
iam-lens simulate \
--principal arn:aws:iam::222222222222:user/Alice \
--action s3:ListAllMyBucketsInclude custom context keys
iam-lens simulate \
--principal arn:aws:iam::333333333333:role/DevRole \
--resource arn:aws:sqs:us-east-1:333333333333:my-queue \
--action sqs:SendMessage \
--context aws:SourceVpc vpc-1234567890abcdef0 \
--verboseAssert the result must be “Allowed”; exit code will be nonzero if not
iam-lens simulate \
--principal arn:aws:iam::444444444444:role/ReadOnly \
--resource arn:aws:dynamodb:us-east-1:444444444444:table/Books \
--action dynamodb:Query \
--expect Allowed
`$3
bash
iam-lens who-can [options]
`Lists all principals in your IAM data who are allowed to perform one or more specified actions on a resource (or account for wildcard only actions). If applicable it will check the resource policy to find cross-account permissions and AWS service principals.
Examples:
bash
Who can get this object?
iam-lens who-can \
--resource arn:aws:s3:::my-bucket/secret-file.txt \
--actions s3:GetObjectWho can list all IAM roles in this account? (wildcard action – no resource)
iam-lens who-can \
--resource-account 555555555555 \
--actions iam:ListRolesCheck multiple actions at once
iam-lens who-can \
--resource arn:aws:dynamodb:us-east-1:555555555555:table/Books \
--actions dynamodb:Query dynamodb:UpdateItemCheck all actions for a bucket
iam-lens who-can \
--resource arn:aws:s3:::my-bucket
`$3
bash
iam-lens principal-can --principal [--shrink-action-lists]
`Creates a consolidated policy document showing all permissions that a principal can perform based on their identity policies, permission boundaries, SCPs, RCPs, and resource policies. The output is a synthesized IAM policy representing the effective permissions after all policy evaluations.
Full principal-can documentation
Examples:
bash
Get all permissions for a user or role
iam-lens principal-can \
--principal arn:aws:iam::123456789012:user/AliceGet permissions for a role with shrunk action lists
iam-lens principal-can \
--principal arn:aws:iam::123456789012:role/MyRole \
--shrink-action-lists
``Full principal-can documentation
The best way to support is to open an issue and let us know of any bugs, feature requests, or questions you have. We're always looking for ways to improve the project and make it more useful for everyone.
Special thanks to Ziyad Almbasher for testing, validating, providing feedback, and for not letting up when the author thinks "this is fine".