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 https://github.com/salesforce/cloudsplaining brew install cloudsplaining
To install Cloudsplaining on Windows or Linux, leverage
pip3 install --user cloudsplaining
To validate the installation, enter:
If you are getting
command not found, make sure you add the cloudsplaining path to
PATH variable using
For auto complete in bash, add the below line to
eval "$(_CLOUDSPLAINING_COMPLETE=source cloudsplaining)"
For auto complete in zsh, add the below line to
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.
- You must have AWS credentials configured. Check AWS CLI v2 for more details.
- Privileges to run GetAccountAuthorizationDetails
To begin scanning, the first step is to download the account authorization details using
The above command downloads the account details in the format of JSON and keeps them in the present directory.
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.
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
Open the HTML report in your favorite browser.
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.
At the top of the report, you can find links to the following:
- Customer Policies
- Inline Policies
- AWS Policies
- IAM Principals
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.
Inline Policy page displays the details about all the inline policies, scan findings as Customer Policies.
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.
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 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.
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.
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 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.
* wildcard is bad. * grants all the actions in IAM. Service wildcards will lead to high risks in your AWS account.
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.