runbooks 1.1.3__py3-none-any.whl → 1.1.5__py3-none-any.whl

runbooks/common/dry_run_examples.py

@@ -27,7 +27,7 @@ from runbooks.common.dry_run_framework import (
     resource_creation_operation,
     resource_deletion_operation,
     remediation_operation,
-    framework
+    framework,
 )
 from runbooks.common.rich_utils import console, print_success, print_warning, print_error
 
@@ -36,64 +36,65 @@ from runbooks.common.rich_utils import console, print_success, print_warning, pr
 # 1. DISCOVERY OPERATIONS (inventory, scan modules)
 # =============================================================================
 
+
 @discovery_operation
 def collect_ec2_instances(
-    dry_run_context: DryRunContext,
-    profile: Optional[str] = None,
-    regions: Optional[List[str]] = None
+    dry_run_context: DryRunContext, profile: Optional[str] = None, regions: Optional[List[str]] = None
 ) -> Dict[str, Any]:
     """
     Example discovery operation - EC2 instance collection.
-    
+
     Discovery operations are inherently safe, so dry-run simulates API calls
     for testing purposes only.
     """
     if dry_run_context.enabled:
         # Simulation mode - no real API calls
         console.print("[dim]🔄 Simulating EC2 instance discovery...[/dim]")
-        
+
         # Return simulated data
         return {
             "instances": [
                 {"id": "i-sim123", "type": "t3.micro", "state": "running"},
-                {"id": "i-sim456", "type": "m5.large", "state": "stopped"}
+                {"id": "i-sim456", "type": "m5.large", "state": "stopped"},
             ],
             "simulated": True,
             "region_count": len(regions or ["us-east-1"]),
-            "total_discovered": 2
+            "total_discovered": 2,
         }
-    
+
     else:
         # Real discovery operation
         console.print("[cyan]🔍 Discovering EC2 instances across regions...[/cyan]")
-        
+
         session = boto3.Session(profile_name=profile)
         instances = []
-        
+
         for region in regions or ["us-east-1"]:
             try:
-                ec2 = session.client('ec2', region_name=region)
+                ec2 = session.client("ec2", region_name=region)
                 response = ec2.describe_instances()
-                
-                for reservation in response['Reservations']:
-                    for instance in reservation['Instances']:
-                        instances.append({
-                            "id": instance['InstanceId'],
-                            "type": instance['InstanceType'],
-                            "state": instance['State']['Name'],
-                            "region": region
-                        })
-            
+
+                for reservation in response["Reservations"]:
+                    for instance in reservation["Instances"]:
+                        instances.append(
+                            {
+                                "id": instance["InstanceId"],
+                                "type": instance["InstanceType"],
+                                "state": instance["State"]["Name"],
+                                "region": region,
+                            }
+                        )
+
             except ClientError as e:
                 print_warning(f"Could not access region {region}: {e}")
-        
+
         print_success(f"Discovered {len(instances)} EC2 instances")
-        
+
         return {
             "instances": instances,
             "simulated": False,
             "region_count": len(regions or ["us-east-1"]),
-            "total_discovered": len(instances)
+            "total_discovered": len(instances),
         }
 
 
@@ -101,15 +102,14 @@ def collect_ec2_instances(
 # 2. ANALYSIS OPERATIONS (finops, security assess, vpc analyze modules)
 # =============================================================================
 
+
 @analysis_operation
 def analyze_cost_optimization(
-    dry_run_context: DryRunContext,
-    profile: Optional[str] = None,
-    account_id: Optional[str] = None
+    dry_run_context: DryRunContext, profile: Optional[str] = None, account_id: Optional[str] = None
 ) -> Dict[str, Any]:
     """
     Example analysis operation - cost optimization analysis.
-    
+
     Analysis operations are read-only, so dry-run shows what would be analyzed
     without making API calls.
     """
@@ -119,35 +119,31 @@ def analyze_cost_optimization(
         console.print(f"[dim]  • Account: {account_id or 'Current account'}[/dim]")
         console.print(f"[dim]  • Services: EC2, RDS, S3, Lambda[/dim]")
         console.print(f"[dim]  • Time range: Last 30 days[/dim]")
-        
+
         return {
             "preview": True,
-            "scope": {
-                "account_id": account_id,
-                "services": ["EC2", "RDS", "S3", "Lambda"],
-                "time_range": "30 days"
-            }
+            "scope": {"account_id": account_id, "services": ["EC2", "RDS", "S3", "Lambda"], "time_range": "30 days"},
         }
-    
+
     else:
         # Real cost analysis
         console.print("[green]💰 Analyzing cost optimization opportunities...[/green]")
-        
+
         session = boto3.Session(profile_name=profile)
-        cost_explorer = session.client('ce')
-        
+        cost_explorer = session.client("ce")
+
         # Real cost analysis logic here
         # This is a simplified example
-        
+
         print_success("Cost analysis completed")
-        
+
         return {
             "analysis_complete": True,
             "recommendations": [
                 {"service": "EC2", "potential_savings": "$150/month"},
-                {"service": "RDS", "potential_savings": "$75/month"}
+                {"service": "RDS", "potential_savings": "$75/month"},
             ],
-            "total_potential_savings": "$225/month"
+            "total_potential_savings": "$225/month",
         }
 
 
@@ -155,51 +151,46 @@ def analyze_cost_optimization(
 # 3. ASSESSMENT OPERATIONS (cfat assess module)
 # =============================================================================
 
+
 @assessment_operation
 def assess_security_compliance(
-    dry_run_context: DryRunContext,
-    profile: Optional[str] = None,
-    frameworks: Optional[List[str]] = None
+    dry_run_context: DryRunContext, profile: Optional[str] = None, frameworks: Optional[List[str]] = None
 ) -> Dict[str, Any]:
     """
     Example assessment operation - security compliance assessment.
-    
+
     Assessment operations are read-only, so dry-run shows assessment scope.
     """
     frameworks = frameworks or ["SOC2", "PCI-DSS", "HIPAA"]
-    
+
     if dry_run_context.enabled:
         # Preview mode - show assessment scope
         console.print("[dim]🔍 Preview: Security assessment scope[/dim]")
         console.print(f"[dim]  • Frameworks: {', '.join(frameworks)}[/dim]")
         console.print(f"[dim]  • Services to check: IAM, S3, EC2, VPC[/dim]")
         console.print(f"[dim]  • Estimated duration: 5-10 minutes[/dim]")
-        
-        return {
-            "preview": True,
-            "frameworks": frameworks,
-            "estimated_checks": 45
-        }
-    
+
+        return {"preview": True, "frameworks": frameworks, "estimated_checks": 45}
+
     else:
         # Real security assessment
         console.print("[blue]🔒 Conducting security compliance assessment...[/blue]")
-        
+
         session = boto3.Session(profile_name=profile)
-        
+
         # Real assessment logic here
         # This is a simplified example
-        
+
         results = {
             "frameworks_assessed": frameworks,
             "total_checks": 45,
             "passed": 38,
             "failed": 7,
-            "compliance_score": "84.4%"
+            "compliance_score": "84.4%",
         }
-        
+
         print_success(f"Assessment completed - Compliance score: {results['compliance_score']}")
-        
+
         return results
 
 
@@ -207,16 +198,17 @@ def assess_security_compliance(
 # 4. RESOURCE CREATION OPERATIONS (operate module)
 # =============================================================================
 
+
 @resource_creation_operation(estimated_impact="Create 1 EC2 instance (~$25/month)")
 def create_ec2_instance(
     dry_run_context: DryRunContext,
     instance_type: str = "t3.micro",
     image_id: Optional[str] = None,
-    profile: Optional[str] = None
+    profile: Optional[str] = None,
 ) -> Dict[str, Any]:
     """
     Example resource creation operation - EC2 instance creation.
-    
+
     Resource creation operations default to dry-run for safety.
     """
     if dry_run_context.enabled:
@@ -225,35 +217,30 @@ def create_ec2_instance(
         console.print(f"[dim]  • Instance type: {instance_type}[/dim]")
         console.print(f"[dim]  • AMI ID: {image_id or 'Latest Amazon Linux 2'}[/dim]")
         console.print(f"[dim]  • Estimated cost: ~$25/month[/dim]")
-        
-        return {
-            "preview": True,
-            "instance_type": instance_type,
-            "image_id": image_id,
-            "estimated_monthly_cost": 25.00
-        }
-    
+
+        return {"preview": True, "instance_type": instance_type, "image_id": image_id, "estimated_monthly_cost": 25.00}
+
     else:
         # Real instance creation
         console.print("[green]🚀 Creating EC2 instance...[/green]")
-        
+
         session = boto3.Session(profile_name=profile)
-        ec2 = session.client('ec2')
-        
+        ec2 = session.client("ec2")
+
         # Use default AMI if not specified
         if not image_id:
             # Get latest Amazon Linux 2 AMI
             images = ec2.describe_images(
-                Owners=['amazon'],
+                Owners=["amazon"],
                 Filters=[
-                    {'Name': 'name', 'Values': ['amzn2-ami-hvm-*']},
-                    {'Name': 'architecture', 'Values': ['x86_64']},
-                    {'Name': 'virtualization-type', 'Values': ['hvm']}
-                ]
+                    {"Name": "name", "Values": ["amzn2-ami-hvm-*"]},
+                    {"Name": "architecture", "Values": ["x86_64"]},
+                    {"Name": "virtualization-type", "Values": ["hvm"]},
+                ],
             )
-            if images['Images']:
-                image_id = sorted(images['Images'], key=lambda x: x['CreationDate'], reverse=True)[0]['ImageId']
-        
+            if images["Images"]:
+                image_id = sorted(images["Images"], key=lambda x: x["CreationDate"], reverse=True)[0]["ImageId"]
+
         try:
             response = ec2.run_instances(
                 ImageId=image_id,
@@ -262,25 +249,20 @@ def create_ec2_instance(
                 InstanceType=instance_type,
                 TagSpecifications=[
                     {
-                        'ResourceType': 'instance',
-                        'Tags': [
-                            {'Key': 'CreatedBy', 'Value': 'CloudOps-Runbooks'},
-                            {'Key': 'Purpose', 'Value': 'Testing'}
-                        ]
+                        "ResourceType": "instance",
+                        "Tags": [
+                            {"Key": "CreatedBy", "Value": "CloudOps-Runbooks"},
+                            {"Key": "Purpose", "Value": "Testing"},
+                        ],
                     }
-                ]
+                ],
             )
-            
-            instance_id = response['Instances'][0]['InstanceId']
+
+            instance_id = response["Instances"][0]["InstanceId"]
             print_success(f"EC2 instance created: {instance_id}")
-            
-            return {
-                "instance_id": instance_id,
-                "instance_type": instance_type,
-                "image_id": image_id,
-                "created": True
-            }
-            
+
+            return {"instance_id": instance_id, "instance_type": instance_type, "image_id": image_id, "created": True}
+
         except ClientError as e:
             print_error(f"Failed to create instance: {e}")
             raise
@@ -290,15 +272,14 @@ def create_ec2_instance(
 # 5. RESOURCE DELETION OPERATIONS (operate module)
 # =============================================================================
 
+
 @resource_deletion_operation(estimated_impact="Delete EC2 instances (~$150/month savings)")
 def terminate_ec2_instances(
-    dry_run_context: DryRunContext,
-    instance_ids: List[str],
-    profile: Optional[str] = None
+    dry_run_context: DryRunContext, instance_ids: List[str], profile: Optional[str] = None
 ) -> Dict[str, Any]:
     """
     Example resource deletion operation - EC2 instance termination.
-    
+
     Resource deletion operations default to dry-run and require confirmation.
     """
     if dry_run_context.enabled:
@@ -308,40 +289,38 @@ def terminate_ec2_instances(
         console.print(f"[dim]  • Instance IDs: {', '.join(instance_ids)}[/dim]")
         console.print(f"[dim]  • Estimated savings: ~$150/month[/dim]")
         console.print(f"[dim]  • ⚠️  THIS OPERATION IS IRREVERSIBLE[/dim]")
-        
+
         return {
             "preview": True,
             "instances_to_terminate": instance_ids,
             "estimated_savings": 150.00,
-            "irreversible": True
+            "irreversible": True,
         }
-    
+
     else:
         # Real instance termination
         console.print("[red]💥 Terminating EC2 instances...[/red]")
-        
+
         session = boto3.Session(profile_name=profile)
-        ec2 = session.client('ec2')
-        
+        ec2 = session.client("ec2")
+
         try:
             response = ec2.terminate_instances(InstanceIds=instance_ids)
-            
+
             terminated = []
-            for instance in response['TerminatingInstances']:
-                terminated.append({
-                    'instance_id': instance['InstanceId'],
-                    'current_state': instance['CurrentState']['Name'],
-                    'previous_state': instance['PreviousState']['Name']
-                })
-            
+            for instance in response["TerminatingInstances"]:
+                terminated.append(
+                    {
+                        "instance_id": instance["InstanceId"],
+                        "current_state": instance["CurrentState"]["Name"],
+                        "previous_state": instance["PreviousState"]["Name"],
+                    }
+                )
+
             print_success(f"Successfully initiated termination of {len(terminated)} instances")
-            
-            return {
-                "terminated_instances": terminated,
-                "count": len(terminated),
-                "operation": "terminate"
-            }
-            
+
+            return {"terminated_instances": terminated, "count": len(terminated), "operation": "terminate"}
+
         except ClientError as e:
             print_error(f"Failed to terminate instances: {e}")
             raise
@@ -351,15 +330,14 @@ def terminate_ec2_instances(
 # 6. SECURITY REMEDIATION OPERATIONS (remediation module)
 # =============================================================================
 
+
 @remediation_operation(estimated_impact="Fix S3 public buckets (security improvement)")
 def fix_public_s3_buckets(
-    dry_run_context: DryRunContext,
-    bucket_names: List[str],
-    profile: Optional[str] = None
+    dry_run_context: DryRunContext, bucket_names: List[str], profile: Optional[str] = None
 ) -> Dict[str, Any]:
     """
     Example security remediation operation - fix public S3 buckets.
-    
+
     Remediation operations default to dry-run and require confirmation.
     """
     if dry_run_context.enabled:
@@ -368,61 +346,55 @@ def fix_public_s3_buckets(
         console.print(f"[dim]  • Buckets to secure: {len(bucket_names)}[/dim]")
         console.print(f"[dim]  • Bucket names: {', '.join(bucket_names)}[/dim]")
         console.print(f"[dim]  • Actions: Remove public access, update policies[/dim]")
-        
+
         return {
             "preview": True,
             "buckets_to_fix": bucket_names,
             "remediation_actions": [
                 "Remove public read access",
-                "Remove public write access", 
+                "Remove public write access",
                 "Update bucket policies",
-                "Enable access logging"
-            ]
+                "Enable access logging",
+            ],
         }
-    
+
     else:
         # Real security remediation
         console.print("[green]🔒 Applying security remediation to S3 buckets...[/green]")
-        
+
         session = boto3.Session(profile_name=profile)
-        s3 = session.client('s3')
-        
+        s3 = session.client("s3")
+
         remediated_buckets = []
-        
+
         for bucket_name in bucket_names:
             try:
                 # Block public access
                 s3.put_public_access_block(
                     Bucket=bucket_name,
                     PublicAccessBlockConfiguration={
-                        'BlockPublicAcls': True,
-                        'IgnorePublicAcls': True,
-                        'BlockPublicPolicy': True,
-                        'RestrictPublicBuckets': True
-                    }
+                        "BlockPublicAcls": True,
+                        "IgnorePublicAcls": True,
+                        "BlockPublicPolicy": True,
+                        "RestrictPublicBuckets": True,
+                    },
                 )
-                
-                remediated_buckets.append({
-                    'bucket_name': bucket_name,
-                    'status': 'secured',
-                    'actions_applied': ['public_access_blocked']
-                })
-                
+
+                remediated_buckets.append(
+                    {"bucket_name": bucket_name, "status": "secured", "actions_applied": ["public_access_blocked"]}
+                )
+
             except ClientError as e:
                 print_warning(f"Could not secure bucket {bucket_name}: {e}")
-                remediated_buckets.append({
-                    'bucket_name': bucket_name,
-                    'status': 'failed',
-                    'error': str(e)
-                })
-        
-        successful = len([b for b in remediated_buckets if b['status'] == 'secured'])
+                remediated_buckets.append({"bucket_name": bucket_name, "status": "failed", "error": str(e)})
+
+        successful = len([b for b in remediated_buckets if b["status"] == "secured"])
         print_success(f"Successfully secured {successful}/{len(bucket_names)} S3 buckets")
-        
+
         return {
             "buckets_processed": remediated_buckets,
             "successful_count": successful,
-            "total_count": len(bucket_names)
+            "total_count": len(bucket_names),
         }
 
 
@@ -430,14 +402,13 @@ def fix_public_s3_buckets(
 # 7. DIRECT FRAMEWORK USAGE (without decorators)
 # =============================================================================
 
+
 def custom_operation_with_framework(
-    dry_run: bool = True,
-    operation_name: str = "custom_operation",
-    resources: Optional[List[str]] = None
+    dry_run: bool = True, operation_name: str = "custom_operation", resources: Optional[List[str]] = None
 ) -> Dict[str, Any]:
     """
     Example of using the dry-run framework directly without decorators.
-    
+
     This approach gives you full control over the dry-run behavior
     and is useful for complex operations that need custom handling.
     """
@@ -448,19 +419,19 @@ def custom_operation_with_framework(
         module_name="example",
         operation_name=operation_name,
         target_resources=resources,
-        estimated_impact="Moderate configuration changes"
+        estimated_impact="Moderate configuration changes",
     )
-    
+
     # Display banner
     framework.display_dry_run_banner(context)
-    
+
     # Request confirmation if needed
     if not framework.confirm_operation(context):
         return {"cancelled": True}
-    
+
     # Log operation start
     framework.log_operation_start(context, {"custom_parameter": "example"})
-    
+
     try:
         if context.enabled:
             # Dry-run logic
@@ -471,12 +442,12 @@ def custom_operation_with_framework(
             console.print("[green]⚡ Executing custom operation...[/green]")
             # Your actual operation code here
             result = {"executed": True, "resources": resources or []}
-        
+
         # Log success
         framework.log_operation_complete(context, success=True, results=result)
-        
+
         return result
-        
+
     except Exception as e:
         # Log failure
         framework.log_operation_complete(context, success=False, error=str(e))
@@ -487,58 +458,60 @@ def custom_operation_with_framework(
 # 8. MIGRATION HELPER FUNCTIONS
 # =============================================================================
 
+
 def migrate_legacy_dry_run_function(legacy_function: callable) -> callable:
     """
     Helper function to migrate legacy dry-run implementations to the new framework.
-    
+
     This function can wrap existing functions that have their own dry-run logic
     and upgrade them to use the unified framework.
     """
+
     def wrapper(*args, **kwargs):
         # Extract dry_run parameter
-        dry_run = kwargs.get('dry_run', True)
-        
+        dry_run = kwargs.get("dry_run", True)
+
         # Determine operation type based on function name/behavior
         func_name = legacy_function.__name__
-        if 'create' in func_name or 'provision' in func_name:
+        if "create" in func_name or "provision" in func_name:
             op_type = OperationType.RESOURCE_CREATE
-        elif 'delete' in func_name or 'terminate' in func_name or 'remove' in func_name:
+        elif "delete" in func_name or "terminate" in func_name or "remove" in func_name:
             op_type = OperationType.RESOURCE_DELETE
-        elif 'modify' in func_name or 'update' in func_name or 'change' in func_name:
+        elif "modify" in func_name or "update" in func_name or "change" in func_name:
             op_type = OperationType.RESOURCE_MODIFY
-        elif 'fix' in func_name or 'remediat' in func_name:
+        elif "fix" in func_name or "remediat" in func_name:
             op_type = OperationType.REMEDIATION
         else:
             op_type = OperationType.ANALYSIS
-        
+
         # Create context
         context = framework.create_context(
             dry_run=dry_run,
             operation_type=op_type,
-            module_name=legacy_function.__module__.split('.')[-2] if '.' in legacy_function.__module__ else 'legacy',
-            operation_name=func_name
+            module_name=legacy_function.__module__.split(".")[-2] if "." in legacy_function.__module__ else "legacy",
+            operation_name=func_name,
         )
-        
+
         # Apply framework behavior
         framework.display_dry_run_banner(context)
-        
+
         if not framework.confirm_operation(context):
             return None
-        
+
         framework.log_operation_start(context)
-        
+
         try:
             # Call the original function with updated context
-            kwargs['dry_run'] = context.enabled
+            kwargs["dry_run"] = context.enabled
             result = legacy_function(*args, **kwargs)
-            
+
             framework.log_operation_complete(context, success=True, results={"migrated": True})
             return result
-            
+
         except Exception as e:
             framework.log_operation_complete(context, success=False, error=str(e))
             raise
-    
+
     return wrapper
 
 
@@ -551,37 +524,29 @@ if __name__ == "__main__":
     Example CLI usage demonstrating the dry-run framework.
     """
     import click
-    
+
     @click.group()
     def cli():
         """Example CLI with dry-run framework integration."""
         pass
-    
+
     @cli.command()
-    @click.option('--dry-run/--no-dry-run', default=True, help='Enable dry-run mode')
-    @click.option('--profile', help='AWS profile name')
-    @click.option('--regions', multiple=True, help='AWS regions')
+    @click.option("--dry-run/--no-dry-run", default=True, help="Enable dry-run mode")
+    @click.option("--profile", help="AWS profile name")
+    @click.option("--regions", multiple=True, help="AWS regions")
     def discover(dry_run, profile, regions):
         """Discover EC2 instances with dry-run support."""
-        result = collect_ec2_instances(
-            profile=profile,
-            regions=list(regions) if regions else None,
-            dry_run=dry_run
-        )
+        result = collect_ec2_instances(profile=profile, regions=list(regions) if regions else None, dry_run=dry_run)
         console.print(f"Discovery result: {result}")
-    
+
     @cli.command()
-    @click.option('--dry-run/--no-dry-run', default=True, help='Enable dry-run mode')
-    @click.option('--instance-type', default='t3.micro', help='Instance type')
-    @click.option('--profile', help='AWS profile name')
+    @click.option("--dry-run/--no-dry-run", default=True, help="Enable dry-run mode")
+    @click.option("--instance-type", default="t3.micro", help="Instance type")
+    @click.option("--profile", help="AWS profile name")
     def create(dry_run, instance_type, profile):
         """Create EC2 instance with dry-run support."""
-        result = create_ec2_instance(
-            instance_type=instance_type,
-            profile=profile,
-            dry_run=dry_run
-        )
+        result = create_ec2_instance(instance_type=instance_type, profile=profile, dry_run=dry_run)
         console.print(f"Creation result: {result}")
-    
+
     # Run CLI
-    cli()
+    cli()