_____          __  __ ______ _           _           
 |_   _|   /\   |  \/  |  ____(_)         | |          
   | |    /  \  | \  / | |__   _ _ __   __| | ___ _ __ 
   | |   / /\ \ | |\/| |  __| | | '_ \ / _` |/ _ \ '__|
  _| |_ / ____ \| |  | | |    | | | | | (_| |  __/ |   
 |_____/_/    \_\_|  |_|_|    |_|_| |_|\__,_|\___|_|   

IAMFinder

IAMFinder enumerates and finds users and IAM roles in a target AWS account. With only the AWS account number of the targeted account, IAMFinder is able to identify users and roles in that environment. Upon successfully identifying an IAM role, IAMFinder can also check if this role can be assumed anonymously. The tool was developed during a red team exercise and it implemented the technique described in this blog. Some features of IAMFinder include:

• Silent. IAMFinder doesn't trigger any alert or leave any log at the target account. Because the enumeration is performed in your accounts, the logs only show up in your accounts. However, the target account will notice if IAMFinder attempts to assume roles.
• High enumeration rate. IAMFinder can achieve a higher enumeration rate by:
  • Concurrently invoking APIs of multiple AWS services (e.g., S3, KMS and IAM) in the account used to perform the test.
  • Concurrently using multiple AWS accounts to perform the test.
• Modularized and extensible. One can implement and integrate additional AWS APIs described in our previous blog on information leakage.
• Cross-partitions. IAMFinder has been tested in all three AWS partitions, AWS Standard (aws), AWS GovCloud U.S. (aws-us-gov), and AWS China (aws-cn).
• Zero cost. The resources that IAMFinder creates in each service don’t have actual workloads and should not incur any costs.

IAMFinder's performace evaluation can be found in this blog.

Prerequisites

IAMFinder is built with Python 3 and AWS Boto3 SDK. An active AWS account and a Python 3.5+ interpreter are needed to run the tool.

• Create an AWS account
• Python3
• Python package manager

AWS credentials

IAMFinder needs an access key or a security token to invoke AWS APIs programmatically. The users or roles that IAMFinder uses need to have necessary permissions to call a set of AWS APIs.

• Create an IAM user access key
• Obtain a security token through AssumeRole

Permissions

The required permissions depend on the AWS services that IAMFinder uses. IAMFinder can work with one or multiple AWS services. Using multiple services concurrently can achieve a higher enumeration rate because AWS API gateway enforces a rate-limit on each API. IAMFinder currently implements the APIs for four AWS services, IAM, S3, SQS, and KMS. These services can be enabled or disabled in the config.json file. AWS_Policy.json contains the minimal set of permissions needed to use all four services. The exact permissions required for each service are as follows:

S3

"s3:PutBucketPublicAccessBlock"
"s3:CreateBucket"
"s3:ListAllMyBuckets"
"s3:PutBucketPolicy"
"s3:GetBucketLocation"
"s3:DeleteBucket"

KMS

"kms:PutKeyPolicy"
"kms:GetKeyPolicy"
"kms:DisableKey"
"kms:ListKeys"
"kms:ScheduleKeyDeletion"
"kms:ListAliases"
"kms:CreateAlias"
"kms:CreateKey"

SQS

"sqs:ListQueues"
"sqs:DeleteQueue"
"sqs:CreateQueue"
"sqs:SetQueueAttributes"

IAM

"iam:UpdateAssumeRolePolicy"
"iam:ListRoles"
"iam:CreateRole"
"iam:DeleteRole"

Note that when more AWS services described in the blog are integrated, the permissions policy will be updated.

• Create an IAM policy
• Create an IAM user
• Create an IAM role

Installation

IAMFinder has only two dependent libraries, boto3 and requests. It is straightforward to run in any platform and environment. We also provide a Dockerfile for users who prefer to run it inside a container.

Install on a host:

git clone https://github.com/prisma-cloud/IAMFinder.git
cd IAMFinder
pip3 install -r requirements.txt

Build a Docker image

git clone https://github.com/prisma-cloud/IAMFinder.git
cd IAMFinder
docker build -t iamfinder .

Configuration

IAMFinder needs a configuration file (config_dir/config.json) and a credential file (config_dir/creds.json) to start.

config.json

{
    "CREDS_PATH": "./config_dir/creds.json",
    "ROLENAMES_FILE_PATH": "./config_dir/rolelist.txt",
    "USERNAMES_FILE_PATH": "./config_dir/userlist.txt",
    "SERVICES_CONFIG":{
        "s3":{
            "enabled": true,
            "resource_type":"s3",
            "resource_prefix":"iamcheckers3",
            "resource_count":3
        },
        "kms":{
            "enabled": true,
            "resource_type":"kms",
            "resource_prefix":"iamcheckerkms",
            "resource_count":3
        },
        "sqs":{
            "enabled": true,
            "resource_type":"sqs",
            "resource_prefix":"iamcheckersqs",
            "resource_count":2
        },
        "iam":{
            "enabled": true,
            "resource_type":"iam",
            "resource_prefix":"iamcheckeriam",
            "resource_count":2
        }
    }
}

Each AWS service can be individually configured in config.json. One can enable or disable a service by toggling the "enabled" field. The "resource_prefix" is an identifier used for naming and locating the resources created in AWS accounts. It should not be changed after the resources have been created with the init command.

creds.json

{
    "account1": {
        "Region": "us-west-1",
        "Active": true,
        "AccessKeyId": "",
        "SecretAccessKey": ""
    },
    "account2": {
        "Region": "us-east-1",
        "Active": false,
        "AccessKeyId": "",
        "SecretAccessKey": ""
    },
    "account3": {
        "Region": "us-east-2",
        "Active": true,
        "AccessKeyId": "",
        "SecretAccessKey": "",
        "SessionToken": ""
    }
}

IAMFinder can use multiple AWS accounts to enumerate identities concurrently. Due to the rate-limit on AWS API gateway, using multiple AWS accounts is the most effective way to boost enumeration rate. Each account can be enabled or disabled by toggling the "Active" field in creds.json. Either a user's access key or security token can be provided for each account.

Usage

usage: iamfinder.py [-h]
                    {init,cleanup,enum_role,enum_user,assu_role,check_awsid}
                    ...

IAMFinder checks for existing users and IAM roles in an AWS account

optional arguments:
  -h, --help            show this help message and exit

subcommand:
  The subcommand to execute

  {init,cleanup,enum_role,enum_user,assu_role,check_awsid}
                        Enter a command to execute
    init                Create aws resoruces necessary for IAMFinder
    cleanup             Remove aws resoruces created by the init command
    enum_role           Check if any role in the role file (default:
                        ./config_dir/rolelist.txt) exists in the target
                        account. Required argument: --aws_id. Optional
                        arguments: --file_path, --aws_part, --assume. If
                        --assume is specified, the scanner will attempt to
                        assume the identified roles
    enum_user           Check if any user in the user file (default:
                        ./config_dir/userlist.txt) exists in the target
                        account. Required argument: --aws_id. Optional
                        arguments: --file_path, --aws_part
    assu_role           Check if any role in the role file (default:
                        ./config_dir/rolelist.txt) can be assumed. Required
                        argument: --aws_id. Optional arguments: --file_path,
                        --aws_part.
    check_awsid         Check if an AWS ID is valid and exist. Required
                        argument: --aws_id. Optional arguments: --aws_part

Initialization

init command creates necessary AWS resources for IAMFinder to perform the test. init only needs to be run once.

python3 iamfinder.py init

Enumerate Identities

Enumerte users in AWS account 123456789012 using the default wordlist ./config_dir/userlist.txt.

python3 iamfinder.py enum_user --aws_id 123456789012

Enumerte IAM roles in AWS account 123456789012 usig wordlist myrolelist.txt

python3 iamfinder.py enum_role --aws_id 987654321098 --file_path ./config_dir/myrolelist.txt

Enumerte IAM roles in aws-us-gov account 987654321098. Note that you need an aws-us-gov account in order to enumerate an aws-us-gov target. Same as aws-cn

python3 iamfinder.py enum_role --aws_id 987654321098 --aws_part aws-us-gov

Check if 135792468100 is a valid account in aws-cn partition. check_awsid can be performed without an active AWS account and init process.

python3 iamfinder.py check_awsid --aws_id 135792468100 --aws_part aws-cn

Delete all the AWS resources created by init command.

python3 iamfinder.py cleanup

Run in Docker

Place the config and credential files in config_dir and mount this directory to the container.

docker run --rm -it -v [absolute path to config_dir]:/home/iamuser/config_dir/ iamfinder [command]

Examples:

docker run --rm -it -v /home/user0/projects/IAMFinder/:/home/iamuser/config_dir/ iamfinder init

docker run --rm -it -v /home/user0/projects/IAMFinder/:/home/iamuser/config_dir/ iamfinder enum_user --aws_id 123456789012