runbooks 1.1.7__py3-none-any.whl → 1.1.10__py3-none-any.whl

runbooks/common/config_schema.py

@@ -0,0 +1,280 @@
+"""
+Configuration schema validation for CloudOps Runbooks.
+
+Provides JSON Schema validation and business rules for hierarchical
+tag mapping configuration (user config > project config > env vars > defaults).
+
+This module defines the validation schema for runbooks configuration files,
+supporting hierarchical configuration loading with comprehensive validation
+rules for AWS tag mappings, coverage requirements, and caching behavior.
+
+Author: CloudOps-Runbooks Enterprise Team
+Version: 1.1.10
+"""
+
+from typing import Any, Dict, List
+
+# =============================================================================
+# JSON SCHEMA VALIDATION
+# =============================================================================
+
+TAG_MAPPING_SCHEMA: Dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "runbooks": {
+            "type": "object",
+            "properties": {
+                "version": {
+                    "type": "string",
+                    "pattern": r"^\d+\.\d+\.\d+$",  # Semantic versioning (e.g., '1.1.10')
+                    "description": "Config schema version following semantic versioning",
+                },
+                "inventory": {
+                    "type": "object",
+                    "properties": {
+                        "tag_mappings": {
+                            "type": "object",
+                            "description": "Maps internal field names to AWS tag keys",
+                            "patternProperties": {
+                                "^[a-z_]+$": {  # Field names: lowercase + underscores only
+                                    "type": "string",
+                                    "minLength": 1,
+                                    "maxLength": 128,  # AWS tag key maximum length
+                                    "description": "AWS tag key name (1-128 characters)",
+                                }
+                            },
+                            "additionalProperties": False,  # Strict validation - no unexpected fields
+                        },
+                        "tag_coverage": {
+                            "type": "object",
+                            "description": "Tag coverage analysis and reporting configuration",
+                            "properties": {
+                                "enabled": {
+                                    "type": "boolean",
+                                    "description": "Enable tag coverage analysis",
+                                },
+                                "minimum_tier1_coverage": {
+                                    "type": "number",
+                                    "minimum": 0.0,
+                                    "maximum": 100.0,
+                                    "description": "Minimum required coverage for Tier 1 tags (percentage)",
+                                },
+                                "minimum_tier2_coverage": {
+                                    "type": "number",
+                                    "minimum": 0.0,
+                                    "maximum": 100.0,
+                                    "description": "Minimum required coverage for Tier 2 tags (percentage)",
+                                },
+                                "display_recommendations": {
+                                    "type": "boolean",
+                                    "description": "Display tag coverage improvement recommendations",
+                                },
+                            },
+                        },
+                        "cache": {
+                            "type": "object",
+                            "description": "Inventory data caching configuration",
+                            "properties": {
+                                "enabled": {
+                                    "type": "boolean",
+                                    "description": "Enable inventory data caching",
+                                },
+                                "ttl_seconds": {
+                                    "type": "integer",
+                                    "minimum": 60,  # Minimum 1 minute
+                                    "maximum": 86400,  # Maximum 24 hours
+                                    "description": "Cache time-to-live in seconds (60-86400)",
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        }
+    },
+}
+
+
+# =============================================================================
+# BUSINESS RULES AND VALIDATION CONSTANTS
+# =============================================================================
+
+VALIDATION_RULES: Dict[str, Any] = {
+    # Allowed field names for tag_mappings configuration
+    # These field names follow the lowercase_with_underscores convention
+    "allowed_field_names": [
+        # TIER 1: Business Metadata (Critical for cost allocation and accountability)
+        "wbs_code",  # Work Breakdown Structure code for project tracking
+        "cost_group",  # Cost allocation group for financial reporting
+        "technical_lead",  # Technical point of contact
+        "account_owner",  # AWS account ownership
+        # TIER 2: Governance Metadata (Important for organizational structure)
+        "business_unit",  # Business unit or division
+        "functional_area",  # Functional area within organization
+        "managed_by",  # Management responsibility
+        "product_owner",  # Product ownership
+        # TIER 3: Operational Metadata (Standard operational requirements)
+        "purpose",  # Resource purpose or description
+        "environment",  # Environment classification (dev, staging, prod)
+        "compliance_scope",  # Compliance framework requirements
+        "data_classification",  # Data sensitivity classification
+        # TIER 4: Extended Metadata (Optional supplementary information)
+        "project_name",  # Project name or identifier
+        "budget_code",  # Budget allocation code
+        "support_tier",  # Support tier classification
+        "created_date",  # Resource creation date
+        "expiry_date",  # Resource expiration or review date
+    ],
+    # AWS reserved tag keys that cannot be used for custom mappings
+    "reserved_tag_keys": [
+        "Name",  # AWS reserved tag key
+        "aws:",  # AWS reserved prefix (check using startswith)
+    ],
+    # Tier definitions for coverage analysis and reporting
+    # Maps tier names to their constituent field names
+    "tier_definitions": {
+        "tier_1": [
+            "wbs_code",
+            "cost_group",
+            "technical_lead",
+            "account_owner",
+        ],
+        "tier_2": [
+            "business_unit",
+            "functional_area",
+            "managed_by",
+            "product_owner",
+        ],
+        "tier_3": [
+            "purpose",
+            "environment",
+            "compliance_scope",
+            "data_classification",
+        ],
+        "tier_4": [
+            "project_name",
+            "budget_code",
+            "support_tier",
+            "created_date",
+            "expiry_date",
+        ],
+    },
+}
+
+
+# =============================================================================
+# HELPER FUNCTIONS
+# =============================================================================
+
+
+def get_tier_for_field(field_name: str) -> str:
+    """
+    Determine the tier classification for a given field name.
+
+    Args:
+        field_name: The field name to classify (e.g., 'wbs_code', 'environment')
+
+    Returns:
+        Tier classification string ('tier_1', 'tier_2', 'tier_3', 'tier_4', or 'unknown')
+
+    Example:
+        >>> get_tier_for_field('wbs_code')
+        'tier_1'
+        >>> get_tier_for_field('environment')
+        'tier_3'
+    """
+    for tier_name, tier_fields in VALIDATION_RULES["tier_definitions"].items():
+        if field_name in tier_fields:
+            return tier_name
+    return "unknown"
+
+
+def is_reserved_tag_key(tag_key: str) -> bool:
+    """
+    Check if a tag key is reserved by AWS and cannot be used for custom mappings.
+
+    Reserved tag keys include:
+    - 'Name' (AWS standard tag)
+    - Any key starting with 'aws:' (AWS system tags)
+
+    Args:
+        tag_key: The AWS tag key to validate
+
+    Returns:
+        True if the tag key is reserved, False otherwise
+
+    Example:
+        >>> is_reserved_tag_key('Name')
+        True
+        >>> is_reserved_tag_key('aws:cloudformation:stack-name')
+        True
+        >>> is_reserved_tag_key('CostCenter')
+        False
+    """
+    reserved_keys = VALIDATION_RULES["reserved_tag_keys"]
+    if tag_key in reserved_keys:
+        return True
+    # Check for aws: prefix
+    if tag_key.startswith("aws:"):
+        return True
+    return False
+
+
+def get_allowed_field_names() -> List[str]:
+    """
+    Get the complete list of allowed field names for tag mappings.
+
+    Returns:
+        List of allowed field names across all tiers
+
+    Example:
+        >>> fields = get_allowed_field_names()
+        >>> 'wbs_code' in fields
+        True
+        >>> len(fields) > 0
+        True
+    """
+    return VALIDATION_RULES["allowed_field_names"]
+
+
+def validate_field_name_format(field_name: str) -> bool:
+    """
+    Validate that a field name follows the required format.
+
+    Field names must:
+    - Use lowercase letters only
+    - Use underscores for word separation
+    - Match pattern: ^[a-z_]+$
+
+    Args:
+        field_name: The field name to validate
+
+    Returns:
+        True if field name format is valid, False otherwise
+
+    Example:
+        >>> validate_field_name_format('wbs_code')
+        True
+        >>> validate_field_name_format('WBS_Code')
+        False
+        >>> validate_field_name_format('wbs-code')
+        False
+    """
+    import re
+
+    pattern = r"^[a-z_]+$"
+    return bool(re.match(pattern, field_name))
+
+
+# =============================================================================
+# MODULE METADATA
+# =============================================================================
+
+__all__ = [
+    "TAG_MAPPING_SCHEMA",
+    "VALIDATION_RULES",
+    "get_tier_for_field",
+    "is_reserved_tag_key",
+    "get_allowed_field_names",
+    "validate_field_name_format",
+]

runbooks/common/dry_run_framework.py

@@ -110,6 +110,12 @@ class DryRunSafetyFramework:
                 "simulation_mode": False,
                 "warning_message": None,
             },
+            OperationType.REPORTING: {
+                "default_dry_run": False,  # Reporting is read-only
+                "requires_confirmation": False,
+                "simulation_mode": False,  # Real API calls for report generation
+                "warning_message": None,
+            },
             OperationType.RESOURCE_CREATE: {
                 "default_dry_run": True,  # Safety-first for resource creation
                 "requires_confirmation": True,
@@ -128,6 +134,12 @@ class DryRunSafetyFramework:
                 "simulation_mode": True,
                 "warning_message": "🚨 RESOURCE DELETION: This will permanently delete AWS resources",
             },
+            OperationType.CONFIGURATION: {
+                "default_dry_run": True,  # Safety-first for configuration changes
+                "requires_confirmation": True,
+                "simulation_mode": True,
+                "warning_message": "⚙️  CONFIGURATION CHANGE: This will modify settings and policies",
+            },
             OperationType.REMEDIATION: {
                 "default_dry_run": True,  # Safety-first for remediation
                 "requires_confirmation": True,
@@ -323,7 +335,7 @@ class DryRunSafetyFramework:
         log_entry = {
             "mode": mode,
             "operation_type": context.operation_type.value,
-            "module": context.module_name,
+            "operation_module": context.module_name,
             "operation": context.operation_name,
             "target_count": len(context.target_resources),
             "safety_level": context.safety_level,
@@ -386,7 +398,7 @@ class DryRunSafetyFramework:
         self.logger.info(
             f"DryRun {event}",
             extra={
-                "module": context.module_name,
+                "operation_module": context.module_name,
                 "operation": context.operation_name,
                 "dry_run": context.enabled,
                 **data,

runbooks/common/mcp_integration.py

@@ -64,6 +64,51 @@ from runbooks.common.rich_utils import (
 )
 
 
+# Custom Exception Hierarchy for MCP Validation
+class MCPValidationError(Exception):
+    """Base exception for MCP validation errors."""
+    pass
+
+
+class MCPTypeError(MCPValidationError):
+    """Raised when MCP client has incorrect type."""
+
+    def __init__(self, expected_type: str, actual_type: str, remediation: str):
+        self.expected_type = expected_type
+        self.actual_type = actual_type
+        self.remediation = remediation
+        super().__init__(
+            f"MCP client type error: Expected {expected_type}, got {actual_type}. "
+            f"Remediation: {remediation}"
+        )
+
+
+class MCPAccuracyError(MCPValidationError):
+    """Raised when MCP accuracy falls below threshold."""
+
+    def __init__(self, accuracy: float, threshold: float, mismatched_fields: List[str]):
+        self.accuracy = accuracy
+        self.threshold = threshold
+        self.mismatched_fields = mismatched_fields
+        super().__init__(
+            f"MCP accuracy {accuracy:.2f}% below threshold {threshold:.2f}%. "
+            f"Mismatched fields: {', '.join(mismatched_fields)}. "
+            f"Remediation: Check MCP server version compatibility with boto3."
+        )
+
+
+class MCPConnectionError(MCPValidationError):
+    """Raised when MCP server connection fails."""
+
+    def __init__(self, server_name: str, error_details: str):
+        self.server_name = server_name
+        self.error_details = error_details
+        super().__init__(
+            f"MCP server '{server_name}' connection failed: {error_details}. "
+            f"Remediation: Verify MCP server running via 'uvx {server_name}@latest --version'."
+        )
+
+
 class MCPOperationType(Enum):
     """MCP operation types for different modules."""
 
@@ -181,6 +226,195 @@ class EnterpriseMCPIntegrator:
             except Exception as e:
                 print_error(f"Failed to initialize {profile_type} profile: {str(e)}")
 
+    def _validate_boto3_client(self, client: Any, required_method: str = 'get_caller_identity') -> bool:
+        """
+        Defensive type checking for boto3 clients - prevents type confusion.
+
+        Historical Context:
+        - Oct 4, 2025: Type confusion incident (dicts passed instead of clients)
+        - Reported accuracy: 99.8% | True accuracy: 0.0%
+        - Root cause: AttributeError on dict.get_caller_identity() caught silently
+
+        Args:
+            client: Object to validate (should be boto3 client)
+            required_method: Method that must exist on client
+
+        Returns:
+            bool: True if valid client
+
+        Raises:
+            MCPTypeError: If client is not a boto3 client or lacks required method
+
+        Reference: @.claude/lessons-learned/quality-gate-violations.md lines 30-51
+        """
+        # CRITICAL: Check if it's a dict (common historical mistake)
+        if isinstance(client, dict):
+            raise MCPTypeError(
+                expected_type="boto3.client.BaseClient",
+                actual_type="dict",
+                remediation="Use session.client('service_name') to create proper boto3 client"
+            )
+
+        # Check if it's a string
+        if isinstance(client, str):
+            raise MCPTypeError(
+                expected_type="boto3.client.BaseClient",
+                actual_type="str",
+                remediation=f"String '{client}' is a service name. Use session.client('{client}') to create client"
+            )
+
+        # Verify it's a boto3 client
+        try:
+            import botocore.client
+            if not isinstance(client, botocore.client.BaseClient):
+                raise MCPTypeError(
+                    expected_type="boto3.client.BaseClient",
+                    actual_type=type(client).__name__,
+                    remediation="Ensure you're passing a valid boto3 client object"
+                )
+        except ImportError:
+            # Fallback if botocore not available (shouldn't happen in production)
+            print_warning("botocore not available for type checking - using hasattr check only")
+
+        # Check if it has required method
+        if not hasattr(client, required_method):
+            raise AttributeError(
+                f"Client {type(client).__name__} missing required method '{required_method}'. "
+                f"Remediation: Use correct service name for intended operation."
+            )
+
+        return True
+
+    def calculate_true_accuracy(
+        self,
+        mcp_result: Dict[str, Any],
+        boto3_result: Dict[str, Any],
+        comparison_fields: List[str]
+    ) -> float:
+        """
+        Calculate true accuracy by comparing MCP vs native boto3 results.
+
+        Historical Context:
+        - October 4, 2025: Reported 99.8% accuracy was actually 0.0%
+        - Root cause: No cross-validation against boto3 responses
+        - This method prevents recurrence via field-by-field comparison
+
+        Args:
+            mcp_result: Result from MCP server API call
+            boto3_result: Result from native boto3 API call
+            comparison_fields: Fields to compare for accuracy
+
+        Returns:
+            Accuracy percentage (0.0 to 100.0)
+
+        Raises:
+            ValueError: If results cannot be compared
+        """
+        from decimal import Decimal
+
+        # Validate both results are dicts
+        if not isinstance(mcp_result, dict) or not isinstance(boto3_result, dict):
+            raise ValueError(
+                f"Cannot compare accuracy: MCP result type={type(mcp_result).__name__}, "
+                f"boto3 result type={type(boto3_result).__name__}"
+            )
+
+        # Compare each field
+        total_fields = len(comparison_fields)
+        matching_fields = 0
+
+        for field in comparison_fields:
+            mcp_value = mcp_result.get(field)
+            boto3_value = boto3_result.get(field)
+
+            # Handle Decimal precision for financial values
+            if isinstance(mcp_value, (float, Decimal)) and isinstance(boto3_value, (float, Decimal)):
+                mcp_decimal = Decimal(str(mcp_value))
+                boto3_decimal = Decimal(str(boto3_value))
+                # ±0.01% tolerance for financial accuracy
+                tolerance = boto3_decimal * Decimal('0.0001')
+                if abs(mcp_decimal - boto3_decimal) <= tolerance:
+                    matching_fields += 1
+            else:
+                # Exact match for non-financial fields
+                if mcp_value == boto3_value:
+                    matching_fields += 1
+
+        # Calculate accuracy
+        accuracy = (matching_fields / total_fields) * 100.0 if total_fields > 0 else 0.0
+
+        return accuracy
+
+    async def validate_with_cross_check(
+        self,
+        operation: str,
+        mcp_client: Any,
+        boto3_client: Any,
+        params: Dict[str, Any],
+        comparison_fields: List[str]
+    ) -> Dict[str, Any]:
+        """
+        Execute operation via both MCP and boto3, calculate accuracy.
+
+        Args:
+            operation: API operation to execute (e.g., 'get_cost_and_usage')
+            mcp_client: MCP client instance
+            boto3_client: Native boto3 client for cross-validation
+            params: Parameters for API operation
+            comparison_fields: Fields to compare between MCP and boto3 results
+
+        Returns:
+            {
+                'mcp_result': {...},
+                'boto3_result': {...},
+                'accuracy': 99.7,
+                'threshold_met': True,  # ≥99.5%
+                'field_matches': ['field1', 'field2'],
+                'field_mismatches': []
+            }
+        """
+        # Validate clients
+        self._validate_boto3_client(boto3_client)
+
+        # Execute via MCP
+        mcp_method = getattr(mcp_client, operation)
+        if asyncio.iscoroutinefunction(mcp_method):
+            mcp_result = await mcp_method(**params)
+        else:
+            mcp_result = mcp_method(**params)
+
+        # Execute via boto3
+        boto3_method = getattr(boto3_client, operation)
+        boto3_result = boto3_method(**params)
+
+        # Calculate accuracy
+        accuracy = self.calculate_true_accuracy(
+            mcp_result,
+            boto3_result,
+            comparison_fields
+        )
+
+        # Identify matching and mismatching fields
+        matches = []
+        mismatches = []
+        for field in comparison_fields:
+            mcp_value = mcp_result.get(field)
+            boto3_value = boto3_result.get(field)
+            if mcp_value == boto3_value:
+                matches.append(field)
+            else:
+                mismatches.append(field)
+
+        return {
+            'mcp_result': mcp_result,
+            'boto3_result': boto3_result,
+            'accuracy': accuracy,
+            'threshold_met': accuracy >= 99.5,
+            'comparison_fields': comparison_fields,
+            'matches': matches,
+            'mismatches': mismatches
+        }
+
     def _is_organizations_cache_valid(self) -> bool:
         """Check if Organizations cache is still valid."""
         if not self._organizations_cache_timestamp:
@@ -786,4 +1020,8 @@ __all__ = [
     "EnterpriseMCPIntegrator",
     "MCPOperationType",
     "MCPValidationResult",
+    "MCPValidationError",
+    "MCPTypeError",
+    "MCPAccuracyError",
+    "MCPConnectionError",
 ]

runbooks/finops/ebs_cost_optimizer.py

@@ -976,11 +976,14 @@ class EBSCostOptimizer:
 @click.option("--regions", multiple=True, help="AWS regions to analyze (space-separated)")
 @click.option("--dry-run/--no-dry-run", default=True, help="Execute in dry-run mode (READ-ONLY analysis)")
 @click.option(
-    "--export-format", type=click.Choice(["json", "csv", "markdown"]), default="json", help="Export format for results"
+    "-f", "--format", "--export-format",
+    type=click.Choice(["json", "csv", "markdown"]),
+    default="json",
+    help="Export format for results (-f/--format preferred, --export-format legacy)"
 )
 @click.option("--output-file", help="Output file path for results export")
 @click.option("--usage-threshold-days", type=int, default=7, help="CloudWatch analysis period in days")
-def ebs_optimizer(profile, regions, dry_run, export_format, output_file, usage_threshold_days):
+def ebs_optimizer(profile, regions, dry_run, format, output_file, usage_threshold_days):
     """
     EBS Volume Optimizer - Enterprise Multi-Region Storage Analysis
 
@@ -1006,8 +1009,8 @@ def ebs_optimizer(profile, regions, dry_run, export_format, output_file, usage_t
         results = asyncio.run(optimizer.analyze_ebs_volumes(dry_run=dry_run))
 
         # Export results if requested
-        if output_file or export_format != "json":
-            optimizer.export_results(results, output_file, export_format)
+        if output_file or format != "json":
+            optimizer.export_results(results, output_file, format)
 
         # Display final success message
         if results.total_potential_annual_savings > 0:

runbooks/finops/elastic_ip_optimizer.py

@@ -692,10 +692,13 @@ class ElasticIPOptimizer:
 @click.option("--regions", multiple=True, help="AWS regions to analyze (space-separated)")
 @click.option("--dry-run/--no-dry-run", default=True, help="Execute in dry-run mode (READ-ONLY analysis)")
 @click.option(
-    "--export-format", type=click.Choice(["json", "csv", "markdown"]), default="json", help="Export format for results"
+    "-f", "--format", "--export-format",
+    type=click.Choice(["json", "csv", "markdown"]),
+    default="json",
+    help="Export format for results (-f/--format preferred, --export-format legacy)"
 )
 @click.option("--output-file", help="Output file path for results export")
-def elastic_ip_optimizer(profile, regions, dry_run, export_format, output_file):
+def elastic_ip_optimizer(profile, regions, dry_run, format, output_file):
     """
     Elastic IP Cost Optimizer - Enterprise Multi-Region Analysis
 
@@ -716,8 +719,8 @@ def elastic_ip_optimizer(profile, regions, dry_run, export_format, output_file):
         results = asyncio.run(optimizer.analyze_elastic_ips(dry_run=dry_run))
 
         # Export results if requested
-        if output_file or export_format != "json":
-            optimizer.export_results(results, output_file, export_format)
+        if output_file or format != "json":
+            optimizer.export_results(results, output_file, format)
 
         # Display final success message
         if results.potential_annual_savings > 0:

runbooks/finops/infrastructure/__init__.py

@@ -73,8 +73,9 @@ EPIC_2_TARGETS = {
     "total": 210147.0,
 }
 
-# Module metadata
-__version__ = "1.1.5"
+# Module metadata - version imported from central source
+from runbooks import __version__
+
 __epic__ = "Epic 2 Infrastructure Optimization"
 __target_savings__ = "$210,147 annual"
 __status__ = "Production Ready"

runbooks/finops/infrastructure/commands.py

@@ -358,10 +358,13 @@ def infrastructure():
 )
 @click.option("--dry-run/--no-dry-run", default=True, help="Execute in dry-run mode (READ-ONLY analysis)")
 @click.option(
-    "--export-format", type=click.Choice(["json", "csv", "markdown"]), default="json", help="Export format for results"
+    "-f", "--format", "--export-format",
+    type=click.Choice(["json", "csv", "markdown"]),
+    default="json",
+    help="Export format for results (-f/--format preferred, --export-format legacy)"
 )
 @click.option("--output-file", help="Output file path for results export")
-def analyze(profile, regions, components, dry_run, export_format, output_file):
+def analyze(profile, regions, components, dry_run, format, output_file):
     """
     Comprehensive Infrastructure Optimization Analysis - Epic 2
 
@@ -391,8 +394,8 @@ def analyze(profile, regions, components, dry_run, export_format, output_file):
         )
 
         # Export results if requested (implementation would go here)
-        if output_file or export_format != "json":
-            print_info(f"Export functionality available - results ready for {export_format} export")
+        if output_file or format != "json":
+            print_info(f"Export functionality available - results ready for {format} export")
 
         # Display final success message
         if results.epic_2_target_achieved: