From 58c7834ffd558c81d97e5dc295b65c3cc2539fa0 Mon Sep 17 00:00:00 2001 From: nikhil6393 Date: Sun, 29 Mar 2026 23:56:53 +0530 Subject: [PATCH 1/3] docs: Update documentation to reflect current features (closes #178) --- README.md | 13 +++++++------ cloudsplaining/bin/cli.py | 6 +++--- docs/index.md | 4 ++-- docs/user-guide/overview.md | 13 +++++++------ 4 files changed, 19 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 59e96392..017e7c1e 100644 --- a/README.md +++ b/README.md @@ -27,13 +27,14 @@ For full documentation, please visit the [project on ReadTheDocs](https://clouds ## 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. +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 Rhino Security Labs research) +* [Data Exfiltration](https://cloudsplaining.readthedocs.io/en/latest/glossary/data-exfiltration/) (`s3:GetObject`, `ssm:GetParameter`, `secretsmanager:GetSecretValue`) +* [Infrastructure Modification](https://cloudsplaining.readthedocs.io/en/latest/glossary/infrastructure-modification/) +* [Resource Exposure](https://cloudsplaining.readthedocs.io/en/latest/glossary/resource-exposure/) (the ability to modify resource-based policies) +* [Privilege Escalation](https://cloudsplaining.readthedocs.io/en/latest/glossary/privilege-escalation/) (based on Rhino Security Labs research) +* [Credentials Exposure](https://cloudsplaining.readthedocs.io/en/latest/glossary/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](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_SendCommand.html) 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](https://opensource.salesforce.com/cloudsplaining/#executive-summary) for some examples. @@ -80,7 +81,7 @@ Policy Sentry [makes it really easy to do this](https://github.com/salesforce/po 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. +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 diff --git a/cloudsplaining/bin/cli.py b/cloudsplaining/bin/cli.py index 210a862f..60aa26b5 100755 --- a/cloudsplaining/bin/cli.py +++ b/cloudsplaining/bin/cli.py @@ -5,7 +5,7 @@ # For full license text, see the LICENSE file in the repo root # or https://opensource.org/licenses/BSD-3-Clause """ -Cloudsplaining is an AWS IAM Assessment tool that identifies violations of least privilege and generates a risk-prioritized HTML report with a triage worksheet. +Cloudsplaining is an AWS IAM Assessment tool that identifies violations of least privilege and generates a risk-prioritized HTML report. """ import click @@ -18,7 +18,7 @@ @click.version_option(version=__version__) def cloudsplaining() -> None: """ - Cloudsplaining is an AWS IAM Assessment tool that identifies violations of least privilege and generates a risk-prioritized HTML report with a triage worksheet. + Cloudsplaining is an AWS IAM Assessment tool that identifies violations of least privilege and generates a risk-prioritized HTML report. """ @@ -32,7 +32,7 @@ def cloudsplaining() -> None: def main() -> None: - """Cloudsplaining is an AWS IAM Assessment tool that identifies violations of least privilege and generates a risk-prioritized HTML report with a triage worksheet.""" + """Cloudsplaining is an AWS IAM Assessment tool that identifies violations of least privilege and generates a risk-prioritized HTML report.""" cloudsplaining() diff --git a/docs/index.md b/docs/index.md index 9744bd95..70a019d5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ # Cloudsplaining -[Cloudsplaining](https://github.com/salesforce/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. +[Cloudsplaining](https://github.com/salesforce/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. ![](_images/cloudsplaining-report.gif) @@ -8,7 +8,7 @@ * `cloudsplaining download` - Download IAM authorization details for an entire AWS account. * `cloudsplaining create-exclusions-file` - Create an exclusions file to filter out false positives specific to your context. -* `cloudsplaining scan` - Scan the IAM authorization details file; generate an HTML report and a triage worksheet. +* `cloudsplaining scan` - Scan the IAM authorization details file; generate an HTML report. * `cloudsplaining scan-policy-file` - Scan a single IAM policy file * `cloudsplaining --help` - Print help messages and exit. diff --git a/docs/user-guide/overview.md b/docs/user-guide/overview.md index 7cdd1f5b..5adc6f39 100644 --- a/docs/user-guide/overview.md +++ b/docs/user-guide/overview.md @@ -1,12 +1,13 @@ # Overview -[Cloudsplaining](https://github.com/salesforce/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. +[Cloudsplaining](https://github.com/salesforce/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 and thus can 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) +* [Data Exfiltration](../glossary/data-exfiltration.md) (`s3:GetObject`, `ssm:GetParameter`, `secretsmanager:GetSecretValue`) +* [Infrastructure Modification](../glossary/infrastructure-modification.md) +* [Resource Exposure](../glossary/resource-exposure.md) (the ability to modify resource-based policies) +* [Privilege Escalation](../glossary/privilege-escalation.md) (based on Rhino Security Labs research) +* [Credentials Exposure](../glossary/credentials-exposure.md) 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. @@ -18,4 +19,4 @@ You can also specify a custom exclusions file to filter out results that are Fal - `cloudsplaining create-exclusions-file --output-file exclusions.yml` * Scan the Account Authorization details - `cloudsplaining scan --input-file default-account-details.json --exclusions-file exclusions.yml` - - This generates three files: (1) The single-file HTML report, (2) The triage CSV worksheet, and (3) The raw JSON data file + - This generates two files: (1) The single-file HTML report, and (2) The raw JSON data file From b807222e7327af2c7fcc32ed3f6c6190d6c00f9d Mon Sep 17 00:00:00 2001 From: nikhil6393 Date: Mon, 30 Mar 2026 00:10:00 +0530 Subject: [PATCH 2/3] chore: Fix ReadTheDocs uv version mismatch --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index cbf7ae97..6f18ba40 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -12,7 +12,7 @@ build: pre_create_environment: - asdf plugin add uv - asdf install uv latest:0.10 - - asdf global uv latest + - asdf global uv latest:0.10 create_environment: - uv venv "${READTHEDOCS_VIRTUALENV_PATH}" install: From ed155816bc43fe895b94bdc48ff3eecdf8a102cb Mon Sep 17 00:00:00 2001 From: nikhil6393 Date: Mon, 30 Mar 2026 00:15:49 +0530 Subject: [PATCH 3/3] chore: Relax required uv version --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index d87f40e3..a6b63bee 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -78,7 +78,7 @@ requires = ["uv_build~=0.10.0"] build-backend = "uv_build" [tool.uv] -required-version = "~=0.10.0" +required-version = ">=0.10.0" [tool.uv.build-backend] module-name = "cloudsplaining"