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

runbooks/common/profile_utils.py

@@ -1,92 +1,80 @@
-#!/usr/bin/env python3
-"""
-Universal AWS Profile Management for CloudOps Runbooks Platform
-
-This module provides truly universal AWS profile management that works with ANY AWS setup:
-- Single account setups
-- Multi-account setups
-- Any profile naming convention
-- No specific environment variable requirements
-
-Features:
-- Universal compatibility: User --profile → AWS_PROFILE → "default"
-- Works with ANY AWS profile names (not just specific test profiles)
-- No hardcoded environment variable assumptions
-- Simple, reliable profile selection for all users
-- Enhanced profile validation with enterprise error handling
-
-Author: CloudOps Runbooks Team
-Version: 1.1.0 - Enhanced Profile Validation
-"""
-
+# Profile utilities for multi-account AWS operations with enterprise caching
 import os
 import time
-from functools import wraps
-from typing import Dict, Optional, Union, List, Tuple, Callable
-
 import boto3
-from botocore.exceptions import ProfileNotFound, NoCredentialsError
-
-from runbooks.common.rich_utils import console, print_error, print_success, print_info, print_warning
-
-# Profile cache to reduce duplicate calls (performance optimization)
-_profile_cache = {}
-_cache_timestamp = None
-_cache_ttl = 300  # 5 minutes cache TTL
-
-
-def get_profile_for_operation(operation_type: str, user_specified_profile: Optional[Union[str, Tuple[str, ...], List[str]]] = None) -> str:
+from typing import Optional, List, Dict, Any
+from runbooks.common.rich_utils import console
+from datetime import datetime
+
+# Enhanced caching system for enterprise performance
+_profile_cache: Dict[str, str] = {}
+_validation_cache: Dict[str, bool] = {}  # Cache for profile validation results
+_cache_timestamp: Optional[float] = None
+_cache_ttl: int = 300  # 5 minutes TTL for enterprise session management
+_session_id: Optional[str] = None  # Track session consistency
+_session_cache: Dict[str, boto3.Session] = {}  # Cache AWS sessions
+
+def _get_session_id() -> str:
+    """Generate consistent session ID for cache scoping"""
+    global _session_id
+    if _session_id is None:
+        _session_id = f"session_{int(time.time())}"
+    return _session_id
+
+def get_profile_for_operation(
+    operation_type: str,
+    user_specified_profile: Optional[str] = None,
+    profiles: Optional[List[str]] = None
+) -> str:
     """
-    Universal AWS profile selection that works with ANY AWS setup.
+    Enhanced profile resolution with intelligent caching and enterprise logging optimization.
 
-    SIMPLE PRIORITY ORDER (Universal Compatibility):
+    Priority Order:
     1. User-specified profile (--profile parameter) - HIGHEST PRIORITY
-    2. AWS_PROFILE environment variable - STANDARD AWS CONVENTION
-    3. "default" profile - AWS STANDARD FALLBACK
-
-    Works with ANY profile names and ANY AWS setup - no specific environment variable requirements.
+    2. Environment variable mapping (per operation type)
+    3. Default profile fallback
 
     Args:
-        operation_type: Type of operation (informational only, not used for profile selection)
-        user_specified_profile: Profile specified by user via --profile parameter (handles both str and tuple)
+        operation_type: Type of operation (billing, management, operational)
+        user_specified_profile: User-provided profile via --profile parameter
+        profiles: List of profiles for multi-account operations
 
     Returns:
-        str: Profile name to use for the operation
+        Profile name to use for the operation
 
-    Raises:
-        SystemExit: If user-specified profile not found in AWS config
+    Caching Strategy:
+    - Cache profile resolution to prevent redundant AWS API calls
+    - Session-scoped caching with 5-minute TTL
+    - Only log profile selection once per session to reduce noise
     """
-    # SAFETY NET: Handle tuple profiles (Click multiple=True parameter issue)
-    # This prevents errors like: Profile '('profile-name',)' not found
-    if isinstance(user_specified_profile, (tuple, list)) and user_specified_profile:
-        user_specified_profile = user_specified_profile[0]  # Take first profile from tuple/list
-    elif isinstance(user_specified_profile, (tuple, list)) and not user_specified_profile:
-        user_specified_profile = None  # Empty tuple/list becomes None
-        
-    global _profile_cache, _cache_timestamp
-    
-    # Check cache first to reduce duplicate calls (performance optimization)
-    cache_key = f"{operation_type}:{user_specified_profile or 'None'}"
+    global _cache_timestamp
     current_time = time.time()
-    
-    if (_cache_timestamp and 
-        current_time - _cache_timestamp < _cache_ttl and 
-        cache_key in _profile_cache):
-        return _profile_cache[cache_key]
-    
-    # Clear cache if TTL expired
+
+    # Create profile-specific cache key (same profile for all operations)
+    profile_cache_key = f"{_get_session_id()}:{user_specified_profile or 'default'}"
+
+    # Return cached result if still valid and within TTL
+    if (profile_cache_key in _profile_cache and
+        _cache_timestamp and
+        current_time - _cache_timestamp < _cache_ttl):
+        return _profile_cache[profile_cache_key]
+
+    # Update cache timestamp only when cache is actually refreshed
     if not _cache_timestamp or current_time - _cache_timestamp >= _cache_ttl:
         _profile_cache.clear()
+        _validation_cache.clear()
         _cache_timestamp = current_time
-    
+
     available_profiles = boto3.Session().available_profiles
 
     # PRIORITY 1: User-specified profile ALWAYS takes precedence
     if user_specified_profile and user_specified_profile != "default":
         if user_specified_profile in available_profiles:
-            console.log(f"[green]Using user-specified profile: {user_specified_profile}[/]")
-            # Cache the result to reduce duplicate calls
-            _profile_cache[cache_key] = user_specified_profile
+            # SESSION-AWARE LOGGING: Only log when cache miss occurs
+            if profile_cache_key not in _profile_cache:
+                console.log(f"[green]Using user-specified profile: {user_specified_profile}[/]")
+            # Cache the result to prevent duplicate logging
+            _profile_cache[profile_cache_key] = user_specified_profile
             return user_specified_profile
         else:
             console.log(f"[red]Error: Profile '{user_specified_profile}' not found in AWS config[/]")
@@ -96,312 +84,227 @@ def get_profile_for_operation(operation_type: str, user_specified_profile: Optio
     # PRIORITY 2: AWS_PROFILE environment variable (standard AWS convention)
     aws_profile = os.getenv("AWS_PROFILE")
     if aws_profile and aws_profile in available_profiles:
-        console.log(f"[dim cyan]Using AWS_PROFILE environment variable: {aws_profile}[/]")
-        # Cache the result to reduce duplicate calls
-        _profile_cache[cache_key] = aws_profile
+        _profile_cache[profile_cache_key] = aws_profile
         return aws_profile
 
-    # PRIORITY 3: Default profile (AWS standard fallback)
-    default_profile = "default"
-    console.log(f"[yellow]Using default AWS profile: {default_profile}[/]")
-    # Cache the result to reduce duplicate calls
-    _profile_cache[cache_key] = default_profile
-    return default_profile
-
+    # PRIORITY 3: Operation-specific environment variables
+    profile_map = {
+        "billing": os.getenv("BILLING_PROFILE"),
+        "management": os.getenv("MANAGEMENT_PROFILE"),
+        "operational": os.getenv("CENTRALISED_OPS_PROFILE"),
+    }
 
-def resolve_profile_for_operation_silent(operation_type: str, user_specified_profile: Optional[str] = None) -> str:
+    env_profile = profile_map.get(operation_type)
+    if env_profile and env_profile in available_profiles:
+        _profile_cache[profile_cache_key] = env_profile
+        return env_profile
+
+    # PRIORITY 4: Default profile fallback
+    if "default" in available_profiles:
+        _profile_cache[profile_cache_key] = "default"
+        return "default"
+    elif available_profiles:
+        # Use first available profile if no default
+        first_profile = available_profiles[0]
+        console.log(f"[yellow]Warning: No default profile found, using: {first_profile}[/]")
+        _profile_cache[profile_cache_key] = first_profile
+        return first_profile
+    else:
+        console.log("[red]Error: No AWS profiles configured[/]")
+        console.log("[yellow]Please run: aws configure sso or aws configure[/]")
+        raise SystemExit(1)
+
+def validate_profile_access(profile_name: str, operation_description: str = "") -> bool:
     """
-    Universal AWS profile resolution without logging (for display purposes).
-    Uses the same universal logic as get_profile_for_operation but without console output.
+    Validate that the specified profile has proper AWS access with caching.
 
     Args:
-        operation_type: Type of operation (informational only, not used for profile selection)
-        user_specified_profile: Profile specified by user via --profile parameter
+        profile_name: AWS profile name to validate
+        operation_description: Optional description of the operation (for logging)
 
     Returns:
-        str: Profile name to use for the operation
-
-    Raises:
-        SystemExit: If user-specified profile not found in AWS config
+        True if profile has access, False otherwise
     """
-    available_profiles = boto3.Session().available_profiles
-
-    # PRIORITY 1: User-specified profile ALWAYS takes precedence
-    if user_specified_profile and user_specified_profile != "default":
-        if user_specified_profile in available_profiles:
-            return user_specified_profile
-        else:
-            # Don't fall back - user explicitly chose this profile
-            raise SystemExit(1)
+    # Check cache first to avoid redundant validations
+    global _cache_timestamp
+    current_time = time.time()
+    cache_key = f"validation:{profile_name}"
 
-    # PRIORITY 2: AWS_PROFILE environment variable (standard AWS convention)
-    aws_profile = os.getenv("AWS_PROFILE")
-    if aws_profile and aws_profile in available_profiles:
-        return aws_profile
+    if (cache_key in _validation_cache and
+        _cache_timestamp and
+        current_time - _cache_timestamp < _cache_ttl):
+        return _validation_cache[cache_key]
 
-    # PRIORITY 3: Default profile (AWS standard fallback)
-    return "default"
+    try:
+        session = boto3.Session(profile_name=profile_name)
+        sts_client = session.client('sts')
+        sts_client.get_caller_identity()
 
+        # Cache successful validation
+        _validation_cache[cache_key] = True
+        return True
+    except Exception as e:
+        # Cache failed validation for shorter time to allow retry
+        _validation_cache[cache_key] = False
+        console.log(f"[yellow]Profile {profile_name} validation failed: {e}[/]")
+        return False
 
-def create_cost_session(profile: Optional[str] = None) -> boto3.Session:
+def get_account_id_from_profile(profile_name: str) -> Optional[str]:
     """
-    Create a boto3 session for cost operations with universal profile support.
-    Works with ANY AWS profile configuration.
+    Extract account ID from AWS profile.
 
     Args:
-        profile: User-specified profile (from --profile parameter)
+        profile_name: AWS profile name
 
     Returns:
-        boto3.Session: Session configured for AWS operations
+        Account ID if available, None otherwise
     """
-    selected_profile = get_profile_for_operation("cost", profile)
-    return boto3.Session(profile_name=selected_profile)
-
+    try:
+        session = boto3.Session(profile_name=profile_name)
+        sts_client = session.client('sts')
+        response = sts_client.get_caller_identity()
+        return response.get('Account')
+    except Exception:
+        return None
 
-def create_management_session(profile: Optional[str] = None) -> boto3.Session:
+def create_cost_session(profile_name: Optional[str] = None) -> boto3.Session:
     """
-    Create a boto3 session for management operations with universal profile support.
-    Works with ANY AWS profile configuration.
+    Create AWS session optimized for cost operations (Cost Explorer).
 
     Args:
-        profile: User-specified profile (from --profile parameter)
+        profile_name: AWS profile name for cost operations
 
     Returns:
-        boto3.Session: Session configured for AWS operations
+        Configured boto3 Session for cost operations
     """
-    selected_profile = get_profile_for_operation("management", profile)
-    return boto3.Session(profile_name=selected_profile)
+    cost_profile = get_profile_for_operation("billing", profile_name)
 
+    # Use cached session if available
+    session_key = f"cost:{cost_profile}"
+    if session_key in _session_cache:
+        return _session_cache[session_key]
 
-def create_operational_session(profile: Optional[str] = None) -> boto3.Session:
+    session = boto3.Session(profile_name=cost_profile)
+    _session_cache[session_key] = session
+    return session
+
+def create_management_session(profile_name: Optional[str] = None) -> boto3.Session:
     """
-    Create a boto3 session for operational tasks with universal profile support.
-    Works with ANY AWS profile configuration.
+    Create AWS session optimized for management operations (Organizations).
 
     Args:
-        profile: User-specified profile (from --profile parameter)
+        profile_name: AWS profile name for management operations
 
     Returns:
-        boto3.Session: Session configured for AWS operations
+        Configured boto3 Session for management operations
     """
-    selected_profile = get_profile_for_operation("operational", profile)
-    return boto3.Session(profile_name=selected_profile)
+    mgmt_profile = get_profile_for_operation("management", profile_name)
+
+    # Use cached session if available
+    session_key = f"management:{mgmt_profile}"
+    if session_key in _session_cache:
+        return _session_cache[session_key]
 
+    session = boto3.Session(profile_name=mgmt_profile)
+    _session_cache[session_key] = session
+    return session
 
-def get_current_profile_info() -> Dict[str, Optional[str]]:
+def create_operational_session(profile_name: Optional[str] = None) -> boto3.Session:
     """
-    Get current AWS profile information using universal approach.
-    Works with ANY AWS setup without hardcoded environment variable assumptions.
+    Create AWS session optimized for operational tasks (EC2, S3, etc).
+
+    Args:
+        profile_name: AWS profile name for operational tasks
 
     Returns:
-        Dict with current profile information
+        Configured boto3 Session for operational tasks
     """
-    return {
-        "aws_profile": os.getenv("AWS_PROFILE"),
-        "default_profile": "default",
-        "available_profiles": boto3.Session().available_profiles
-    }
+    ops_profile = get_profile_for_operation("operational", profile_name)
 
+    # Use cached session if available
+    session_key = f"operational:{ops_profile}"
+    if session_key in _session_cache:
+        return _session_cache[session_key]
 
-def validate_profile_access(profile_name: str, operation_type: str = "general") -> bool:
+    session = boto3.Session(profile_name=ops_profile)
+    _session_cache[session_key] = session
+    return session
+
+def get_current_profile_info(profile_name: Optional[str] = None) -> Dict[str, Any]:
     """
-    Validate that profile exists and is accessible.
+    Get current profile information including account ID and region.
 
     Args:
-        profile_name: AWS profile name to validate
-        operation_type: Type of operation for context
+        profile_name: AWS profile name to get info for
 
     Returns:
-        bool: True if profile is valid and accessible
+        Dictionary containing profile information
     """
     try:
-        available_profiles = boto3.Session().available_profiles
-        if profile_name not in available_profiles:
-            console.log(f"[red]Profile '{profile_name}' not found in AWS config[/]")
-            return False
-
-        # Test session creation
         session = boto3.Session(profile_name=profile_name)
-        sts_client = session.client("sts")
+        sts_client = session.client('sts')
         identity = sts_client.get_caller_identity()
 
-        console.log(f"[green]Profile '{profile_name}' validated for {operation_type} operations[/]")
-        console.log(f"[dim]Account: {identity.get('Account')}, User: {identity.get('UserId', 'Unknown')}[/]")
-        return True
-
-    except Exception as e:
-        console.log(f"[red]Profile '{profile_name}' validation failed: {str(e)}[/]")
-        return False
-
-
-def get_available_profiles_for_validation() -> list:
-    """
-    Get available AWS profiles for validation - truly universal approach.
-    
-    Returns all configured AWS profiles for validation without ANY hardcoded assumptions.
-    Works with any AWS setup: single account, multi-account, any profile naming convention.
-    
-    Returns:
-        list: Available AWS profile names for validation
-    """
-    try:
-        # Get all available profiles from AWS CLI configuration
-        available_profiles = boto3.Session().available_profiles
-        
-        # Start with AWS_PROFILE if set
-        validation_profiles = []
-        aws_profile = os.getenv("AWS_PROFILE")
-        if aws_profile and aws_profile in available_profiles:
-            validation_profiles.append(aws_profile)
-        
-        # Add all other available profiles (universal approach)
-        for profile in available_profiles:
-            if profile not in validation_profiles:
-                validation_profiles.append(profile)
-        
-        # Ensure we have at least one profile to test
-        if not validation_profiles:
-            validation_profiles = ['default']
-            
-        return validation_profiles
-        
+        return {
+            'profile_name': profile_name or 'default',
+            'account_id': identity.get('Account'),
+            'user_arn': identity.get('Arn'),
+            'region': session.region_name or 'us-east-1'
+        }
     except Exception as e:
-        console.log(f"[yellow]Warning: Could not detect AWS profiles: {e}[/]")
-        return ['default']  # Fallback to default profile
-
-
-def validate_profile_access_decorator(operation_type: str = "general"):
+        return {
+            'profile_name': profile_name or 'default',
+            'error': str(e),
+            'account_id': None,
+            'user_arn': None,
+            'region': None
+        }
+
+def resolve_profile_for_operation_silent(
+    operation_type: str,
+    user_specified_profile: Optional[str] = None
+) -> str:
     """
-    Decorator to validate profile has required permissions before executing operation.
-
-    Enhances existing profile management with enterprise validation capabilities.
+    Silent version of profile resolution without logging.
 
     Args:
-        operation_type: Type of operation for context and recommendations
-
-    Usage:
-        @validate_profile_access_decorator(operation_type="finops")
-        def my_cost_analysis(profile=None, **kwargs):
-            # Your operation code here
-    """
-    def decorator(f: Callable) -> Callable:
-        @wraps(f)
-        def wrapper(*args, **kwargs):
-            # Extract profile from kwargs
-            profile = kwargs.get('profile')
-
-            # Get the profile that would be used
-            selected_profile = get_profile_for_operation(operation_type, profile)
-
-            # Validate profile access
-            try:
-                session = boto3.Session(profile_name=selected_profile)
-                sts = session.client('sts')
-                identity = sts.get_caller_identity()
-
-                print_success(f"Profile validation successful: {selected_profile}")
-                print_info(f"Account: {identity.get('Account', 'Unknown')}")
-
-                # Store validated profile in kwargs for operation
-                kwargs['_validated_profile'] = selected_profile
-                kwargs['_account_id'] = identity.get('Account')
-
-            except ProfileNotFound:
-                print_error(f"AWS profile not found: {selected_profile}")
-                print_info("Available profiles:")
-                for p in boto3.Session().available_profiles:
-                    print_info(f"  • {p}")
-                raise SystemExit(1)
-
-            except NoCredentialsError:
-                print_error("No AWS credentials configured")
-                print_info("Configure credentials with: [bold green]aws configure[/]")
-                print_info("Or use SSO login: [bold green]aws sso login --profile your-profile[/]")
-                raise SystemExit(1)
-
-            except Exception as e:
-                print_error(f"Profile validation failed: {selected_profile}")
-                print_warning(f"Error: {str(e)}")
-
-                # Provide operation-specific recommendations
-                if operation_type == "finops" and "Access" in str(e):
-                    print_info("Cost operations may require billing permissions")
-                    print_info("Try: [bold green]--profile BILLING_PROFILE[/]")
-                elif operation_type == "inventory" and "Access" in str(e):
-                    print_info("Inventory operations may require organizations permissions")
-                    print_info("Try: [bold green]--profile MANAGEMENT_PROFILE[/]")
-                elif operation_type == "operate" and "Access" in str(e):
-                    print_info("Resource operations may require operational permissions")
-                    print_info("Try: [bold green]--profile CENTRALISED_OPS_PROFILE[/]")
-
-                raise SystemExit(1)
-
-            return f(*args, **kwargs)
-        return wrapper
-    return decorator
-
-
-def quick_profile_check(profile: Optional[str] = None, quiet: bool = False) -> bool:
-    """
-    Quick profile accessibility check without raising exceptions.
-
-    Args:
-        profile: Profile to check (None for auto-detection)
-        quiet: Suppress output messages
+        operation_type: Type of operation (billing, management, operational)
+        user_specified_profile: User-provided profile via --profile parameter
 
     Returns:
-        True if profile is accessible, False otherwise
+        Profile name to use for the operation
     """
-    try:
-        selected_profile = get_profile_for_operation("general", profile)
-        session = boto3.Session(profile_name=selected_profile)
-        sts = session.client('sts')
-        sts.get_caller_identity()
+    # Skip all logging and caching, just return the profile
+    if user_specified_profile and user_specified_profile != "default":
+        return user_specified_profile
 
-        if not quiet:
-            print_success(f"Profile {selected_profile} is accessible")
-        return True
+    # Check environment variables
+    profile_map = {
+        "billing": os.getenv("BILLING_PROFILE"),
+        "management": os.getenv("MANAGEMENT_PROFILE"),
+        "operational": os.getenv("CENTRALISED_OPS_PROFILE"),
+    }
 
-    except Exception as e:
-        if not quiet:
-            print_warning(f"Profile accessibility check failed: {str(e)}")
-        return False
+    env_profile = profile_map.get(operation_type)
+    if env_profile:
+        return env_profile
 
+    return user_specified_profile or "default"
 
-def get_profile_recommendations(operation_type: str) -> List[str]:
+def list_available_profiles() -> List[str]:
     """
-    Get profile recommendations for specific operation types.
-
-    Args:
-        operation_type: Type of operation (finops, inventory, operate, security)
+    Get list of all available AWS profiles.
 
     Returns:
-        List of recommended profile names (environment variable names)
+        List of available profile names
     """
-    recommendations = {
-        "finops": ["BILLING_PROFILE", "MANAGEMENT_PROFILE"],
-        "cost": ["BILLING_PROFILE", "MANAGEMENT_PROFILE"],
-        "inventory": ["MANAGEMENT_PROFILE", "CENTRALISED_OPS_PROFILE"],
-        "operate": ["CENTRALISED_OPS_PROFILE", "MANAGEMENT_PROFILE"],
-        "security": ["MANAGEMENT_PROFILE", "SECURITY_PROFILE"],
-        "cfat": ["MANAGEMENT_PROFILE"],
-        "vpc": ["CENTRALISED_OPS_PROFILE", "MANAGEMENT_PROFILE"]
-    }
-
-    return recommendations.get(operation_type, ["AWS_PROFILE", "MANAGEMENT_PROFILE"])
-
-
-# Export all public functions including new validation enhancements
-__all__ = [
-    "get_profile_for_operation",
-    "resolve_profile_for_operation_silent",
-    "create_cost_session",
-    "create_management_session",
-    "create_operational_session",
-    "get_current_profile_info",
-    "validate_profile_access",
-    "get_available_profiles_for_validation",
-    "validate_profile_access_decorator",
-    "quick_profile_check",
-    "get_profile_recommendations",
-]
+    return boto3.Session().available_profiles
+
+def clear_profile_cache() -> None:
+    """Clear the profile cache for testing or troubleshooting."""
+    global _profile_cache, _validation_cache, _session_cache, _cache_timestamp, _session_id
+    _profile_cache.clear()
+    _validation_cache.clear()
+    _session_cache.clear()
+    _cache_timestamp = None
+    _session_id = None