Getting Started
The easiest way to get started with IAM Zero is to run it locally on your own computer.
Installation#
- 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 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.
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:
Running the console#
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!
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:
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
You should see an output similar to below.
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#
info
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:
https://console.aws.amazon.com/iam/home#/users$new?step=tags&accessKey&userNames=iamzero-test-user
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 ~/.aws/credentials file:
~/.aws/credentials
~/.aws/config
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:
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:
note
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.
warning
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.