The easiest way to get started with IAM Zero is to run it locally on your own computer.
- Compile from source
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:
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.
- Mac or Linux
Print a list of locations in your
Move the IAM Zero binary to one of the listed locations. The below command assumes that your
/usr/local/bin/, but you can change this if the locations are different.
Verify that the installation worked by opening a new terminal session and running
You should receive an output similar to below:
Run the console locally with the following command:
A new tab should open in your web browser with the IAM Zero Console:
Help - the IAM Zero Console didn't open automatically for me!
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:
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
To retrieve the token, run the command
You should see an output similar to below.
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
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:
You'll see a screen similar to below.
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
You can find more details on configuring your AWS CLI here.
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:
The script we will run is
iamzero_example.py. 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:
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
setup.sh 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:
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:
The Python script should output an error similar to below:
Open the local IAM Zero console. You should see a new alert similar to below.
You can view the alert details which will show you more information.
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.
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.
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.