Skip to main content

​
Prerequisites

Before installing IAM Audit, ensure you have:

Python 3.9+

Modern Python installation required

AWS Organization Access

Credentials for the management account

Audit Role

Read-only IAM role deployed in child accounts

AWS CLI Configured

Named profile for management account
If you’re using AWS Control Tower, the AWSControlTowerExecution role already exists in all accounts and can be used immediately.

​
Installation Steps

1

Clone or Download the Repository

Get the IAM Audit source code:
git clone https://github.com/your-org/iam-audit.git
cd iam-audit
Or download iam_audit.py directly if distributing internally.
2

Install Python Dependencies

Install the AWS SDK for Python:
pip install boto3
Or use the requirements file:
pip install -r requirements.txt
This installs boto3>=1.26.0, which is the only dependency.
3

Verify Python Installation

Confirm Python 3.9+ is available:
python --version
# Should output: Python 3.9.x or higher

​
AWS Credentials Setup

1

Configure AWS CLI Profile

Create a named profile for your AWS Organization management account:
aws configure --profile mgmt-profile
Enter your management account credentials when prompted.
2

Test Organizations Access

Verify you can list accounts:
aws organizations list-accounts --profile mgmt-profile
You should see a JSON response with all accounts in your organization.

​
Permission Requirements

​
Management Account Role

Your management account credentials need: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "organizations:ListAccounts",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "arn:aws:iam::*:role/YOUR-AUDIT-ROLE-NAME"
    }
  ]
}
Replace YOUR-AUDIT-ROLE-NAME with the role name you’ll use in child accounts (e.g., AWSControlTowerExecution or IAMAuditRole).

​
Child Account Role

The audit role in each child account needs these read-only permissions: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:ListUsers",
        "iam:ListAccessKeys",
        "iam:GetAccessKeyLastUsed",
        "iam:ListMFADevices",
        "iam:GetLoginProfile",
        "cloudtrail:LookupEvents"
      ],
      "Resource": "*"
    }
  ]
}
The role must have a trust relationship allowing the management account to assume it:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::MANAGEMENT-ACCOUNT-ID:root"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

​
Verify Installation

Test that IAM Audit is ready to run: 
python iam_audit.py --help
You should see: 
usage: iam_audit.py [-h] --profile PROFILE --role ROLE

IAM Security Audit Tool

optional arguments:
  -h, --help         show this help message and exit
  --profile PROFILE  AWS CLI profile name
  --role ROLE        Role name to assume in each account
If you see this output, installation is complete.

​
Next Steps

Quick Start

Run your first organization-wide IAM audit in 5 minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us