{"id":35177095,"url":"https://github.com/cloud-copilot/iam-lens","last_synced_at":"2026-05-30T14:00:45.531Z","repository":{"id":293903891,"uuid":"985470263","full_name":"cloud-copilot/iam-lens","owner":"cloud-copilot","description":"Google Maps for AWS IAM","archived":false,"fork":false,"pushed_at":"2026-05-23T12:39:28.000Z","size":2111,"stargazers_count":274,"open_issues_count":11,"forks_count":19,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-05-23T14:23:08.637Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloud-copilot.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-17T20:40:25.000Z","updated_at":"2026-05-23T12:39:30.000Z","dependencies_parsed_at":"2026-01-04T09:02:43.151Z","dependency_job_id":null,"html_url":"https://github.com/cloud-copilot/iam-lens","commit_stats":null,"previous_names":["cloud-copilot/iam-lens"],"tags_count":127,"template":false,"template_full_name":null,"purl":"pkg:github/cloud-copilot/iam-lens","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-copilot%2Fiam-lens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-copilot%2Fiam-lens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-copilot%2Fiam-lens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-copilot%2Fiam-lens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloud-copilot","download_url":"https://codeload.github.com/cloud-copilot/iam-lens/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-copilot%2Fiam-lens/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33694714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-28T22:59:51.288Z","updated_at":"2026-05-30T14:00:45.525Z","avatar_url":"https://github.com/cloud-copilot.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# iam-lens\n\n[![NPM Version](https://img.shields.io/npm/v/@cloud-copilot/iam-lens.svg?logo=nodedotjs)](https://www.npmjs.com/package/@cloud-copilot/iam-lens) [![License: AGPL v3](https://img.shields.io/github/license/cloud-copilot/iam-lens)](LICENSE.txt) [![GuardDog](https://github.com/cloud-copilot/iam-lens/actions/workflows/guarddog.yml/badge.svg)](https://github.com/cloud-copilot/iam-lens/actions/workflows/guarddog.yml) [![Known Vulnerabilities](https://snyk.io/test/github/cloud-copilot/iam-lens/badge.svg?targetFile=package.json\u0026style=flat-square)](https://snyk.io/test/github/cloud-copilot/iam-lens?targetFile=package.json)\n\nGet visibility into the IAM permissions in your AWS organizations and accounts. Use your actual AWS IAM policies (downloaded via [iam-collect](https://github.com/cloud-copilot/iam-collect)) and evaluate the effective permissions.\n\n## Table of Contents\n\n1. [Quick Start](#quick-start)\n2. [What is iam-lens?](#what-is-iam-lens)\n3. [Why use it?](#why-use-it)\n4. [Getting Started](#getting-started)\n5. [Commands](#commands)\n   - [simulate - Simulate a request](docs/Simulate.md)\n   - [who-can - Find who can perform an action on a resource](docs/WhoCan.md)\n   - [principal-can - Get a consolidated policy of all permissions for a principal](docs/PrincipalCan.md)\n   - [Global CLI Options](docs/GlobalCliOptions.md)\n6. [Contributing \u0026 Support](#contributing--support)\n7. [Acknowledgements](#acknowledgements)\n\n## Quick Start\n\n```bash\n# Install\nnpm install -g @cloud-copilot/iam-collect @cloud-copilot/iam-lens\n\n# Download all IAM policies in your account using default credentials, run download once per account\niam-collect init\niam-collect download\n\n# Simulate a request\niam-lens simulate --principal arn:aws:iam::123456789012:role/ExampleRole --resource arn:aws:s3:::example-bucket/secret-file.txt --action s3:GetObject\n\n# Find out who can do something\niam-lens who-can --resource arn:aws:s3:::example-bucket --actions s3:ListBucket\n\n# Find out who can do all actions on a resource\niam-lens who-can --resource arn:aws:s3:::example-bucket\n```\n\n## What is iam-lens?\n\n**iam-lens** lets you **simulate** and **audit** real IAM requests against your collected IAM data from your AWS accounts (collected via [iam-collect](https://github.com/cloud-copilot/iam-collect)) and understand the effective permissions that apply to a principal or resource.\n\n## Why use it?\n\n- **Understand** the permissions that are actually in place.\n- **Verify** allowed and denied outcomes after all policies are deployed.\n- **Discover** every principal that can access a given resource.\n- **Audit** complex policy combinations across all your AWS accounts and orgs.\n- **Debug** complex conditions locally without deployment or network calls.\n\n## Getting Started\n\n1. **Download Your Policies** with [iam-collect](https://github.com/cloud-copilot/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.\n\n```bash\nnpm install -g @cloud-copilot/iam-collect\niam-collect init\niam-collect download\n```\n\nTo 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.\n\nYou 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.\n\n2. **Install iam-lens**\n\n```bash\nnpm install -g @cloud-copilot/iam-lens\n```\n\n3. **Execute Commands** with `iam-lens` to simulate requests, discover permissions, and audit your IAM policies.\n\nSimulate a request:\n\n```bash\niam-lens simulate \\\n  --principal arn:aws:iam::123456789012:role/ExampleRole \\\n  --resource arn:aws:s3:::example-bucket/secret-file.txt \\\n  --action s3:GetObject\n```\n\nor\n\nDiscover who can perform an action on a resource:\n\n```bash\niam-lens who-can \\\n  --resource arn:aws:iam::111111111111:role/ImportantRole \\\n  --actions sts:AssumeRole iam:PassRole\n```\n\n## Commands\n\n### `simulate` - Simulate a request\n\nEvaluates 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](docs/Simulate.md#context-keys) are supported and [many context keys are set automatically](docs/Simulate.md#default-context-keys).\n\n[Full simulate documentation](docs/Simulate.md)\n\n```bash\n# Simple simulate: can this role list objects in the bucket?\niam-lens simulate \\\n  --principal arn:aws:iam::111111111111:role/MyRole \\\n  --resource arn:aws:s3:::my-bucket \\\n  --action s3:ListBucket\n\n# Simulate a wildcard action (ListAllMyBuckets) – this will assume the principals account\niam-lens simulate \\\n  --principal arn:aws:iam::222222222222:user/Alice \\\n  --action s3:ListAllMyBuckets\n\n# Include custom context keys\niam-lens simulate \\\n  --principal arn:aws:iam::333333333333:role/DevRole \\\n  --resource arn:aws:sqs:us-east-1:333333333333:my-queue \\\n  --action sqs:SendMessage \\\n  --context aws:SourceVpc vpc-1234567890abcdef0 \\\n  --verbose\n\n# Assert the result must be “Allowed”; exit code will be nonzero if not\niam-lens simulate \\\n  --principal arn:aws:iam::444444444444:role/ReadOnly \\\n  --resource arn:aws:dynamodb:us-east-1:444444444444:table/Books \\\n  --action dynamodb:Query \\\n  --expect Allowed\n```\n\n[Full simulate documentation](docs/Simulate.md)\n\n### `who-can` - Find who can perform an action on a resource\n\n```bash\niam-lens who-can [options]\n```\n\nLists 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.\n\n[Full who-can documentation](docs/WhoCan.md)\n\n**Examples:**\n\n```bash\n# Who can get this object?\niam-lens who-can \\\n  --resource arn:aws:s3:::my-bucket/secret-file.txt \\\n  --actions s3:GetObject\n\n# Who can list all IAM roles in this account? (wildcard action – no resource)\niam-lens who-can \\\n  --resource-account 555555555555 \\\n  --actions iam:ListRoles\n\n# Check multiple actions at once\niam-lens who-can \\\n  --resource arn:aws:dynamodb:us-east-1:555555555555:table/Books \\\n  --actions dynamodb:Query dynamodb:UpdateItem\n\n# Check a wildcard resource prefix and inspect allowed patterns\niam-lens who-can \\\n  --resource arn:aws:s3:::my-bucket/reports/* \\\n  --actions s3:GetObject\n\n# Check all actions for a bucket\niam-lens who-can \\\n  --resource arn:aws:s3:::my-bucket\n```\n\n[Full who-can documentation](docs/WhoCan.md)\n\n### `principal-can` - Get a consolidated policy of all permissions for a principal\n\n```bash\niam-lens principal-can --principal \u003carn\u003e [--shrink-action-lists]\n```\n\nCreates 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.\n\n[Full principal-can documentation](docs/PrincipalCan.md)\n\n**Examples:**\n\n```bash\n# Get all permissions for a user or role\niam-lens principal-can \\\n  --principal arn:aws:iam::123456789012:user/Alice\n\n# Get permissions for a role with shrunk action lists\niam-lens principal-can \\\n  --principal arn:aws:iam::123456789012:role/MyRole \\\n  --shrink-action-lists\n```\n\n[Full principal-can documentation](docs/PrincipalCan.md)\n\n## Contributing \u0026 Support\n\nThe best way to support is to [open an issue](https://github.com/cloud-copilot/iam-lens/issues) 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.\n\n## Acknowledgements\n\nSpecial thanks to [Ziyad Almbasher](https://www.linkedin.com/in/ziadmo/) for testing, validating, providing feedback, and for not letting up when the author thinks \"this is fine\".\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-copilot%2Fiam-lens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloud-copilot%2Fiam-lens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-copilot%2Fiam-lens/lists"}