Cloudsplaining

Warnings

• breaking 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.
  Fix: Upgrade Python to version 3.9 or newer.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• pip install cloudsplaining Install latest version

Imports

• scan_account_authorization_details

  from cloudsplaining.command.scan import scan_account_authorization_details

Quickstart

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.

import os
import json
from cloudsplaining.command.scan import scan_account_authorization_details
from cloudsplaining.shared.exclusions import DEFAULT_EXCLUSIONS, Exclusions

# NOTE: For a real scan, you would first generate an account authorization details JSON file.
# This typically requires AWS credentials configured (e.g., via AWS CLI or environment variables)
# and the `iam:GetAccountAuthorizationDetails` permission.
# Example CLI command: `cloudsplaining download --output-file account_authorization_details.json`
# For this example, we'll use a dummy file path and content.

dummy_auth_details_path = "account_authorization_details.json"
# In a real scenario, this would be a large JSON file downloaded from AWS.
# Example: https://github.com/salesforce/cloudsplaining/blob/master/examples/files/iam-results-example.json
dummy_auth_details_content = {
    "UserDetailList": [],
    "GroupDetailList": [],
    "RoleDetailList": [
        {
            "Path": "/",
            "RoleName": "TestRoleWithFullS3",
            "RoleId": "AROAJEXAMPLEAAAEK",
            "Arn": "arn:aws:iam::123456789012:role/TestRoleWithFullS3",
            "CreateDate": "2023-01-01T00:00:00Z",
            "AssumeRolePolicyDocument": {
                "Version": "2012-10-17",
                "Statement": [
                    {
                        "Effect": "Allow",
                        "Principal": {"Service": "ec2.amazonaws.com"},
                        "Action": "sts:AssumeRole"
                    }
                ]
            },
            "AttachedManagedPolicies": [
                {
                    "PolicyName": "AmazonS3FullAccess",
                    "PolicyArn": "arn:aws:iam::aws:policy/AmazonS3FullAccess"
                }
            ],
            "InstanceProfileList": []
        }
    ],
    "ManagedPolicyDetailList": [],
    "ContextKeyDetailList": []
}

with open(dummy_auth_details_path, "w") as f:
    json.dump(dummy_auth_details_content, f)


# Create an empty exclusions object for this quickstart (you might load from a file)
# An exclusions file is recommended for production use to filter out false positives.
exclusions = Exclusions(DEFAULT_EXCLUSIONS)

# Scan the account authorization details file programmatically
try:
    print(f"Scanning {dummy_auth_details_path}...")
    html_report_string = scan_account_authorization_details(
        input_file=dummy_auth_details_path,
        exclusions=exclusions,
        flag_all_risky_actions=False, # Set to True to flag all risky actions regardless of resource constraints
        # You can also set other parameters like 'high_priority_only' or 'severity'
    )
    # The HTML report content is returned as a string.
    # In a real application, you might save this to a file or serve it.
    # For this example, we'll just print a snippet.
    print("Scan complete. HTML report (snippet):\n")
    print(html_report_string[:500] + "...")

    # Clean up dummy file
    os.remove(dummy_auth_details_path)

except Exception as e:
    print(f"An error occurred during scan: {e}")
    if os.path.exists(dummy_auth_details_path):
        os.remove(dummy_auth_details_path)