Cloudsplaining is an AWS IAM Security Assessment tool that identifies violations of least privilege and generates a risk-prioritized HTML report.
Documentation
For full documentation, please visit the project on ReadTheDocs.
Overview
Cloudsplaining identifies violations of least privilege in AWS IAM policies and generates a pretty HTML report with a triage worksheet. It can scan all the policies in your AWS account 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 Rhino Security Labs research)
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:{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject"
],
"Resource": "*"
}
]
}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::my-bucket/*"
}
]
}
That's why we wrote Cloudsplaining.
Cloudsplaining identifies violations of least privilege in AWS IAM policies and generates a pretty HTML report with a triage worksheet. It can scan all the policies in your AWS account 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 runningcloudsplaining --help
.
Scanning an entire AWS Account
Downloading Account Authorization Details
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
'sdownload
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
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
exclusions.yml
.Now when you run the
scan
command, you can use the exclusions file like this:cloudsplaining scan --exclusions-file exclusions.yml --input examples/files/example.json --output examples/files/
Scanning the Authorization Details file
Now that we've downloaded the account authorization file, we can scan all of the AWS IAM policies with
cloudsplaining
.Run the following command:
cloudsplaining scan --exclusions-file exclusions.yml --input examples/files/example.json --output examples/files/
It will also create a raw JSON data file:
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/output/example-authz-details-results.json
{
"example-authz-details": [
{
"AccountID": "012345678901",
"ManagedBy": "Customer",
"PolicyName": "InsecureUserPolicy",
"Arn": "arn:aws:iam::012345678901:user/userwithlotsofpermissions",
"ActionsCount": 2,
"ServicesCount": 1,
"Actions": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Services": [
"s3"
]
}
]
}
Filtering False Positives
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
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 Leaks
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
, listMyRole
orMyR*
in theroles
list. - You can follow the same approach for
users
andgroups
list.
- Under
scan
command, you can use the exclusions file like this:cloudsplaining scan --exclusions-file exclusions.yml --input examples/files/example.json --output examples/files/
Scanning a single policy
You can also scan a single policy file to identify risks instead of an entire account.
cloudsplaining scan-policy-file --input examples/policies/explicit-actions.json
The output will resemble the following:
Issue found: Data Exfiltration
Actions: s3:GetObject
Issue found: Resource Exposure
Actions: ecr:DeleteRepositoryPolicy, ecr:SetRepositoryPolicy, s3:BypassGovernanceRetention, s3:DeleteAccessPointPolicy, s3:DeleteBucketPolicy, s3:ObjectOwnerOverrideToBucketOwner, s3:PutAccessPointPolicy, s3:PutAccountPublicAccessBlock, s3:PutBucketAcl, s3:PutBucketPolicy, s3:PutBucketPublicAccessBlock, s3:PutObjectAcl, s3:PutObjectVersionAcl
Issue found: Unrestricted Infrastructure Modification
Actions: ecr:BatchDeleteImage, ecr:CompleteLayerUpload, ecr:CreateRepository, ecr:DeleteLifecyclePolicy, ecr:DeleteRepository, ecr:DeleteRepositoryPolicy, ecr:InitiateLayerUpload, ecr:PutImage, ecr:PutImageScanningConfiguration, ecr:PutImageTagMutability, ecr:PutLifecyclePolicy, ecr:SetRepositoryPolicy, ecr:StartImageScan, ecr:StartLifecyclePolicyPreview, ecr:TagResource, ecr:UntagResource, ecr:UploadLayerPart, s3:AbortMultipartUpload, s3:BypassGovernanceRetention, s3:CreateAccessPoint, s3:CreateBucket, s3:DeleteAccessPoint, s3:DeleteAccessPointPolicy, s3:DeleteBucket, s3:DeleteBucketPolicy, s3:DeleteBucketWebsite, s3:DeleteObject, s3:DeleteObjectTagging, s3:DeleteObjectVersion, s3:DeleteObjectVersionTagging, s3:GetObject, s3:ObjectOwnerOverrideToBucketOwner, s3:PutAccelerateConfiguration, s3:PutAccessPointPolicy, s3:PutAnalyticsConfiguration, s3:PutBucketAcl, s3:PutBucketCORS, s3:PutBucketLogging, s3:PutBucketNotification, s3:PutBucketObjectLockConfiguration, s3:PutBucketPolicy, s3:PutBucketPublicAccessBlock, s3:PutBucketRequestPayment, s3:PutBucketTagging, s3:PutBucketVersioning, s3:PutBucketWebsite, s3:PutEncryptionConfiguration, s3:PutInventoryConfiguration, s3:PutLifecycleConfiguration, s3:PutMetricsConfiguration, s3:PutObject, s3:PutObjectAcl, s3:PutObjectLegalHold, s3:PutObjectRetention, s3:PutObjectTagging, s3:PutObjectVersionAcl, s3:PutObjectVersionTagging, s3:PutReplicationConfiguration, s3:ReplicateDelete, s3:ReplicateObject, s3:Re plicateTags, s3:RestoreObject, s3:UpdateJobPriority, s3:UpdateJobStatus
Cheatsheet
# Download authorization details
cloudsplaining download
# Download from a specific profile
cloudsplaining download --profile someprofile
# Scan Authorization details
cloudsplaining scan --input default.json
# Scan Authorization details with custom exclusions
cloudsplaining scan --input default.json --exclusions-file exclusions.yml
# Scan Policy Files
cloudsplaining scan-policy-file --input examples/policies/wildcards.json
cloudsplaining scan-policy-file --input examples/policies/wildcards.json --exclusions-file examples/example-exclusions.yml
FAQ
Will it scan all policies by default?
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
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
慄♂️
Tags
AWS
AWS IAM
Cloudsplaining
Command Line
Exfiltration
HTML Report
Privilege Escalation
Python
Remote Code Execution
Scan
Security Assessment
Security Assessment Tool