DOCSEARCHbyAlgolia
Submit Docs

Cloudsplaining

repository·master·Indexed 25 days ago

https://github.com/salesforce/cloudsplaining

An AWS IAM security assessment tool (version 0.4.8) designed to identify least-privilege violations. It analyzes IAM policies for risks such as data exfiltration, privilege escalation, and credentials exposure, generating prioritized HTML reports. The tool supports scanning single policies, entire AWS accounts, or multiple accounts via cross-account roles, and includes features for managing exclusions and automating JIRA ticket creation.

Tokens
29.9K
Snippets
48
Records
122
Agent score
80%

What's inside Cloudsplaining

  1. Overview of Cloudsplaining capabilities

    master

    Cloudsplaining is a tool designed to identify violations of least privilege in AWS IAM policies. It identifies IAM actions that lack resource constraints, which can lead to several security risks:

    • Data Exfiltration: e.g., s3:GetObject, ssm:GetParameter, secretsmanager:GetSecretValue.
    • Infrastructure Modification
    • Resource Exposure: The ability to modify resource-based policies.
    • Privilege Escalation
    • Credentials Exposure

    Cloudsplaining can scan a single policy file, all policies within a single AWS account, or policies across multiple AWS accounts.

  2. Overview of Cloudsplaining

    master

    Cloudsplaining is an AWS IAM Security Assessment tool designed to identify violations of the principle of least privilege. It analyzes AWS IAM policies to find IAM actions that lack proper resource constraints and generates a risk-prioritized HTML report.

    Key risk categories identified include:

    • Data Exfiltration: Actions like s3:GetObject, ssm:GetParameter, and secretsmanager:GetSecretValue.
    • Infrastructure Modification
    • Resource Exposure: The ability to modify resource-based policies.
    • Privilege Escalation: Based on Pathfinding.cloud.
    • Credentials Exposure

    Cloudsplaining also flags IAM Roles that can be assumed by AWS Compute Services (EC2, ECS, EKS, or Lambda), which can be high-risk if those services are exposed to the internet.

  3. What is Resource Exposure in Cloudsplaining?

    master

    In Cloudsplaining, Resource Exposure refers to IAM actions that allow a user to modify resource-based policies or perform other actions that can expose AWS resources to the public or unauthorized actors.

    Common examples of resource exposure risks include:

    • S3 Permissions: Actions like s3:PutBucketPolicy or s3:PutObjectAcl can make data publicly accessible.
    • ECR Permissions: ecr:SetRepositoryPolicy could allow an attacker to exfiltrate or tamper with container images.
    • IAM Permissions: iam:UpdateAssumeRolePolicy can be used to create backdoors by allowing external accounts to assume privileged roles.
    • RAM Permissions: Modifying AWS Resource Access Manager settings could allow sharing sensitive VPCs with rogue accounts.

  5. Control exclusion message visibility when using Cloudsplaining as a library

    master

    When using Cloudsplaining as a library, messages indicating that a prefix or suffix was excluded from evaluation are routed through the standard Python logging module at the DEBUG level. This allows library consumers to control the verbosity of these messages using standard logging configuration.

    By default, these messages are silent in library mode. If you wish to see these messages, you must configure your logger to capture DEBUG level logs from the cloudsplaining package.

  6. Understanding roles assumable by cross-account principals

    master

    IAM Roles that can be assumed from other AWS accounts present a higher security risk than roles restricted to the same AWS account, particularly if the external account is not owned by your organization. Cloudsplaining flags these roles to highlight potential unauthorized access vectors.

    When reviewing roles flagged with this finding, verify the following:

    • Trust Verification: Ensure the external account is a trusted entity belonging to your organization or a legitimate partner.
    • Permission Scoping: Confirm the role's permissions are strictly limited to what is required for the cross-account use case.
    • Monitoring: Ensure logging and monitoring are active to track all cross-account access activity.
    • Condition Constraints: Check that the trust relationship includes appropriate IAM Condition keys to limit the scope of access.

    Risk Note: If an external account is compromised, any role it can assume in your account could lead to unauthorized access to your resources, especially if those roles grant broad permissions or access to sensitive data.

  7. Understand privilege escalation paths in Cloudsplaining

    master
    Cloudsplaining identifies privilege escalation paths, which are sequences of IAM permissions that allow an identity to gain higher-level privileges. These paths are categorized by the AWS service involved (e.g., ec2, iam, lambda). Many of these paths rely on the iam:passrole permission combined with service-specific actions (like lambda:createfunction or ecs:runtask) to attach a more powerful role to a new resource and then execute code or tasks using that role.

  8. Understand Cloudsplaining privilege escalation detection

    master

    Cloudsplaining detects AWS IAM privilege escalation paths by identifying specific permissions that allow an attacker to increase their level of access. The detection logic is centralized in PRIVILEGE_ESCALATION_METHODS within cloudsplaining/shared/constants.py.

    Findings are categorized into five main groups based on Bishop Fox's research:

    1. IAM Permissions on other Users: Actions that allow manipulating other users (e.g., creating access keys or changing passwords).
    2. Permissions on Policies: Actions that allow modifying policy versions or attaching policies to users, groups, or roles.
    3. Updating an AssumeRole Policy: Actions that allow changing the trust relationship of a role.
    4. iam:PassRole:*: Actions that allow passing an existing IAM role to an AWS service (like EC2, Lambda, or Glue) to execute code with that role's permissions.
    5. Privilege Escalation using AWS Services: Using specific service permissions (like Glue) to gain access to attached roles.

  9. How the Cloudsplaining report handles new privilege escalation methods

    master

    The Cloudsplaining JavaScript/Vue report is fully data-driven. When you add a new method to the Python PRIVILEGE_ESCALATION_METHODS dictionary, the frontend automatically renders it without requiring any code changes.

    Findings are grouped under the PrivilegeEscalation category. The report iterates through findings and displays the type (the key you defined in Python) and the actions (the list of actions you defined).

    Optional Frontend Customization: If you need to change the risk description text (which is duplicated in the frontend and not read from the IAM data), you must edit:

    • cloudsplaining/output/src/util/glossary.js
    • cloudsplaining/output/src/assets/definition-privilege-escalation.md

    If you make frontend changes, you must rebuild the bundle using:

    just build-js

  10. Understand Infrastructure Modification actions

    master

    In the context of Cloudsplaining, Infrastructure Modification refers to IAM actions that possess "modify" capabilities. These actions are high-risk because they can be used for:

    • Resource Hijacking: Unauthorized takeover of existing resources.
    • Unauthorized Infrastructure Creation: Creating new resources without permission.
    • Backdoor Creation: Establishing persistent, unauthorized access.
    • Resource Modification: Changing existing resources, which can lead to service downtime or unintentional exposure.

    Example: An action like ec2:AuthorizeSecurityGroupIngress allows adding inbound rules to a security group. If misused, this can expose compute resources to the public internet or cause service disruptions.

  11. Identify Credentials Exposure actions

    master

    In Cloudsplaining, 'Credentials Exposure' refers to specific AWS actions that return sensitive credentials as part of the API response. When these actions are permitted by an IAM policy, they represent a security risk because an identity could potentially obtain access keys, tokens, or passwords.

    Common examples include:

    • iam:CreateAccessKey
    • iam:UpdateAccessKey
    • ecr:GetAuthorizationToken
    • sts:AssumeRole
    • sts:GetSessionToken

  12. Understand and remediate Service Wildcards

    master

    A "Service Wildcard" refers to IAM policy statements that grant access to all actions within a specific service using the service:* syntax (for example, s3:*).

    In Cloudsplaining reports, policies containing service wildcards often contribute to a high volume of security findings. Prioritizing the remediation of these statements—by replacing the wildcard with specific, required actions—is an efficient way to reduce the total number of issues identified in your Cloudsplaining report.