iam-collect

Get every possible policy in any set of AWS accounts. This is built to run out of the box in simple use cases, and also work in terribly oppressive environments with a little more configuration. If you want to analyze IAM data at scale this is what you've been looking for.

Table of Contents

1. Tenets
2. Introduction
3. Getting Started
4. Using Your Data
5. Configuration
6. Authentication
7. Storage
8. Filtering
9. Indexing
10. CLI
11. History
12. Supported Services and Data
13. Using AWS Config as a Data Source

iam-collect Tenets

1. Centralized Store all your data across all partitions, organizations, accounts, and regions in one place. This is a single source of truth for all your IAM data.
2. Easy A few commands and you can get started and everything should just work. If resources no longer exist, data is cleaned up automatically.
3. Configurable Store your data on disk or in S3. You can configure exactly what accounts, regions, and services you want to collect data for; and customize auth for each.

Introduction

What is iam-collect?

iam-collect is a command-line tool that aggregates every IAM-related resource and policy across any number of AWS accounts, regions, and partitions into a single, consistent dataset. It requires minimal setup for simple use cases and allows flexible configuration to operate in even the most restrictive (compliance oriented) environments to give you a single source of truth for your IAM data.

Why use it?

• Centralized store: Consolidate IAM data from multiple partitions, organizations, and accounts into one structured store.
• Get everything: Collect all the polices from all the resources in all your accounts. Terraform will show you what was intended, iam-collect will show you what is actually there.
• Audit and compliance: Generate comprehensive snapshots of your IAM landscape to support security reviews, audits, and forensics. The structured approach to storage makes it easy to build automation and tooling around the data.

How it works at a glance

Every time you run iam-collect download it will:

1. Scan: Connect to AWS account(s) using your configured credentials or roles and retrieve IAM resources (users, roles, policies, etc.) from each target account.
2. Store: Persist the data to your chosen storage (local filesystem or S3), organizing it by partition, account, service, and resource.
3. Index: Build search-friendly JSON indexes that map resources to accounts and other relationships for fast lookups.

Then you use the data to analyze your IAM landscape, build reports, or integrate with other tools.

Getting Started

By default, iam-collect will use the credentials configured in your environment using the default credential chain. If you have the permissions in the SID CollectIAMData in the example policy everything will work for the current account you have credentials for.

You don't need the AWS CLI, but a good way to make sure your credentials are configured is to ensure you can run aws sts get-caller-identity and a command that requires a region be set such as aws ec2 describe-instances.

npm install -g @cloud-copilot/iam-collect
# Create a default configuration file
iam-collect init
# Download iam data from the current account to `./iam-data`
iam-collect download

Install

You need Node.js >= 20.

npm install -g @cloud-copilot/iam-collect

Initialize

iam-collect init

This will create a file called iam-collect.jsonc in the current directory with a simple default configuration and many comments on how to customize the configuration.

Download

iam-collect download

This will download the IAM data from the current account to the ./iam-data directory. You can change the output directory by modifying the storage.path property in the configuration. See the storage docs for more details.

Enjoy

ls -R ./iam-data

This will show you your data that was downloaded. See the storage docs for more details on the layout of the data.

Additional Docs

• Configuration - Set the configuration files to use.
• Authentication - Configure authentication for different accounts, services, and regions.
• Storage - Configure where your data is stored.
• Filtering - Configure what accounts, services, and regions are downloaded.
• Indexing - Disable or manually run indexing.
• CLI - Details on the CLI commands and options.
• History - How to track history of changes.

Using Your Data

iam-lens

To explore effective access in your environment check out iam-lens. iam-lens reads your iam-collect data to answer questions like: "Who can access this resource?", "Who can assume this role?", and "Does this principal have access to this bucket?"

Leveraging Your AI

Use AgentInstructions.md to help your AI understand the data and how to interrogate it.

curl -O https://raw.githubusercontent.com/cloud-copilot/iam-collect/main/docs/AgentInstructions.md

Then you can start asking questions like "Using AgentInstructions.md as context...":

• Do I have any roles that have "*" in the trust policy?
• Which users have the "AdministratorAccess" managed policy attached?
• What RAM shares are sharing resources outside of my organization?
• Are there any S3 buckets without block public access enabled?

You can also ask your AI to generate scripts to predictably and scalably answer these same questions for you.

Additional Data Sources

By default, iam-collect collects data directly from AWS service APIs.

If you prefer, you can configure iam-collect to pull data from AWS Config instead. See the AWS Config data source documentation for details.

Supported Services and Data

Service	Resource Type	Data Downloaded
iam	Users	name, path, id, groups, tags, inline policies, managed policies, permission boundary
iam	Groups	name, path, id, inline policies, managed policies
iam	Roles	name, path, id, trust policy, inline policies, managed policies, instance profiles, tags (excluded by default), permission boundary
iam	Customer and AWS Managed Policies	name, path, id, default version, default version doc, tags
iam	OIDC Providers	audiences, thumbprints, url, tags
iam	SAML Providers	metadata document, uuid, private keys, valid until, tags
iam	Instance Profiles	name, roles, id, path, tags
apigateway	Rest APIs	id, name, policy, tags
backup	Backup Vaults	name, key, tags, policy
dynamodb	Streams	name, region, resource policy
dynamodb	Tables	name, region, tags, resource policy
ecr	Repositories	name, region, tags, resource policy, key id
ecr	Registries	policy
ec2	VPC Endpoints	id, name, type, vpc, policy
elasticfilesystem	File Systems	name, id, key, encryption, tags, policy
es	OpenSearch Domains	name, policy, tags, KMS key id
events	Event Buses	name, key id, policy, tags
glacier	Vaults	name, region, tags, policy
glue	Root Catalogs	policy
kafka	MSK Clusters	name, policy, kms key, tags
kinesis	Data Streams	name, encryption type, key id, policy, tags
kms	Keys	id, policy, tags
lambda	Functions	name, role, tags, policy
lambda	Layer Versions	name, version, policy
ram	Shared Resources	resource shares, resource policy
s3	Access Points	name, bucket, bucket account, policy, block public access configuration, network origin, vpc, alias, endpoints
s3	Buckets	name, region, tags, policy, block public access configuration, default encryption
s3	Multi Region Access Points	name, alias, regions, policy, block public access configuration
s3-object-lambda	Object Lambda Access Points	name, alias, policy, block public access configuration
s3express	Directory Buckets	name, encryption settings, policy
s3express	Directory Bucket Access Points	name, bucket, bucket account, policy, block public access configuration, network origin, vpc, alias, endpoints
s3outposts	Outpost Buckets	name, region, tags, policy
s3outposts	Outpost Access Points	name, bucket, bucket account, policy, network origin, vpc
s3tables	Table Buckets	name, region, bucket policy, encryption
organizations	Organizations	id, root account id, enabled policy types, org structure, delegated administrators
organizations	Organizational Units	id, parent ou, enabled SCPs, enabled RCPs, tags
organizations	Accounts	id, parent ou, enabled SCPs, enabled RCPs, tags
organizations	SCPs, RCPs	id, name, description, tags, policy
sns	Topics	name, tags, kms key id, policy
sqs	Queues	name, tags, kms key id, policy
secretsmanager	Secrets	name, tags, kms key id, policy
sso	Instances	id, name, owner account id, status, tags
sso	Permission Sets	name, description, AWS managed policies, customer managed policies, inline policy, permission boundary, accounts, tags

If you don't see the data you are looking for, please check the open resource issues and comment on the issue or create a new one.