cfn2iam 0.1.0__py3-none-any.whl

cfn2iam-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: cfn2iam
+Version: 0.1.0
+Summary: A tool to automatically generate minimal IAM policy to deploy a CloudFormation stack from its template.
+Project-URL: Homepage, https://github.com/mrlikl/cfn2iam.git
+Author-email: S Murali Krishnan <mrlikrsh@gmail.com>
+License-File: LICENSE
+Keywords: aws, cloudformation, iam, permissions
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: boto3
+Requires-Dist: pyyaml
+Requires-Dist: typer
+Description-Content-Type: text/markdown
+
+# CloudFormation to IAM (cfn2iam)
+
+A tool to automatically generate minimal IAM policy to deploy a CloudFormation stack from its template.
+
+## Overview
+
+This tool analyzes CloudFormation templates to identify all resource types used, then queries the CloudFormation registry to determine the required IAM permissions for each resource type. It can generate IAM policy documents or create IAM roles with the appropriate permissions.
+
+## Features
+
+- Parse CloudFormation templates in JSON or YAML format
+- Extract resource types and determine required permissions
+- Generate IAM policy documents with appropriate permissions
+- Create IAM roles with the generated permissions
+- Option to allow or deny delete permissions
+- Support for permissions boundaries
+
+## Prerequisites
+
+- Python 3.9+
+- AWS CLI configured with [CloudFormation DescribeType](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DescribeType.html) permission
+- [uv package manager](https://docs.astral.sh/uv/getting-started/installation/)
+
+## Installation
+
+```bash
+git clone https://github.com/mrlikl/cfn2iam.git
+cd cfn2iam
+uv sync
+```
+
+## Usage
+
+```bash
+python source/app.py <template_file> [options]
+# or using shorthand options
+python source/app.py -t <template_file> [options]
+```
+
+### Arguments
+
+- `template_file` or `-t, --template-file`: Path to the CloudFormation template file (JSON or YAML)
+
+### Options
+
+- `-d, --allow-delete`: Allow delete permissions instead of denying them
+- `-c, --create-role`: Create an IAM role with the generated permissions (default: True)
+- `-r, --role-name`: Name for the IAM role (if not specified, uses 'cfn2iam-<random_hash>')
+- `-p, --permissions-boundary`: ARN of the permissions boundary to attach to the role
+
+### Examples
+
+Generate a policy document from a template:
+```bash
+python source/app.py path/to/template.yaml
+# or
+python source/app.py -t path/to/template.yaml
+```
+
+Create an IAM role with delete permissions denied (default behavior):
+```bash
+python source/app.py path/to/template.yaml
+```
+
+Create an IAM role with delete permissions allowed:
+```bash
+python source/app.py path/to/template.yaml -d
+```
+
+Create an IAM role with a custom name:
+```bash
+python source/app.py path/to/template.yaml -r MyCustomRole
+```
+
+Create an IAM role with a permissions boundary:
+```bash
+python source/app.py path/to/template.yaml -p arn:aws:iam::123456789012:policy/boundary
+```
+
+## How It Works
+
+1. The tool parses the CloudFormation template to extract all resource types
+2. For each resource type, it queries the CloudFormation registry to get the required permissions
+3. It categorizes permissions into "update" (create/update/read) and "delete-specific" permissions
+4. It generates a policy document with appropriate Allow and Deny statements
+5. It saves the policy document to a file with a unique name
+6. If requested (default), it creates an IAM role with the generated policy
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

cfn2iam-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+source/__init__.py,sha256=Wex3ithyFiSRKcRb4rgt9kyWJfgxH_ABs7NO2jiJhbE,63
+source/app.py,sha256=3LGr4-RDejChF-cm1FwmEHkJn-aQwyJS_jTcsHSSLCg,7378
+cfn2iam-0.1.0.dist-info/METADATA,sha256=xYJ0eioUMy9tdSw5t0q08zRmigyjO45M2BMhX-tjhXw,3617
+cfn2iam-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+cfn2iam-0.1.0.dist-info/entry_points.txt,sha256=OnOURo8kIqzk26E1hWEKetZ27YFAUcPEUu7UfzMF268,43
+cfn2iam-0.1.0.dist-info/licenses/LICENSE,sha256=BX9jvbIeb-ywYBlPQBy6DW8yIYu6RfUoL7xrQ9xbp7o,1072
+cfn2iam-0.1.0.dist-info/RECORD,,

cfn2iam-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cfn2iam-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cfn2iam = source.app:app

cfn2iam-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Murali Krishnan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

source/__init__.py

@@ -0,0 +1 @@
+# This file is required to make the directory a Python package

source/app.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+import boto3
+import typer
+import json
+import yaml
+import sys
+import re
+import uuid
+from typing import Optional
+from importlib.metadata import version
+
+
+def version_callback(value: bool):
+    if value:
+        try:
+            pkg_version = version("cfn2iam")
+        except Exception:
+            pkg_version = "unknown"
+        print(f"cfn2iam {pkg_version}")
+        raise typer.Exit()
+
+# Simple constructor that ignores CloudFormation intrinsic functions
+
+
+def ignore_unknown_tags(loader, tag_suffix, node):
+    if isinstance(node, yaml.ScalarNode):
+        return loader.construct_scalar(node)
+    elif isinstance(node, yaml.SequenceNode):
+        return loader.construct_sequence(node)
+    elif isinstance(node, yaml.MappingNode):
+        return loader.construct_mapping(node)
+    return None
+
+
+# Add multi constructor to handle all CloudFormation tags
+yaml.SafeLoader.add_multi_constructor('!', ignore_unknown_tags)
+
+
+def parse_cloudformation_template(file_path):
+    with open(file_path, 'r') as file:
+        if file_path.endswith('.json'):
+            template = json.load(file)
+        elif file_path.endswith(('.yaml', '.yml')):
+            template = yaml.safe_load(file)
+        else:
+            raise ValueError(
+                "Unsupported file format. Please provide a JSON or YAML file.")
+
+    if 'Resources' not in template:
+        print("No Resources section found in the template.")
+        return set()
+
+    ignore_patterns = [
+        r"^Custom::.*",
+        r"^AWS::CDK::Metadata",
+        r"^AWS::CloudFormation::CustomResource"
+    ]
+
+    resource_types = set()
+    for resource in template['Resources'].values():
+        if 'Type' in resource:
+            resource_type = resource['Type']
+            if not any(re.match(pattern, resource_type) for pattern in ignore_patterns):
+                resource_types.add(resource_type)
+    return resource_types
+
+
+def get_permissions(resourcetype):
+    cfn_client = boto3.client('cloudformation')
+    response = cfn_client.describe_type(Type='RESOURCE', TypeName=resourcetype)
+    data = json.loads(response['Schema'])
+
+    iam_update = set()
+    iam_delete = set()
+
+    if 'handlers' in data:
+        handlers = data['handlers']
+        # Collect all non-delete permissions
+        for action in ['create', 'update', 'read', 'list']:
+            if action in handlers:
+                iam_update.update(handlers[action]['permissions'])
+
+        # Collect delete-only permissions
+        if 'delete' in handlers:
+            delete_perms = set(handlers['delete']['permissions'])
+            iam_delete = delete_perms - iam_update
+
+    return iam_update, iam_delete
+
+
+def generate_random_hash():
+    """Generate a short random hash for role name uniqueness"""
+    return uuid.uuid4().hex[:8]
+
+
+def generate_policy_document(all_update_permissions, all_delete_permissions, allow_delete=False):
+    """
+    Generate an IAM policy document with the specified permissions.
+
+    Args:
+        all_update_permissions (set): Set of permissions to allow
+        all_delete_permissions (set): Set of permissions to deny or allow based on allow_delete flag
+        allow_delete (bool): If True, include delete permissions as Allow, otherwise as Deny
+
+    Returns:
+        dict: Policy document
+    """
+    statements = []
+    if all_update_permissions:
+        statements.append({
+            "Effect": "Allow",
+            "Action": list(sorted(all_update_permissions)),
+            "Resource": "*"
+        })
+    if all_delete_permissions:
+        statements.append({
+            "Effect": "Allow" if allow_delete else "Deny",
+            "Action": list(sorted(all_delete_permissions)),
+            "Resource": "*"
+        })
+
+    policy_document = {
+        "Version": "2012-10-17",
+        "Statement": statements
+    }
+
+    return policy_document
+
+
+def create_iam_role(policy_document, role_name, permissions_boundary=None):
+    iam_client = boto3.client('iam')
+    trust_policy = {
+        "Version": "2012-10-17",
+        "Statement": [
+            {
+                "Effect": "Allow",
+                "Principal": {
+                    "Service": "cloudformation.amazonaws.com"
+                },
+                "Action": "sts:AssumeRole"
+            }
+        ]
+    }
+
+    try:
+        create_role_params = {
+            "RoleName": role_name,
+            "AssumeRolePolicyDocument": json.dumps(trust_policy),
+            "Description": "Role generated using cfn2iam"
+        }
+        if permissions_boundary:
+            create_role_params["PermissionsBoundary"] = permissions_boundary
+
+        response = iam_client.create_role(**create_role_params)
+        role_arn = response['Role']['Arn']
+        policy_name = f"{role_name}-Policy"
+        iam_client.put_role_policy(
+            RoleName=role_name,
+            PolicyName=policy_name,
+            PolicyDocument=json.dumps(policy_document)
+        )
+        return role_arn
+
+    except Exception as e:
+        print(f"Error creating IAM role: {e}")
+        return None
+
+
+app = typer.Typer(no_args_is_help=True)
+
+
+@app.command()
+def main(
+    template_path: str = typer.Argument(
+        help="Path to the CloudFormation template file"),
+    allow_delete: bool = typer.Option(
+        False, "-d", "--allow-delete", help="Allow delete permissions instead of denying them"),
+    create_role: bool = typer.Option(
+        False, "-c", "--create-role", help="Create an IAM role with the generated permissions"),
+    role_name: str = typer.Option(
+        None, "-r", "--role-name", help="Name for the IAM role (if not specified, uses 'cfn2iam-<random_hash>')"),
+    permissions_boundary: str = typer.Option(
+        None, "-p", "--permissions-boundary", help="ARN of the permissions boundary to attach to the role"),
+    version: Optional[bool] = typer.Option(
+        None, "--version", callback=version_callback, help="Show version and exit")
+):
+    """Generate IAM permissions for CloudFormation resources."""
+    try:
+        print(f"Parsing CloudFormation template: {template_path}")
+        resource_types = parse_cloudformation_template(template_path)
+
+        if not resource_types:
+            print("No resource types found in the template.")
+            sys.exit(1)
+
+        all_update_permissions = set()
+        all_delete_permissions = set()
+
+        for resource in resource_types:
+            update_permissions, delete_permissions = get_permissions(resource)
+            all_update_permissions.update(update_permissions)
+            all_delete_permissions.update(delete_permissions)
+
+        policy_document = generate_policy_document(
+            all_update_permissions, all_delete_permissions, allow_delete)
+        file_path = f"policy-{generate_random_hash()}.json"
+        with open(file_path, 'w') as json_file:
+            json.dump(policy_document, json_file, indent=2)
+        print(f"\nGenerated IAM Policy Document to {file_path}")
+
+        if create_role:
+            role_name = role_name or f"cfn2iam-{generate_random_hash()}"
+
+            role_arn = create_iam_role(
+                policy_document,
+                role_name,
+                permissions_boundary
+            )
+            if role_arn:
+                print(f"\nSuccessfully created IAM role: {role_arn}")
+
+    except Exception as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    typer.run(main)