DEV Community

Cover image for Cloudsplaining - AWS IAM Security Assessment Tool
NaveenKumar Namachivayam ⚡ for AWS Community Builders

Posted on • Originally published at

Cloudsplaining - AWS IAM Security Assessment Tool

Security is everyone's responsibility. In all the phases of the software lifecycle, security is inevitable. If your application or service is built on cloud-native, then security is responsible between you and the cloud providers. This shared model is often known as the Shared Responsibility Model in the AWS ecosystem, Shared Responsibility Matrix in Google Cloud Platform, and Azure's Shared responsibility in the cloud. Cloudsplaining is a utility for AWS IAM where it assesses the IAM policies and generates an HTML report for further actions. It is an open source initiative from Salesforce. In this blog post, we will deep-dive into Cloudsplaining, how to get started, generate an HTML report, and more.

What is Cloudsplaining?

Cloudsplaining is a Python based utility to assess the AWS IAM policies and identifies violations of the least privileges. It generates a simple HTML report once the scanning is performed along with a triage sheet.

It supports scanning all the policies in a single AWS account, a single policy in an AWS account, or you could scan multiple AWS accounts.

It is an open source contribution from Salesforce.

How to install Cloudsplaining?

The only prerequisite to installing Cloudsplaining is to have the latest version of Python.

To install Cloudsplaining on Mac:

brew tap salesforce/cloudsplaining
brew install cloudsplaining

To install Cloudsplaining on Windows or Linux, leverage pip:

pip3 install --user cloudsplaining

To validate the installation, enter:

cloudsplaining --version

If you are getting command not found, make sure you add the cloudsplaining path to PATH variable using export PATH=$PATH:/home/<user_name>/.local/bin

For auto complete in bash, add the below line to .bashrc

eval "$(_CLOUDSPLAINING_COMPLETE=source cloudsplaining)"

For auto complete in zsh, add the below line to .zshrc

eval "$(_CLOUDSPLAINING_COMPLETE=source_zsh cloudsplaining)"

Getting Started with Cloudsplaining

Before using Cloudsplaining utility, make sure you have the following AWS setup. Cloudsplaining leverages get-account-authorization-details AWS API to scan the IAM policies to identify the potential issues.

To begin scanning, the first step is to download the account authorization details using cloudsplaining download

The above command downloads the account details in the format of JSON and keeps them in the present directory.

Cloudsplaining - AWS IAM Security Assessment Tool
Cloudsplaining - AWS IAM Security Assessment Tool

If you open the JSON using your favorite editor, you can find all the IAM policies, ARN, path, role name, role ID, and more.

After downloading the account details, it is time to perform our first scan. As most of us will have only one AWS account, let us see how to scan a single AWS account. But cloudsplaining supports scanning multiple AWS accounts.

Create an empty directory to store the HTML report output using the below command.

mkdir report

Then, issue the below command.

cloudsplaining scan --input-file default.json --output report

Once the scan is successful, you could find the below artifacts inside report folder.

Cloudsplaining Report
Cloudsplaining Report

Open the HTML report in your favorite browser.

HTML Report
HTML Report

Here is the sample report for your analysis.

Generating reports is easy and simple. But understanding the report takes experience and time. Let us try to understand the high level context of the report.

Understanding the Cloudsplaining Report

The home page of Cloudsplaining report will have an executive summary which often lists out the risks in IAM policies such as

  • Privilege Escalation
  • Resource Exposure
  • Infrastructure Modification
  • Data Exfiltration

It also displays the graphical view and the classification with severity, risk, and instances. The below table helps to identify potential threats and reduces the vulnerability radius.

IAM Risks
IAM Risks

At the top of the report, you can find links to the following:

  • Customer Policies
  • Inline Policies
  • AWS Policies
  • IAM Principals
  • Guidance
  • Appendices

The Customer Policies page displays the list of the policies which you or your team created either manually or via automation. It will also display the policy document, scan findings such as Privilege Escalation, Resource Exposure, Infrastructure Modification, Data Exfiltration, and more for each policy, how to fix it, false positives and more.

Customer Policies
Customer Policies

Privilege Escalation Methods
Privilege Escalation Methods

Inline Policy page displays the details about all the inline policies, scan findings as Customer Policies.

Inline Policy
Inline Policy

The AWS Policies page will display all the policies which are created by AWS and its scan findings.

The IAM Principles page will display all the roles, users, groups, associated policies, and the risks associated and other metadata.

IAM Principles
IAM Principles

Guidance page will help you out with triaging and deep-dive into understanding the report. Also, it will help you out with common false positive scenarios, remediation, and validation.

The Appendices page will list out all the glossary.

Understanding the High Priority Tasks

Now let us try to understand the high priority tasks from the report.

Privilege Escalation

Privilege Escalation is one of the common techniques for gaining access. The hackers might start with small and step-by-step they escalate themselves to high privilege access. More details here.

Resource Exposure

By leveraging resource based policies, the bad actor can expose AWS resources to the public. e.g. s3:PutObjectAcl allows the actors to modify the access control list for new or existing objects in S3.

Infrastructure Modification

From the term itself, it is easy to guess. The IAM actions allow the resource to create, modify or delete. The bad actor can bring down the resources or spin up powerful EC2 instances for crypto mining purposes.

Data Exfiltration

Data Exfiltration is a type of security breach where the bad actor transfers sensitive data from AWS to their premise. e.g. s3:GetObject without any resource constraint can lead to data exfiltration breach.

Service Wildcard

* wildcard is bad. * grants all the actions in IAM. Service wildcards will lead to high risks in your AWS account.

Credentials Exposure

Some actions such as codepipeline:pollforjobs, iam:createaccesskey, sts:assumerole, and more will expose the credentials in its response. Keep an eye on it to reduce the risks.

Roles Assumable by Compute Services

IAM service roles can impose greater risk than user-defined roles, particularly when resources are exposed to the public.


Cloudsplaining is a great Python utility to identify the risks associated via IAM policies, roles, and more. Cloudsplaining triage worksheet helps to tune the policies, principals, roles by intuitive table along with IAM metadata. Also, it supports scanning multiple AWS accounts, exclusions to eliminate false positives, scanning single or multiple policies and more. It also supports Jira ticket automation, and you can use it along with Policy Sentry - a preventative tool to write secured IAM policies.

Top comments (0)