aws-inventory-manager 0.13.2__py3-none-any.whl

src/delta/reporter.py

@@ -0,0 +1,234 @@
+"""Delta report formatting and display."""
+
+from typing import Optional
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from ..models.delta_report import DeltaReport
+
+
+class DeltaReporter:
+    """Format and display delta reports."""
+
+    def __init__(self, console: Optional[Console] = None):
+        """Initialize delta reporter.
+
+        Args:
+            console: Rich console instance (creates new one if not provided)
+        """
+        self.console = console or Console()
+
+    def display(self, report: DeltaReport, show_details: bool = False) -> None:
+        """Display delta report to console.
+
+        Args:
+            report: DeltaReport to display
+            show_details: Whether to show detailed resource information
+        """
+        # Header
+        self.console.print()
+        self.console.print(
+            Panel(
+                f"[bold]Resource Delta Report[/bold]\n"
+                f"Reference Snapshot: {report.baseline_snapshot_name}\n"
+                f"Generated: {report.generated_at.strftime('%Y-%m-%d %H:%M:%S UTC')}",
+                style="cyan",
+            )
+        )
+        self.console.print()
+
+        # Check if there are any changes
+        if not report.has_changes:
+            self.console.print(
+                "[green]✓ No changes detected - environment matches reference snapshot[/green]", style="bold"
+            )
+            self.console.print()
+            self.console.print(f"Total resources: {report.baseline_resource_count}")
+            return
+
+        # Summary statistics
+        self._display_summary(report)
+
+        # Group changes by service
+        grouped = report.group_by_service()
+
+        # Display changes by service
+        for service_type in sorted(grouped.keys()):
+            changes = grouped[service_type]
+            if any(changes.values()):
+                self._display_service_changes(service_type, changes, show_details)
+
+        # Display drift details if available
+        if report.drift_report is not None and report.drift_report.total_changes > 0:
+            from .formatters import DriftFormatter
+
+            self.console.print()
+            self.console.print("[bold cyan]═" * 50 + "[/bold cyan]")
+            formatter = DriftFormatter(self.console)
+            formatter.display(report.drift_report)
+
+    def _display_summary(self, report: DeltaReport) -> None:
+        """Display summary statistics."""
+        table = Table(title="Summary", show_header=True, header_style="bold magenta")
+        table.add_column("Change Type", style="cyan", width=15)
+        table.add_column("Count", justify="right", style="yellow", width=10)
+
+        added_count = len(report.added_resources)
+        deleted_count = len(report.deleted_resources)
+        modified_count = len(report.modified_resources)
+        unchanged_count = report.unchanged_count
+
+        if added_count > 0:
+            table.add_row("➕ Added", f"[green]{added_count}[/green]")
+        if deleted_count > 0:
+            table.add_row("➖ Deleted", f"[red]{deleted_count}[/red]")
+        if modified_count > 0:
+            table.add_row("🔄 Modified", f"[yellow]{modified_count}[/yellow]")
+        if unchanged_count > 0:
+            table.add_row("✓ Unchanged", str(unchanged_count))
+
+        table.add_row("━" * 15, "━" * 10, style="dim")
+        table.add_row("[bold]Total Changes", f"[bold]{report.total_changes}")
+
+        self.console.print(table)
+        self.console.print()
+
+    def _display_service_changes(self, service_type: str, changes: dict, show_details: bool) -> None:
+        """Display changes for a specific service type.
+
+        Args:
+            service_type: AWS resource type (e.g., 'AWS::EC2::Instance')
+            changes: Dictionary with 'added', 'deleted', 'modified' lists
+            show_details: Whether to show detailed information
+        """
+        # Count total changes for this service
+        total = len(changes["added"]) + len(changes["deleted"]) + len(changes["modified"])
+        if total == 0:
+            return
+
+        self.console.print(f"[bold cyan]{service_type}[/bold cyan] ({total} changes)")
+
+        # Create table for this service
+        table = Table(show_header=True, box=None, padding=(0, 2))
+        table.add_column("Change", width=8)
+        table.add_column("Name", style="white")
+        table.add_column("Region", width=15)
+        table.add_column("ARN" if show_details else "Tags", style="dim")
+
+        # Added resources
+        for resource in changes["added"]:
+            tags_str = self._format_tags(resource.tags)
+            arn_or_tags = resource.arn if show_details else tags_str
+            table.add_row("[green]➕ Add[/green]", resource.name, resource.region, arn_or_tags)
+
+        # Deleted resources
+        for resource in changes["deleted"]:
+            tags_str = self._format_tags(resource.tags)
+            arn_or_tags = resource.arn if show_details else tags_str
+            table.add_row("[red]➖ Del[/red]", resource.name, resource.region, arn_or_tags)
+
+        # Modified resources
+        for change in changes["modified"]:
+            tags_str = self._format_tags(change.resource.tags)
+            arn_or_tags = change.resource.arn if show_details else tags_str
+            table.add_row("[yellow]🔄 Mod[/yellow]", change.resource.name, change.resource.region, arn_or_tags)
+
+        self.console.print(table)
+        self.console.print()
+
+    def _format_tags(self, tags: dict) -> str:
+        """Format tags dictionary as a string.
+
+        Args:
+            tags: Dictionary of tag key-value pairs
+
+        Returns:
+            Formatted string like "Env=prod, App=web"
+        """
+        if not tags:
+            return "-"
+
+        # Show up to 3 most important tags
+        important_keys = ["Name", "Environment", "Project", "Team", "Application"]
+        selected_tags = []
+
+        # First add important tags if present
+        for key in important_keys:
+            if key in tags:
+                selected_tags.append(f"{key}={tags[key]}")
+
+        # Add other tags up to limit
+        for key, value in tags.items():
+            if key not in important_keys and len(selected_tags) < 3:
+                selected_tags.append(f"{key}={value}")
+
+        return ", ".join(selected_tags[:3])
+
+    def export_json(self, report: DeltaReport, filepath: str) -> None:
+        """Export delta report to JSON file.
+
+        Args:
+            report: DeltaReport to export
+            filepath: Destination file path
+        """
+        from ..utils.export import export_to_json
+
+        export_to_json(report.to_dict(), filepath)
+        self.console.print(f"[green]✓ Delta report exported to {filepath}[/green]")
+
+    def export_csv(self, report: DeltaReport, filepath: str) -> None:
+        """Export delta report to CSV file.
+
+        Args:
+            report: DeltaReport to export
+            filepath: Destination file path
+        """
+        from ..utils.export import export_to_csv
+
+        # Flatten the report into rows
+        rows = []
+
+        for resource in report.added_resources:
+            rows.append(
+                {
+                    "change_type": "added",
+                    "resource_type": resource.resource_type,
+                    "name": resource.name,
+                    "arn": resource.arn,
+                    "region": resource.region,
+                    "tags": str(resource.tags),
+                    "created_at": resource.created_at.isoformat() if resource.created_at else None,
+                }
+            )
+
+        for resource in report.deleted_resources:
+            rows.append(
+                {
+                    "change_type": "deleted",
+                    "resource_type": resource.resource_type,
+                    "name": resource.name,
+                    "arn": resource.arn,
+                    "region": resource.region,
+                    "tags": str(resource.tags),
+                    "created_at": resource.created_at.isoformat() if resource.created_at else None,
+                }
+            )
+
+        for change in report.modified_resources:
+            rows.append(
+                {
+                    "change_type": "modified",
+                    "resource_type": change.resource.resource_type,
+                    "name": change.resource.name,
+                    "arn": change.resource.arn,
+                    "region": change.resource.region,
+                    "tags": str(change.resource.tags),
+                    "old_hash": change.old_config_hash,
+                    "new_hash": change.new_config_hash,
+                }
+            )
+
+        export_to_csv(rows, filepath)
+        self.console.print(f"[green]✓ Delta report exported to {filepath}[/green]")

src/models/__init__.py

@@ -0,0 +1,21 @@
+"""Data models for AWS Baseline Snapshot tool."""
+
+from .cost_report import CostBreakdown, CostReport
+from .delta_report import DeltaReport, ResourceChange
+from .group import GroupMember, ResourceGroup, extract_resource_name
+from .inventory import Inventory
+from .resource import Resource
+from .snapshot import Snapshot
+
+__all__ = [
+    "Snapshot",
+    "Resource",
+    "DeltaReport",
+    "ResourceChange",
+    "CostReport",
+    "CostBreakdown",
+    "Inventory",
+    "ResourceGroup",
+    "GroupMember",
+    "extract_resource_name",
+]

src/models/config_diff.py

@@ -0,0 +1,135 @@
+"""Configuration diff model for representing field-level changes between snapshots."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class ChangeCategory(Enum):
+    """Categories of configuration changes."""
+
+    TAGS = "tags"
+    CONFIGURATION = "configuration"
+    SECURITY = "security"
+    PERMISSIONS = "permissions"
+
+
+# Security-critical field patterns that should be flagged
+SECURITY_CRITICAL_FIELDS = {
+    "PubliclyAccessible",
+    "public",
+    "encryption",
+    "kms",
+    "SecurityGroups",
+    "IpPermissions",
+    "IpPermissionsEgress",
+    "Policy",
+    "BucketPolicy",
+    "Acl",
+    "HttpTokens",  # IMDSv2
+    "MetadataOptions",
+}
+
+
+@dataclass
+class ConfigDiff:
+    """Represents a field-level configuration change between two resource snapshots.
+
+    Attributes:
+        resource_arn: AWS ARN of the resource that changed
+        field_path: Dot-notation path to the changed field (e.g., "Tags.Environment")
+        old_value: Previous value of the field (None if field was added)
+        new_value: New value of the field (None if field was removed)
+        category: Category of the change (tags/configuration/security/permissions)
+    """
+
+    resource_arn: str
+    field_path: str
+    old_value: Any
+    new_value: Any
+    category: ChangeCategory
+
+    def __post_init__(self) -> None:
+        """Validate ConfigDiff fields after initialization."""
+        # Validate ARN format (basic check)
+        if not self.resource_arn or not self.resource_arn.startswith("arn:"):
+            raise ValueError(f"Invalid ARN format: {self.resource_arn}")
+
+        # Validate field_path is not empty
+        if not self.field_path:
+            raise ValueError("field_path cannot be empty")
+
+        # Validate category is ChangeCategory enum
+        if not isinstance(self.category, ChangeCategory):
+            raise ValueError(f"Invalid category type: {type(self.category)}. Must be ChangeCategory enum.")
+
+    def with_path_prefix(self, prefix: str) -> ConfigDiff:
+        """Create a new ConfigDiff with a prefix added to the field path.
+
+        Args:
+            prefix: Prefix to add to the field path
+
+        Returns:
+            New ConfigDiff instance with prefixed field path
+        """
+        return ConfigDiff(
+            resource_arn=self.resource_arn,
+            field_path=f"{prefix}.{self.field_path}",
+            old_value=self.old_value,
+            new_value=self.new_value,
+            category=self.category,
+        )
+
+    def is_security_critical(self) -> bool:
+        """Check if this configuration change affects security-related settings.
+
+        Returns:
+            True if the change is security-critical, False otherwise
+        """
+        # Check if field path contains any security-critical keywords
+        field_lower = self.field_path.lower()
+        return any(keyword.lower() in field_lower for keyword in SECURITY_CRITICAL_FIELDS)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert ConfigDiff to dictionary representation.
+
+        Returns:
+            Dictionary with all diff attributes
+        """
+        return {
+            "resource_arn": self.resource_arn,
+            "field_path": self.field_path,
+            "old_value": self.old_value,
+            "new_value": self.new_value,
+            "category": self.category.value,
+            "security_critical": self.is_security_critical(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ConfigDiff:
+        """Create ConfigDiff from dictionary representation.
+
+        Args:
+            data: Dictionary with diff attributes
+
+        Returns:
+            ConfigDiff instance
+
+        Raises:
+            ValueError: If category value is invalid
+        """
+        category_str = data.get("category", "").lower()
+        try:
+            category = ChangeCategory(category_str)
+        except ValueError:
+            raise ValueError(f"Invalid category value: {category_str}")
+
+        return cls(
+            resource_arn=data["resource_arn"],
+            field_path=data["field_path"],
+            old_value=data["old_value"],
+            new_value=data["new_value"],
+            category=category,
+        )

src/models/cost_report.py

@@ -0,0 +1,87 @@
+"""Cost report models for cost analysis and tracking."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class CostBreakdown:
+    """Represents cost breakdown for baseline or non-baseline resources."""
+
+    total: float
+    by_service: Dict[str, float] = field(default_factory=dict)
+    percentage: float = 0.0
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "total": self.total,
+            "by_service": self.by_service,
+            "percentage": self.percentage,
+        }
+
+
+@dataclass
+class CostReport:
+    """Represents cost analysis separating baseline vs non-baseline costs."""
+
+    generated_at: datetime
+    baseline_snapshot_name: str
+    period_start: datetime
+    period_end: datetime
+    baseline_costs: CostBreakdown
+    non_baseline_costs: CostBreakdown
+    total_cost: float
+    data_complete: bool = True
+    data_through: Optional[datetime] = None
+    lag_days: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "generated_at": self.generated_at.isoformat(),
+            "baseline_snapshot_name": self.baseline_snapshot_name,
+            "period_start": self.period_start.isoformat(),
+            "period_end": self.period_end.isoformat(),
+            "baseline_costs": self.baseline_costs.to_dict(),
+            "non_baseline_costs": self.non_baseline_costs.to_dict(),
+            "total_cost": self.total_cost,
+            "data_complete": self.data_complete,
+            "data_through": self.data_through.isoformat() if self.data_through else None,
+            "lag_days": self.lag_days,
+            "summary": {
+                "baseline_total": self.baseline_costs.total,
+                "baseline_percentage": self.baseline_costs.percentage,
+                "non_baseline_total": self.non_baseline_costs.total,
+                "non_baseline_percentage": self.non_baseline_costs.percentage,
+                "total": self.total_cost,
+            },
+        }
+
+    @property
+    def baseline_percentage(self) -> float:
+        """Get baseline cost percentage."""
+        return self.baseline_costs.percentage
+
+    @property
+    def non_baseline_percentage(self) -> float:
+        """Get non-baseline cost percentage."""
+        return self.non_baseline_costs.percentage
+
+    def get_top_services(self, limit: int = 5, baseline: bool = True) -> Dict[str, float]:
+        """Get top N services by cost.
+
+        Args:
+            limit: Number of top services to return
+            baseline: If True, return baseline services; if False, non-baseline
+
+        Returns:
+            Dictionary of service name to cost, sorted by cost descending
+        """
+        services = self.baseline_costs.by_service if baseline else self.non_baseline_costs.by_service
+
+        # Sort by cost descending
+        sorted_services = sorted(services.items(), key=lambda x: x[1], reverse=True)
+
+        return dict(sorted_services[:limit])

src/models/deletion_operation.py

@@ -0,0 +1,104 @@
+"""Deletion operation model.
+
+Represents a complete restore operation with metadata, filters, and execution context.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+
+class OperationMode(Enum):
+    """Operation execution mode."""
+
+    DRY_RUN = "dry-run"
+    EXECUTE = "execute"
+
+
+class OperationStatus(Enum):
+    """Operation execution status with state transitions."""
+
+    PLANNED = "planned"
+    EXECUTING = "executing"
+    COMPLETED = "completed"
+    PARTIAL = "partial"
+    FAILED = "failed"
+
+
+@dataclass
+class DeletionOperation:
+    """Deletion operation entity.
+
+    Represents a complete restore operation with metadata, filters, and execution
+    context. Tracks overall progress and status of resource deletion.
+
+    State transitions:
+        planned → executing → completed (all succeeded)
+        planned → executing → partial (some failed)
+        planned → executing → failed (critical error)
+
+    Attributes:
+        operation_id: Unique identifier for the operation
+        baseline_snapshot: Name of baseline snapshot to compare against
+        timestamp: When operation was initiated (ISO 8601 UTC)
+        account_id: AWS account ID (12-digit number)
+        mode: dry-run or execute
+        status: Current execution status
+        total_resources: Total resources identified for deletion
+        succeeded_count: Number successfully deleted (default: 0)
+        failed_count: Number that failed to delete (default: 0)
+        skipped_count: Number skipped due to protections (default: 0)
+        aws_profile: AWS profile used for credentials (optional)
+        filters: Resource type and region filters (optional)
+        started_at: When execution started (optional, execute mode only)
+        completed_at: When execution completed (optional)
+        duration_seconds: Total execution duration (optional)
+    """
+
+    operation_id: str
+    baseline_snapshot: str
+    timestamp: datetime
+    account_id: str
+    mode: OperationMode
+    status: OperationStatus
+    total_resources: int
+    succeeded_count: int = 0
+    failed_count: int = 0
+    skipped_count: int = 0
+    aws_profile: Optional[str] = None
+    filters: Optional[dict] = field(default=None)
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    duration_seconds: Optional[float] = None
+
+    def validate(self) -> bool:
+        """Validate operation invariants.
+
+        Validation rules:
+            - succeeded_count + failed_count + skipped_count == total_resources
+            - completed_at must be after started_at
+            - dry-run mode must have planned status
+
+        Returns:
+            True if validation passes
+
+        Raises:
+            ValueError: If any validation rule fails
+        """
+        # Count validation
+        if self.succeeded_count + self.failed_count + self.skipped_count != self.total_resources:
+            raise ValueError("Resource counts don't match total")
+
+        # Timing validation
+        if self.completed_at and self.started_at:
+            if self.completed_at < self.started_at:
+                raise ValueError("Completion time before start time")
+
+        # Mode/status consistency
+        if self.mode == OperationMode.DRY_RUN and self.status != OperationStatus.PLANNED:
+            raise ValueError("Dry-run mode must have planned status")
+
+        return True

src/models/deletion_record.py

@@ -0,0 +1,97 @@
+"""Deletion record model.
+
+Individual resource deletion attempt with result and metadata.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+
+class DeletionStatus(Enum):
+    """Individual resource deletion status."""
+
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+@dataclass
+class DeletionRecord:
+    """Deletion record entity.
+
+    Represents an individual resource deletion attempt with result and metadata.
+    Each record belongs to a DeletionOperation and tracks the outcome for a single
+    resource.
+
+    Validation rules:
+        - status=succeeded: no error_code or protection_reason
+        - status=failed: requires error_code
+        - status=skipped: requires protection_reason
+        - resource_arn must start with "arn:aws:"
+        - estimated_monthly_cost must be >= 0 if provided
+
+    Attributes:
+        record_id: Unique identifier for this record
+        operation_id: Parent operation identifier
+        resource_arn: AWS Resource Name (ARN format)
+        resource_id: Resource identifier (ID, name)
+        resource_type: AWS resource type (format: aws:service:type)
+        region: AWS region
+        timestamp: When deletion was attempted (ISO 8601 UTC)
+        status: Deletion outcome (succeeded, failed, skipped)
+        error_code: AWS error code if failed (optional)
+        error_message: Human-readable error if failed (optional)
+        protection_reason: Why resource was skipped (optional)
+        deletion_tier: Tier (1-5) for deletion ordering (optional)
+        tags: Resource tags at deletion time (optional)
+        estimated_monthly_cost: Estimated cost in USD (optional)
+    """
+
+    record_id: str
+    operation_id: str
+    resource_arn: str
+    resource_id: str
+    resource_type: str
+    region: str
+    timestamp: datetime
+    status: DeletionStatus
+    error_code: Optional[str] = None
+    error_message: Optional[str] = None
+    protection_reason: Optional[str] = None
+    deletion_tier: Optional[int] = None
+    tags: Optional[dict] = field(default=None)
+    estimated_monthly_cost: Optional[float] = None
+
+    def validate(self) -> bool:
+        """Validate record invariants.
+
+        Returns:
+            True if validation passes
+
+        Raises:
+            ValueError: If any validation rule fails
+        """
+        # Status-specific validation
+        if self.status == DeletionStatus.FAILED:
+            if not self.error_code:
+                raise ValueError("Failed status requires error_code")
+        elif self.status == DeletionStatus.SKIPPED:
+            if not self.protection_reason:
+                raise ValueError("Skipped status requires protection_reason")
+        elif self.status == DeletionStatus.SUCCEEDED:
+            if self.error_code or self.protection_reason:
+                raise ValueError("Succeeded status cannot have error or protection reason")
+
+        # ARN format validation
+        if not self.resource_arn.startswith("arn:aws:"):
+            raise ValueError("Invalid ARN format")
+
+        # Cost validation
+        if self.estimated_monthly_cost is not None and self.estimated_monthly_cost < 0:
+            raise ValueError("Cost cannot be negative")
+
+        return True