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.
- Quick Start
- What is iam-lens?
- Why use it?
- Getting Started
- Commands
- Contributing & Support
- Acknowledgements
# Install
npm install -g @cloud-copilot/iam-collect @cloud-copilot/iam-lens
# Download all IAM policies in your account using default credentials, run download once per account
iam-collect init
iam-collect download
# Simulate a request
iam-lens simulate --principal arn:aws:iam::123456789012:role/ExampleRole --resource arn:aws:s3:::example-bucket/secret-file.txt --action s3:GetObject
# Find out who can do something
iam-lens who-can --resource arn:aws:s3:::example-bucket --actions s3:ListBucket
# Find out who can do all actions on a resource
iam-lens who-can --resource arn:aws:s3:::example-bucketiam-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.
- 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.
- 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.
npm install -g @cloud-copilot/iam-collect
iam-collect init
iam-collect downloadTo 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. iam-lens 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.
- Install iam-lens
npm install -g @cloud-copilot/iam-lens- Execute Commands with
iam-lensto simulate requests, discover permissions, and audit your IAM policies.
Simulate a request:
iam-lens simulate \
--principal arn:aws:iam::123456789012:role/ExampleRole \
--resource arn:aws:s3:::example-bucket/secret-file.txt \
--action s3:GetObjector
Discover who can perform an action on a resource:
iam-lens who-can \
--resource arn:aws:iam::111111111111:role/ImportantRole \
--actions sts:AssumeRole iam:PassRoleEvaluates whether a principal can perform a specified action on a resource (or account for wildcard only actions). Returns a decision: Allowed, ImplicitlyDenied, or ExplicitlyDenied. All condition keys are supported and many context keys are set automatically.
# 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:ListBucket
# Simulate a wildcard action (ListAllMyBuckets) – this will assume the principals account
iam-lens simulate \
--principal arn:aws:iam::222222222222:user/Alice \
--action s3:ListAllMyBuckets
# Include 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 \
--verbose
# Assert 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 Allowediam-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:
# Who can get this object?
iam-lens who-can \
--resource arn:aws:s3:::my-bucket/secret-file.txt \
--actions s3:GetObject
# Who can list all IAM roles in this account? (wildcard action – no resource)
iam-lens who-can \
--resource-account 555555555555 \
--actions iam:ListRoles
# Check multiple actions at once
iam-lens who-can \
--resource arn:aws:dynamodb:us-east-1:555555555555:table/Books \
--actions dynamodb:Query dynamodb:UpdateItem
# Check all actions for a bucket
iam-lens who-can \
--resource arn:aws:s3:::my-bucketThe 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".