Skip to main content

Getting Started

The easiest way to get started with IAM Zero is to run it locally on your own computer.


We don't yet host releases of IAM Zero but you can build the CLI from source. You'll need the following tools installed:

Please note that the main branch in this repository is currently under active development and should be considered unstable. We run the git checkout v0.2.0 command below to check out the latest tested and working version.

Follow these steps to compile IAM Zero locally:

git clone
cd iamzero/web
git checkout v0.2.0
yarn install --frozen-lockfile
yarn build
cd ..
go build -o bin/iamzero cmd/main.go

A binary will be created at bin/iamzero, relative to the folder that you cloned the repository to.

Finally, make sure that the iamzero binary is available on your PATH. This process will differ depending on your operating system.

Print a list of locations in your PATH.

echo $PATH

Move the IAM Zero binary to one of the listed locations. The below command assumes that your PATH includes /usr/local/bin/, but you can change this if the locations are different.

mv bin/iamzero /usr/local/bin/

Verify the Installation#

Verify that the installation worked by opening a new terminal session and running iamzero.


You should receive an output similar to below:

iamzero [flags] <subcommand> [flags] [<arg>...]
local Run a local iamzero server
server Start an iamzero server (for server usage)
-v false log verbose output
flag: help requested

Running the console#

Run the console locally with the following command:

iamzero local

A new tab should open in your web browser with the IAM Zero Console:

IAM Zero Console

Help - the IAM Zero Console didn't open automatically for me!

Manually launching the IAM Zero Console#

If your web browser does not automatically launch, visit http://localhost:9090 in a new tab. You will be prompted with a login screen similar to below:

IAM Zero Login

The iamzero local command will have automatically generated an authentication token for you. This is saved to your home directory in MacOS or Linux systems as ~/.iamzero.ini.

To retrieve the token, run the command

cat ~/.iamzero.ini

You should see an output similar to below.

token = 172db0070b6576f33b06eeab9a6eff70
url = http://localhost:9090

Copy the token string and paste it into the input on the login page in your web browser. You should now be able to access the IAM Zero Console.

If you are running a Windows operating system or you cannot find your token please ask for help on our Slack

Sending a permissions alert to IAM Zero#

Creating an AWS user#


The below section will create an IAM user in your AWS account. If you have a different identity management setup (for example, if you use AWS SSO or IAM roles rather than user accounts) you may read through this section and then implement your own IAM roles accordingly to test IAM Zero.

The important thing for testing is that you have created a role which has no IAM policy or permissions, so that we can capture permissions errors when the role is used to start quickly building a least-privilege access policy.

You will need administrator access to an AWS account with the ability to create IAM users to complete this section.

Sign in to the AWS Console. Once you are logged in, visit the link below:$new?step=tags&accessKey&userNames=iamzero-test-user

You'll see a screen similar to below.

The AWS IAM console showing the &quot;create a user&quot; step

Click the "Next: Permissions" button to proceed. Don't add any permissions here as we will use IAM Zero to build permissions instead. Complete the wizard and then copy the AWS CLI credentials to your ~/.aws/credentials file:





You can find more details on configuring your AWS CLI here.

Run the example script#

To get up and running quickly with building least-privilege policies we've created an example script which uses IAM Zero. The script uses boto3, the AWS Python Software Development Kit (SDK), to create an S3 bucket.

We'll run the script as the iamzero-test AWS user created above, which has zero AWS permissions. By using IAM Zero, every time we try and make a call to an AWS resource we'll instantly get a recommendation to build a least-privilege policy.

First, clone the repository:

git clone
cd iamzero-python-example

The script we will run is You can inspect it in your code editor to see how IAM Zero is loaded and used. The important two lines in the script are:

import iamzero

Which does all of the configuration and initialisation of IAM Zero for you.

We need to install some Python dependencies - the iamzero Python client as well as boto3. Run the script in the repository which creates a virtual environment with these installed, accepting the creation of a virtual environment when prompted.


Ensure that we use the iamzero-test user by setting our environment variable as follows:

export AWS_PROFILE=iamzero-test

If you saved your AWS credentials from the previous step to a different profile name, you'll need to change the above command to match your customised name.

Finally, run the script:

source .venv/bin/activate

The Python script should output an error similar to below:

botocore.exceptions.ClientError: An error occurred (AccessDenied) when calling the CreateBucket operation: Access Denied

Open the local IAM Zero console. You should see a new alert similar to below.

The IAM Zero console showing an S3:CreateBucket permission error

You can view the alert details which will show you more information.

The IAM Zero console showing alert details for a S3:CreateBucket permission error


You'll see that there is an "Apply" button to create the IAM policy. This currently works but is not yet properly documented. If you want to apply the alert you'll need to ensure that the environment you are running the iamzero local command in has permission to create IAM policies. We're actively working on ways to better control IAM policy generation and would appreciate any feedback on this GitHub issue.

Clean up#

Visit the AWS IAM console and remove the test user that you created.

To stop running IAM Zero locally, simply close the terminal window running the iamzero local command.

Try it in your own applications and scripts#

Now that you've got IAM Zero up and running, follow the instructions in the Usage section for details on how to capture permissions issues in your own applications.