runbooks 0.9.2__py3-none-any.whl → 0.9.4__py3-none-any.whl

runbooks/__init__.py

@@ -59,15 +59,24 @@ s3_ops = S3Operations()
 - **FinOps Practitioners**: Cost optimization and resource governance
 """
 
-from importlib.metadata import PackageNotFoundError
-from importlib.metadata import version as _pkg_version
+# Centralized Version Management - Single Source of Truth
+# All modules MUST import __version__ from this location
+__version__ = "0.9.3"
 
-# Keep package version in sync with distribution metadata
+# Fallback for legacy importlib.metadata usage during transition
 try:
-    __version__ = _pkg_version("runbooks")
+    from importlib.metadata import version as _pkg_version
+    _metadata_version = _pkg_version("runbooks")
+    if _metadata_version != __version__:
+        import warnings
+        warnings.warn(
+            f"Version mismatch detected: pyproject.toml has {_metadata_version}, "
+            f"but centralized version is {__version__}. Please sync pyproject.toml.",
+            UserWarning
+        )
 except Exception:
-    # Fallback if metadata is unavailable during editable installs
-    __version__ = "1.0.0"
+    # Expected during development or when package metadata is unavailable
+    pass
 
 # Core module exports
 from runbooks.config import RunbooksConfig, load_config, save_config

runbooks/cfat/__init__.py

@@ -56,8 +56,10 @@ from runbooks.cfat.models import (
 )
 from runbooks.cfat.runner import AssessmentRunner
 
+# Import centralized version from main runbooks package
+from runbooks import __version__
+
 # Version info
-__version__ = "0.7.8"
 __author__ = "CloudOps Runbooks Team"
 
 # Public API exports

runbooks/cloudops/__init__.py

@@ -51,7 +51,9 @@ from .models import (
     ResourceImpact
 )
 
-__version__ = "0.9.1"
+# Import centralized version from main runbooks package
+from runbooks import __version__
+
 __author__ = "CloudOps Enterprise Team"
 
 __all__ = [

runbooks/common/aws_utils.py

@@ -0,0 +1,367 @@
+#!/usr/bin/env python3
+"""
+AWS Security & Authentication Utilities for CloudOps Runbooks Platform
+
+This module provides enterprise-grade AWS authentication security enhancements
+following FAANG security-as-code principles:
+
+Features:
+- Profile name sanitization to prevent account ID exposure
+- Proactive token refresh with retry logic
+- Enhanced error handling with security-aware messaging
+- Audit trail maintenance while protecting sensitive identifiers
+- Token expiration prediction and silent refresh
+
+Author: DevSecOps Security Engineer - CloudOps Runbooks Team
+Version: 0.9.1
+Security Focus: Enterprise AWS Account Protection
+"""
+
+import re
+import time
+from datetime import datetime, timedelta
+from typing import Dict, List, Optional, Tuple
+
+import boto3
+from botocore.exceptions import ClientError, NoCredentialsError, TokenRetrievalError
+
+from runbooks.common.rich_utils import console
+
+
+class AWSProfileSanitizer:
+    """
+    Enterprise-grade AWS profile name sanitization for security logging.
+    
+    Prevents AWS account ID exposure in logs while maintaining audit trail integrity.
+    Following FAANG security-as-code principles for sensitive identifier protection.
+    """
+    
+    # Pattern to detect AWS account IDs in profile names
+    ACCOUNT_ID_PATTERN = re.compile(r'\b\d{12}\b')
+    
+    # Pattern to detect enterprise profile patterns
+    ENTERPRISE_PROFILE_PATTERN = re.compile(r'(ams|aws)-.*-ReadOnlyAccess-(\d{12})')
+    
+    @classmethod
+    def sanitize_profile_name(cls, profile_name: str, mask_style: str = "***masked***") -> str:
+        """
+        Sanitize AWS profile name by masking account IDs for secure logging.
+        
+        Replaces 12-digit AWS account IDs with masked values to prevent account enumeration
+        while preserving profile identification capabilities for audit purposes.
+        
+        Args:
+            profile_name: Original AWS profile name
+            mask_style: Masking pattern for account IDs (default: ***masked***)
+            
+        Returns:
+            Sanitized profile name with masked account IDs
+            
+        Example:
+            'ams-admin-Billing-ReadOnlyAccess-909135376185' → 'ams-admin-Billing-ReadOnlyAccess-***masked***'
+        """
+        if not profile_name:
+            return profile_name
+            
+        # Check for enterprise pattern first (more specific)
+        if cls.ENTERPRISE_PROFILE_PATTERN.match(profile_name):
+            return cls.ENTERPRISE_PROFILE_PATTERN.sub(r'\1-masked-ReadOnlyAccess-***masked***', profile_name)
+        
+        # General account ID masking
+        return cls.ACCOUNT_ID_PATTERN.sub(mask_style, profile_name)
+    
+    @classmethod
+    def sanitize_profile_list(cls, profiles: List[str]) -> List[str]:
+        """
+        Sanitize a list of AWS profile names for secure logging.
+        
+        Args:
+            profiles: List of AWS profile names
+            
+        Returns:
+            List of sanitized profile names
+        """
+        return [cls.sanitize_profile_name(profile) for profile in profiles]
+    
+    @classmethod
+    def create_secure_log_context(cls, profile: str, operation: str) -> Dict[str, str]:
+        """
+        Create secure logging context with sanitized profile information.
+        
+        Args:
+            profile: AWS profile name
+            operation: Operation being performed
+            
+        Returns:
+            Dictionary with sanitized context for secure logging
+        """
+        return {
+            "operation": operation,
+            "profile_sanitized": cls.sanitize_profile_name(profile),
+            "profile_type": cls._classify_profile_type(profile),
+            "timestamp": datetime.utcnow().isoformat()
+        }
+    
+    @classmethod
+    def _classify_profile_type(cls, profile_name: str) -> str:
+        """Classify profile type for enhanced logging context."""
+        profile_lower = profile_name.lower()
+        
+        if "billing" in profile_lower:
+            return "billing"
+        elif "management" in profile_lower:
+            return "management"
+        elif "ops" in profile_lower or "operational" in profile_lower:
+            return "operational"
+        elif "admin" in profile_lower:
+            return "administrative"
+        else:
+            return "standard"
+
+
+class AWSTokenManager:
+    """
+    Proactive AWS token management with security-focused error handling.
+    
+    Implements proactive token refresh, retry logic, and enhanced error messaging
+    to reduce authentication timing exposure and improve operational security.
+    """
+    
+    # Token refresh thresholds
+    TOKEN_REFRESH_THRESHOLD_MINUTES = 15  # Refresh if expires within 15 minutes
+    MAX_RETRY_ATTEMPTS = 3
+    RETRY_BACKOFF_BASE = 2  # Exponential backoff base (seconds)
+    
+    def __init__(self, profile_name: str):
+        """Initialize token manager for specific AWS profile."""
+        self.profile_name = profile_name
+        self.sanitized_profile = AWSProfileSanitizer.sanitize_profile_name(profile_name)
+        self._session = None
+        self._last_refresh_check = None
+        
+    def get_secure_session(self, force_refresh: bool = False) -> boto3.Session:
+        """
+        Get AWS session with proactive token refresh and security enhancements.
+        
+        Implements:
+        - Proactive token expiration checking
+        - Silent token refresh before expiration
+        - Exponential backoff retry logic
+        - Security-aware error messages
+        
+        Args:
+            force_refresh: Force token refresh regardless of expiration status
+            
+        Returns:
+            Boto3 session with valid credentials
+            
+        Raises:
+            SecurityError: For authentication security issues
+            TokenRefreshError: For token refresh failures
+        """
+        current_time = datetime.utcnow()
+        
+        # Check if proactive refresh is needed
+        if (force_refresh or 
+            self._session is None or 
+            self._needs_token_refresh(current_time)):
+            
+            self._session = self._refresh_session_with_retry()
+            self._last_refresh_check = current_time
+            
+            # Log secure refresh event
+            console.log(
+                f"[dim green]✅ Token refresh completed for profile: {self.sanitized_profile}[/]"
+            )
+        
+        return self._session
+    
+    def _needs_token_refresh(self, current_time: datetime) -> bool:
+        """Check if proactive token refresh is needed."""
+        if self._last_refresh_check is None:
+            return True
+            
+        # Check every 5 minutes to avoid excessive API calls
+        if (current_time - self._last_refresh_check) < timedelta(minutes=5):
+            return False
+            
+        try:
+            # Test session validity with STS call
+            if self._session:
+                sts_client = self._session.client('sts')
+                sts_client.get_caller_identity()
+                return False  # Session still valid
+        except ClientError as e:
+            error_code = e.response.get('Error', {}).get('Code', '')
+            if error_code in ['ExpiredToken', 'InvalidToken', 'TokenRefreshRequired']:
+                return True
+                
+        return False
+    
+    def _refresh_session_with_retry(self) -> boto3.Session:
+        """Refresh session with exponential backoff retry logic."""
+        last_exception = None
+        
+        for attempt in range(self.MAX_RETRY_ATTEMPTS):
+            try:
+                # Create new session
+                session = boto3.Session(profile_name=self.profile_name)
+                
+                # Validate session with STS call
+                sts_client = session.client('sts')
+                caller_identity = sts_client.get_caller_identity()
+                
+                # Log successful refresh (with sanitized profile)
+                console.log(
+                    f"[dim cyan]🔄 Session validated for {self.sanitized_profile} "
+                    f"(attempt {attempt + 1}/{self.MAX_RETRY_ATTEMPTS})[/]"
+                )
+                
+                return session
+                
+            except (ClientError, NoCredentialsError, TokenRetrievalError) as e:
+                last_exception = e
+                
+                if attempt < self.MAX_RETRY_ATTEMPTS - 1:
+                    # Wait with exponential backoff
+                    wait_time = self.RETRY_BACKOFF_BASE ** attempt
+                    console.log(
+                        f"[yellow]⏳ Token refresh attempt {attempt + 1} failed, "
+                        f"retrying in {wait_time}s for {self.sanitized_profile}[/]"
+                    )
+                    time.sleep(wait_time)
+                else:
+                    # Final attempt failed, provide enhanced guidance
+                    self._handle_token_refresh_failure(last_exception)
+        
+        # If we get here, all attempts failed
+        raise TokenRefreshError(
+            f"Failed to refresh AWS session for profile {self.sanitized_profile} "
+            f"after {self.MAX_RETRY_ATTEMPTS} attempts"
+        )
+    
+    def _handle_token_refresh_failure(self, error: Exception) -> None:
+        """Provide enhanced guidance for token refresh failures."""
+        error_str = str(error)
+        
+        # Determine error type for appropriate guidance
+        if "ExpiredToken" in error_str or "InvalidToken" in error_str:
+            console.log(
+                f"[red]🔐 Token expired for {self.sanitized_profile}[/]\n"
+                "[yellow]💡 Resolution steps:[/]\n"
+                f"  1. Run: [bold]aws sso login --profile {self.profile_name}[/bold]\n"
+                "  2. Complete browser authentication\n"
+                "  3. Retry your operation\n"
+                "  4. Consider extending SSO session duration in AWS settings"
+            )
+        elif "NoCredentialsError" in error_str:
+            console.log(
+                f"[red]🔐 No credentials found for {self.sanitized_profile}[/]\n"
+                "[yellow]💡 Resolution steps:[/]\n"
+                f"  1. Verify profile exists: [bold]aws configure list-profiles[/bold]\n"
+                f"  2. Configure profile: [bold]aws configure sso --profile {self.profile_name}[/bold]\n"
+                "  3. Complete SSO configuration\n"
+                "  4. Retry your operation"
+            )
+        else:
+            console.log(
+                f"[red]🔐 Authentication error for {self.sanitized_profile}: {str(error)[:100]}[/]\n"
+                "[yellow]💡 General resolution steps:[/]\n"
+                f"  1. Check AWS CLI configuration\n"
+                f"  2. Verify IAM permissions\n"
+                f"  3. Try: [bold]aws sts get-caller-identity --profile {self.profile_name}[/bold]"
+            )
+
+
+class SecurityError(Exception):
+    """Raised for AWS security-related errors."""
+    pass
+
+
+class TokenRefreshError(Exception):
+    """Raised for AWS token refresh failures."""
+    pass
+
+
+def create_secure_aws_session(profile_name: str, operation_context: str = "aws_operation") -> boto3.Session:
+    """
+    Create secure AWS session with enterprise security enhancements.
+    
+    This is the primary entry point for secure AWS session creation across
+    all CloudOps modules. Implements:
+    
+    - Profile name sanitization for secure logging
+    - Proactive token refresh
+    - Enhanced error handling
+    - Security audit trail
+    
+    Args:
+        profile_name: AWS profile name
+        operation_context: Description of the operation for audit logging
+        
+    Returns:
+        Secure boto3 session with valid credentials
+        
+    Raises:
+        SecurityError: For security-related authentication issues
+        TokenRefreshError: For token refresh failures
+        
+    Example:
+        session = create_secure_aws_session("ams-admin-Billing-ReadOnlyAccess-909135376185", "cost_analysis")
+    """
+    # Create secure logging context
+    log_context = AWSProfileSanitizer.create_secure_log_context(profile_name, operation_context)
+    
+    console.log(
+        f"[dim cyan]🔐 Initiating secure AWS session for {log_context['profile_sanitized']} "
+        f"({log_context['profile_type']} profile)[/]"
+    )
+    
+    try:
+        # Initialize token manager and get secure session
+        token_manager = AWSTokenManager(profile_name)
+        session = token_manager.get_secure_session()
+        
+        console.log(
+            f"[dim green]✅ Secure session established for {log_context['profile_sanitized']}[/]"
+        )
+        
+        return session
+        
+    except Exception as e:
+        console.log(
+            f"[red]❌ Failed to create secure session for {log_context['profile_sanitized']}: {str(e)[:100]}[/]"
+        )
+        raise
+
+
+def sanitize_aws_error_message(error_message: str) -> str:
+    """
+    Sanitize AWS error messages to remove sensitive account information.
+    
+    Args:
+        error_message: Original AWS error message
+        
+    Returns:
+        Sanitized error message with account IDs masked
+    """
+    return AWSProfileSanitizer.ACCOUNT_ID_PATTERN.sub("***masked***", error_message)
+
+
+def get_profile_classification(profile_name: str) -> Dict[str, str]:
+    """
+    Get security classification information for AWS profile.
+    
+    Args:
+        profile_name: AWS profile name
+        
+    Returns:
+        Dictionary with profile security classification
+    """
+    sanitizer = AWSProfileSanitizer()
+    return {
+        "original": profile_name,
+        "sanitized": sanitizer.sanitize_profile_name(profile_name),
+        "type": sanitizer._classify_profile_type(profile_name),
+        "risk_level": "high" if "admin" in profile_name.lower() else "medium"
+    }

runbooks/common/enhanced_logging_example.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""
+Enhanced Logging Integration Example for CloudOps Runbooks
+
+This module demonstrates how to integrate the enhanced multi-level logging system
+with Rich CLI formatting across different user types and scenarios.
+"""
+
+import time
+from typing import Dict, Any, Optional
+
+# Import enhanced logging capabilities
+from runbooks.enterprise.logging import get_context_logger, EnterpriseRichLogger
+
+
+class EnhancedLoggingExample:
+    """Demonstrates enhanced logging integration patterns for different user types."""
+    
+    def __init__(self, log_level: str = "INFO", json_output: bool = False):
+        """
+        Initialize with enhanced logger.
+        
+        Args:
+            log_level: Logging level (DEBUG, INFO, WARNING, ERROR)
+            json_output: Enable structured JSON output
+        """
+        self.logger = get_context_logger(level=log_level, json_output=json_output)
+        self.log_level = log_level.upper()
+    
+    def demonstrate_debug_logging(self):
+        """Demonstrate DEBUG level logging for tech users (SRE/DevOps)."""
+        print("\n=== DEBUG Level Logging (Tech Users) ===")
+        
+        # AWS API tracing example
+        start_time = time.time()
+        
+        # Simulate AWS API call
+        time.sleep(0.1)
+        duration = time.time() - start_time
+        
+        self.logger.debug_tech(
+            "EC2 instances discovered in region us-east-1",
+            aws_api={
+                "service": "ec2",
+                "operation": "describe_instances",
+                "region": "us-east-1"
+            },
+            duration=duration,
+            request_id="12345-abcde-67890",
+            resource_count=42
+        )
+        
+        # Performance metrics
+        self.logger.debug_tech(
+            "Cost analysis query executed",
+            aws_api={
+                "service": "ce",
+                "operation": "get_cost_and_usage"
+            },
+            duration=2.435,
+            data_points=1500,
+            cache_hit=False
+        )
+    
+    def demonstrate_info_logging(self):
+        """Demonstrate INFO level logging for standard users."""
+        print("\n=== INFO Level Logging (Standard Users) ===")
+        
+        # Standard operation status
+        self.logger.info_standard("Starting cost analysis for account 123456789012")
+        
+        # Progress indication
+        self.logger.info_standard("Processing 15 AWS services across 3 regions")
+        
+        # Completion status
+        self.logger.info_standard(
+            "Cost analysis completed successfully",
+            execution_time="12.3s",
+            resources_analyzed=245
+        )
+    
+    def demonstrate_warning_logging(self):
+        """Demonstrate WARNING level logging for business users."""
+        print("\n=== WARNING Level Logging (Business Users) ===")
+        
+        # Cost alerts with recommendations
+        self.logger.warning_business(
+            "High storage costs detected in S3",
+            recommendation="Consider implementing lifecycle policies for objects older than 90 days",
+            cost_impact=2847.50,
+            affected_buckets=12
+        )
+        
+        # Resource optimization alerts
+        self.logger.warning_business(
+            "Underutilized EC2 instances found",
+            recommendation="Review instance sizing for potential rightsizing opportunities",
+            cost_impact=1250.00,
+            instance_count=8
+        )
+        
+        # Budget threshold warnings
+        self.logger.warning_business(
+            "Monthly budget threshold exceeded",
+            recommendation="Review cost allocation and consider implementing cost controls",
+            cost_impact=450.75,
+            budget_utilization="105%"
+        )
+    
+    def demonstrate_error_logging(self):
+        """Demonstrate ERROR level logging for all users."""
+        print("\n=== ERROR Level Logging (All Users) ===")
+        
+        # AWS authentication errors
+        self.logger.error_all(
+            "Unable to access Cost Explorer API",
+            solution="Run 'aws sso login' to refresh your authentication tokens",
+            aws_error="ExpiredToken: Token has expired",
+            profile="billing-profile"
+        )
+        
+        # Configuration errors
+        self.logger.error_all(
+            "Invalid AWS profile configuration",
+            solution="Check your ~/.aws/config file or contact your AWS administrator",
+            aws_error="ProfileNotFound: The config profile (invalid-profile) could not be found"
+        )
+        
+        # Service access errors
+        self.logger.error_all(
+            "Insufficient permissions for Organizations API",
+            solution="Request 'organizations:ListAccounts' permission or use a different profile",
+            aws_error="AccessDenied: User is not authorized to perform organizations:ListAccounts"
+        )
+    
+    def demonstrate_structured_logging(self):
+        """Demonstrate structured JSON logging for programmatic use."""
+        print("\n=== Structured JSON Logging (Programmatic Use) ===")
+        
+        # Create JSON logger
+        json_logger = get_context_logger(level=self.log_level, json_output=True)
+        
+        # JSON structured logs
+        json_logger.info_standard(
+            "Cost analysis completed",
+            total_cost=15432.75,
+            account_count=5,
+            service_breakdown={
+                "EC2": 8750.25,
+                "S3": 3200.50,
+                "RDS": 2482.00,
+                "Lambda": 1000.00
+            }
+        )
+        
+        json_logger.warning_business(
+            "Budget variance detected",
+            recommendation="Implement cost controls",
+            cost_impact=2500.00,
+            variance_percentage=15.2
+        )
+    
+    def demonstrate_contextual_logging(self):
+        """Demonstrate context-aware logging based on execution environment."""
+        print("\n=== Context-Aware Logging ===")
+        
+        # Logging adapts to CLI vs Jupyter vs CI/CD environments
+        self.logger.info_standard("Environment-aware logging initialized")
+        
+        # Performance logging with context
+        with self.logger_performance_context("cost_analysis_operation") as perf:
+            # Simulate work
+            time.sleep(0.2)
+            perf.add_metric("accounts_processed", 12)
+            perf.add_metric("cost_data_points", 1500)
+
+
+def demo_user_type_scenarios():
+    """
+    Demonstrate logging for different user types and scenarios.
+    """
+    print("Enhanced Multi-Level Logging System Demo")
+    print("=" * 50)
+    
+    # Tech users (DEBUG level)
+    print("\n🔧 TECH USER SCENARIO (--log-level DEBUG)")
+    tech_demo = EnhancedLoggingExample(log_level="DEBUG")
+    tech_demo.demonstrate_debug_logging()
+    
+    # Standard users (INFO level) 
+    print("\n👥 STANDARD USER SCENARIO (--log-level INFO)")
+    standard_demo = EnhancedLoggingExample(log_level="INFO")
+    standard_demo.demonstrate_info_logging()
+    
+    # Business users (WARNING level)
+    print("\n💼 BUSINESS USER SCENARIO (--log-level WARNING)")
+    business_demo = EnhancedLoggingExample(log_level="WARNING")
+    business_demo.demonstrate_warning_logging()
+    
+    # Error scenarios (ERROR level)
+    print("\n🚨 ERROR SCENARIOS (--log-level ERROR)")
+    error_demo = EnhancedLoggingExample(log_level="ERROR")
+    error_demo.demonstrate_error_logging()
+    
+    # JSON output for automation
+    print("\n📄 STRUCTURED JSON OUTPUT (--json-output)")
+    json_demo = EnhancedLoggingExample(log_level="INFO", json_output=True)
+    json_demo.demonstrate_structured_logging()
+
+
+# Performance context manager for demonstration
+class MockPerformanceContext:
+    """Mock performance context for demonstration."""
+    
+    def __init__(self, operation_name: str):
+        self.operation_name = operation_name
+        self.metrics = {}
+        self.start_time = time.time()
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        duration = time.time() - self.start_time
+        print(f"Performance: {self.operation_name} completed in {duration:.3f}s")
+        if self.metrics:
+            print(f"Metrics: {self.metrics}")
+    
+    def add_metric(self, key: str, value: Any):
+        self.metrics[key] = value
+
+
+# Add performance context to logger class for demo
+EnhancedLoggingExample.logger_performance_context = lambda self, name: MockPerformanceContext(name)
+
+
+if __name__ == "__main__":
+    """Run the enhanced logging demonstration."""
+    demo_user_type_scenarios()