{"id":2436,"library":"cloudsplaining","title":"Cloudsplaining","description":"Cloudsplaining is an AWS IAM Security Assessment tool that identifies violations of least privilege in AWS IAM policies. It scans all policies in an AWS account or a single policy file and generates a risk-prioritized HTML report and a triage worksheet. The library is currently at version 0.8.2 and maintains an active release cadence with frequent updates and bug fixes.","status":"active","version":"0.8.2","language":"en","source_language":"en","source_url":"https://github.com/salesforce/cloudsplaining","tags":["AWS","IAM","Security","Assessment","Least Privilege","Cloud","DevSecOps"],"install":[{"cmd":"pip install cloudsplaining","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Cloudsplaining is an assessment tool, while Policy Sentry is a preventative tool for policy authoring and automation. They are complementary, and Policy Sentry is often recommended for remediating issues discovered by Cloudsplaining.","package":"policy_sentry","optional":true}],"imports":[{"symbol":"scan_account_authorization_details","correct":"from cloudsplaining.command.scan import scan_account_authorization_details"}],"quickstart":{"code":"import os\nimport json\nfrom cloudsplaining.command.scan import scan_account_authorization_details\nfrom cloudsplaining.shared.exclusions import DEFAULT_EXCLUSIONS, Exclusions\n\n# NOTE: For a real scan, you would first generate an account authorization details JSON file.\n# This typically requires AWS credentials configured (e.g., via AWS CLI or environment variables)\n# and the `iam:GetAccountAuthorizationDetails` permission.\n# Example CLI command: `cloudsplaining download --output-file account_authorization_details.json`\n# For this example, we'll use a dummy file path and content.\n\ndummy_auth_details_path = \"account_authorization_details.json\"\n# In a real scenario, this would be a large JSON file downloaded from AWS.\n# Example: https://github.com/salesforce/cloudsplaining/blob/master/examples/files/iam-results-example.json\ndummy_auth_details_content = {\n    \"UserDetailList\": [],\n    \"GroupDetailList\": [],\n    \"RoleDetailList\": [\n        {\n            \"Path\": \"/\",\n            \"RoleName\": \"TestRoleWithFullS3\",\n            \"RoleId\": \"AROAJEXAMPLEAAAEK\",\n            \"Arn\": \"arn:aws:iam::123456789012:role/TestRoleWithFullS3\",\n            \"CreateDate\": \"2023-01-01T00:00:00Z\",\n            \"AssumeRolePolicyDocument\": {\n                \"Version\": \"2012-10-17\",\n                \"Statement\": [\n                    {\n                        \"Effect\": \"Allow\",\n                        \"Principal\": {\"Service\": \"ec2.amazonaws.com\"},\n                        \"Action\": \"sts:AssumeRole\"\n                    }\n                ]\n            },\n            \"AttachedManagedPolicies\": [\n                {\n                    \"PolicyName\": \"AmazonS3FullAccess\",\n                    \"PolicyArn\": \"arn:aws:iam::aws:policy/AmazonS3FullAccess\"\n                }\n            ],\n            \"InstanceProfileList\": []\n        }\n    ],\n    \"ManagedPolicyDetailList\": [],\n    \"ContextKeyDetailList\": []\n}\n\nwith open(dummy_auth_details_path, \"w\") as f:\n    json.dump(dummy_auth_details_content, f)\n\n\n# Create an empty exclusions object for this quickstart (you might load from a file)\n# An exclusions file is recommended for production use to filter out false positives.\nexclusions = Exclusions(DEFAULT_EXCLUSIONS)\n\n# Scan the account authorization details file programmatically\ntry:\n    print(f\"Scanning {dummy_auth_details_path}...\")\n    html_report_string = scan_account_authorization_details(\n        input_file=dummy_auth_details_path,\n        exclusions=exclusions,\n        flag_all_risky_actions=False, # Set to True to flag all risky actions regardless of resource constraints\n        # You can also set other parameters like 'high_priority_only' or 'severity'\n    )\n    # The HTML report content is returned as a string.\n    # In a real application, you might save this to a file or serve it.\n    # For this example, we'll just print a snippet.\n    print(\"Scan complete. HTML report (snippet):\\n\")\n    print(html_report_string[:500] + \"...\")\n\n    # Clean up dummy file\n    os.remove(dummy_auth_details_path)\n\nexcept Exception as e:\n    print(f\"An error occurred during scan: {e}\")\n    if os.path.exists(dummy_auth_details_path):\n        os.remove(dummy_auth_details_path)\n","lang":"python","description":"This quickstart demonstrates how to programmatically scan AWS IAM authorization details using Cloudsplaining. It assumes an `account_authorization_details.json` file, which is typically generated by running `cloudsplaining download` via the CLI. The example creates a dummy JSON file for demonstration purposes. It then uses the `scan_account_authorization_details` function to generate an HTML report string."},"warnings":[{"fix":"Upgrade Python to version 3.9 or newer.","message":"Version 0.8.0 dropped support for Python 3.8. Users on Python 3.8 must upgrade their Python environment to 3.9 or higher to use Cloudsplaining 0.8.0 and above.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Ensure AWS credentials are configured and the principal has `iam:GetAccountAuthorizationDetails` permission, typically part of the `SecurityAudit` AWS managed policy. Refer to AWS CLI documentation for credential configuration.","message":"Cloudsplaining requires AWS credentials configured in the environment (e.g., via AWS CLI, environment variables like `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) and the IAM permission `iam:GetAccountAuthorizationDetails` to download account details. Without these, the `cloudsplaining download` command will fail.","severity":"gotcha","affected_versions":"All"},{"fix":"Generate an exclusions file using `cloudsplaining create-exclusions-file` and customize it to suit your environment. Then, include it in your scan command: `cloudsplaining scan --exclusions-file exclusions.yml ...` or pass an `Exclusions` object when using the library programmatically.","message":"Cloudsplaining can generate false positives, as it does not inherently understand the context of all IAM policies in your environment (e.g., intended broad permissions for specific automation roles). It is recommended to create and utilize an 'exclusions file' to filter out these known false positives.","severity":"gotcha","affected_versions":"All"},{"fix":"Understand the implications of `--flag-all-risky-actions`. Use it when you want to see all potential risks without filtering by existing resource constraints, but be prepared for a larger number of findings that may require more aggressive triage.","message":"The `--flag-all-risky-actions` (or `flag_all_risky_actions=True` in the library) option changes how Cloudsplaining identifies risky actions. By default, it considers resource constraints or conditions. When this flag is enabled, it will flag all risky actions regardless of whether resource ARN constraints or conditions are used, leading to more verbose output.","severity":"gotcha","affected_versions":">=0.5.0"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}