As a security tool, salesforce/cloudsplaining has picked up 2.3k stars on GitHub (JavaScript). Cloudsplaining is an AWS IAM Security Assessment tool that identifies violations of least privilege and generates a risk-prioritized report.
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
Cloudsplaining is an AWS IAM Security Assessment tool that identifies violations of least privilege and generates a risk-prioritized HTML report.
Example report
Documentation
For full documentation, please visit the project on ReadTheDocs.
Installation
Cheatsheet
Example report
Overview
Cloudsplaining identifies violations of least privilege in AWS IAM policies and generates a pretty HTML report. It can scan all the policies in your AWS account, across multiple AWS accounts, or it can scan a single policy file.
It helps to identify IAM actions that do not leverage resource constraints. It also helps prioritize the remediation process by flagging IAM policies that present the following risks to the AWS account in question without restriction:
Data Exfiltration (s3:GetObject, ssm:GetParameter, secretsmanager:GetSecretValue)
Infrastructure Modification
Resource Exposure (the ability to modify resource-based policies)
Privilege Escalation (based on Pathfinding.cloud)
Credentials Exposure
Cloudsplaining also identifies IAM Roles that can be assumed by AWS Compute Services (such as EC2, ECS, EKS, or Lambda), as they can present greater risk than user-defined roles - especially if the AWS Compute service is on an instance that is directly or indirectly exposed to the internet. Flagging these roles is particularly useful to penetration testers (or attackers) under certain scenarios. For example, if an attacker obtains privileges to execute ssm:SendCommand and there are privileged EC2 instances with the SSM agent installed, they can effectively have the privileges of those EC2 instances. Remote Code Execution via AWS Systems Manager Agent was already a known escalation/exploitation path, but Cloudsplaining can make the process of identifying theses cases easier. See the sample report for some examples.
You can also specify a custom exclusions file to filter out results that are False Positives for various reasons. For example, User Policies are permissive by design, whereas System roles are generally more restrictive. You might also have exclusions that are specific to your organization's multi-account strategy or AWS application architecture.
Motivation
Policy Sentry revealed to us that it is possible to finally write IAM policies according to least privilege in a scalable manner. Before Policy Sentry was released, it was too easy to find IAM policy documents that lacked resource constraints. Consider the policy below, which allows the IAM principal (a role or user) to run s3:PutObject on any S3 bucket in the AWS account:
Policy Sentry makes it really easy to do this. Once Infrastructure as Code developers or AWS Administrators gain familiarity with the tool (which is quite easy to use), we've found that adoption starts very quickly. However, if you've been using AWS, there is probably a very large backlog of IAM policies that could use an uplift. If you have hundreds of AWS accounts with dozens of policies in each, how can we lock down those AWS accounts by programmatically identifying the policies that should be fixed?
That's why we wrote Cloudsplaining.
Cloudsplaining identifies violations of least privilege in AWS IAM policies and generates a pretty HTML report. It can scan all the policies in your AWS account, across multiple AWS accounts, or it can scan a single policy file.
Installation
Homebrew
brew tap salesforce/cloudsplaining https://github.com/salesforce/cloudsplaining
brew install cloudsplaining
Pip3
pip3 install --user cloudsplaining
Now you should be able to execute cloudsplaining from command line by running cloudsplaining --help.
Shell completion
To enable Bash completion, put this in your .bashrc:
We can scan an entire AWS account and generate reports. To do this, we leverage the AWS IAM get-account-authorization-details API call, which downloads a large JSON file (around 100KB per account) that contains all of the IAM details for the account. This includes data on users, groups, roles, customer-managed policies, and AWS-managed policies.
You must have AWS credentials configured that can be used by the CLI.
You must have the privileges to run iam:GetAccountAuthorizationDetails. The arn:aws:iam::aws:policy/SecurityAudit policy includes this, as do many others that allow Read access to the IAM Service.
To download the account authorization details, ensure you are authenticated to AWS, then run cloudsplaining's download command:
cloudsplaining download
If you prefer to use your ~/.aws/credentials file instead of environment variables, you can specify the profile name:
cloudsplaining download --profile myprofile
It will download a JSON file in your current directory that contains your account authorization detail information.
Create Exclusions file
Cloudsplaining tool does not attempt to understand the context behind everything in your AWS account. It's possible to understand the context behind some of these things programmatically - whether the policy is applied to an instance profile, whether the policy is attached, whether inline IAM policies are in use, and whether or not AWS Managed Policies are in use. Only you know the context behind the design of your AWS infrastructure and the IAM strategy.
As such, it's important to eliminate False Positives that are context-dependent. You can do this with an exclusions file. We've included a command that will generate an exclusions file for you so you don't have to remember the required format.
You can create an exclusions template via the following command:
cloudsplaining create-exclusions-file
This will generate a file in your current directory titled exclusions.yml.
Now when you run the scan command, you can use the exclusions file like this:
default-iam-results.json: This contains the raw JSON output of the report. You can use this data file for operating on the scan results for various purposes. For example, you could write a Python script that parses this data and opens up automated JIRA issues or Salesforce Work Items. An example entry is shown below. The full example can be viewed at examples/files/iam-results-example.json
Resource constraints are best practice - especially for system roles/instance profiles - but sometimes, these are by design. For example, consider a situation where a custom IAM policy is used on an instance profile for an EC2 instance that provisions Terraform. In this case, broad permissions are design requirements - so we don't want to include these in the results.
You can create an exclusions template via the following command:
cloudsplaining create-exclusions-file
This will generate a file in your current directory titled exclusions.yml.
The default exclusions file looks like this:
# Policy names to exclude from evaluation
# Suggestion: Add policies here that are known to be overly permissive by design, after you run the initial report.
policies:
- "AWSServiceRoleFor*"
- "*ServiceRolePolicy"
- "*ServiceLinkedRolePolicy"
- "AdministratorAccess" # Otherwise, this will take a long time
- "service-role*"
- "aws-service-role*"
# Don't evaluate these roles, users, or groups as part of the evaluation
roles:
- "service-role*"
- "aws-service-role*"
users:
- ""
groups:
- ""
# Read-only actions to include in the results, such as s3:GetObject
# By default, it includes Actions that could lead to Data Exfiltration
include-actions:
- "s3:GetObject"
- "ssm:GetParameter"
- "ssm:GetParameters"
- "ssm:GetParametersByPath"
- "secretsmanager:GetSecretValue"
# Write actions to include from the results, such as kms:Decrypt
exclude-actions:
- ""
Make any additions or modifications that you want.
Under policies, list the path of policy names that you want to exclude.
If you want to exclude a role titled MyRole, list MyRole or MyR* in the roles list.
You can follow the same approach for users and groups list.
Now when you run the scan command, you can use the exclusions file like this:
If your IAM user or IAM role has sts:AssumeRole permissions to a common IAM role across multiple AWS accounts, you can use the scan-multi-account command.
This diagram depicts how the process works:
Note: If you are new to setting up cross-account access, check out the official AWS Tutorial on Delegating access across AWS accounts using IAM roles. That can help you set up the architecture above.
First, you'll need to create the multi-account config file. Run the following command:
Note: Observe how the format of the file above includes account_name: accountID. Edit the file contents to match your desired account name and account ID. Include as many account IDs as you like.
For the next step, let's say that:
We have a role in the target accounts that is called CommonSecurityRole.
The credentials for your IAM user are under the AWS Credentials profile called scanning-user.
That user has sts:AssumeRole permissions to assume the CommonSecurityRole in all your target accounts specified in the YAML file we created previously.
You want to save the output to an S3 bucket called my-results-bucket
Using the data above, you can run the following command:
Note that if you run the above without the --profile flag, it will execute in the standard AWS Credentials order of precedence (i.e., Environment variables, credentials profiles, ECS container credentials, then finally EC2 Instance Profile credentials).
Custom Guidance and Appendices
Cloudsplaining supports customizing the Guidance and Appendices sections of the HTML report to include organization-specific security recommendations and documentation.
No, it will only scan policies that are attached to IAM principals.
Will the download command download all policy versions?
Not by default. If you want to do this, specify the --include-non-default-policy-versions flag. Note that the scan tool does not currently operate on non-default versions.
I followed the installation instructions but can't execute the program via command line at all. What do I do?
This is likely an issue with your PATH. Your PATH environment variable is not considering the binary packages installed by pip3. On a Mac, you can likely fix this by entering the command below, depending on the versions you have installed. YMMV.
export PATH=$HOME/Library/Python/3.7/bin/:$PATH
I followed the installation instructions, but I am receiving a ModuleNotFoundError that says No module named policy_sentry.analysis.expand. What should I do?
Try upgrading to the latest version of Cloudsplaining. This error was fixed in version 0.0.10.
References
Policy Sentry by Kinnaird McQuade at Salesforce
Parliament by Scott Piper at Summit Route and Duo Labs.
AWS Privilege Escalation Methods by Spencer Gietzen at Rhino Security Labs
Understanding Access Level Summaries within Policy Summaries
Leveraging next-generation blockchain-based AI across multiple service meshes to transparently automate multi-cloud IAM wizardry :mage_man:
How active is development on salesforce/cloudsplaining?
The most recent commit recorded on salesforce/cloudsplaining was 3 months ago, based on the GitHub push timestamp. The repository has 222 forks — one of the better signals of community interest.
How does salesforce/cloudsplaining compare to other Security projects?
salesforce/cloudsplaining is tracked by TopGit in the Security category, with 2.3k GitHub stars and written in JavaScript. Browse the Security topic page on TopGit to compare it against similar projects by stars and activity.
How many stars does salesforce/cloudsplaining have?
salesforce/cloudsplaining has 2.3k GitHub stars — refresh the page for the live number, or check github.com/salesforce/cloudsplaining. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
What is salesforce/cloudsplaining?
salesforce/cloudsplaining (salesforce/cloudsplaining) is a JavaScript project on GitHub. From the project's own README: Cloudsplaining is an AWS IAM Security Assessment tool that identifies violations of least privilege and generates a risk-prioritized report.
What language is salesforce/cloudsplaining written in?
salesforce/cloudsplaining is written primarily in JavaScript. GitHub's language field is based on the largest share of bytes in the default branch.
What topics is salesforce/cloudsplaining associated with?
GitHub's repository topics for salesforce/cloudsplaining: "aws", "aws-iam", "aws-security", "cloud", "cloud-security", "hacktoberfest", "iam", "salesforce", "security". TopGit's editorial category is Security.
Why is salesforce/cloudsplaining categorized under Security?
TopGit places salesforce/cloudsplaining in the Security category based on its GitHub topics and description (tagged: "aws", "aws-iam", "aws-security"). Categories are assigned from real repository metadata, not editorial guesswork.
Read full README in the tab above.
Curious whether cloudsplaining is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about cloudsplaining.