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

src/models/inventory.py

@@ -0,0 +1,133 @@
+"""Inventory model for organizing snapshots by account and purpose."""
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Inventory:
+    """Named container for organizing snapshots by account and purpose.
+
+    Attributes:
+        name: Unique identifier within account (alphanumeric + hyphens + underscores, 1-50 chars)
+        account_id: AWS account ID (12 digits)
+        include_tags: Tag filters (resource MUST have ALL)
+        exclude_tags: Tag filters (resource MUST NOT have ANY)
+        snapshots: List of snapshot filenames in this inventory
+        active_snapshot: Filename of active baseline snapshot
+        description: Human-readable description
+        created_at: Inventory creation timestamp (timezone-aware UTC)
+        last_updated: Last modification timestamp (timezone-aware UTC, auto-updated)
+    """
+
+    name: str
+    account_id: str
+    include_tags: Dict[str, str] = field(default_factory=dict)
+    exclude_tags: Dict[str, str] = field(default_factory=dict)
+    snapshots: List[str] = field(default_factory=list)
+    active_snapshot: Optional[str] = None
+    description: str = ""
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    last_updated: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to dictionary for YAML storage.
+
+        Returns:
+            Dictionary representation suitable for YAML serialization
+        """
+        return {
+            "name": self.name,
+            "account_id": self.account_id,
+            "description": self.description,
+            "include_tags": self.include_tags,
+            "exclude_tags": self.exclude_tags,
+            "snapshots": self.snapshots,
+            "active_snapshot": self.active_snapshot,
+            "created_at": self.created_at.isoformat(),
+            "last_updated": self.last_updated.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Inventory":
+        """Deserialize from dictionary (YAML load).
+
+        Args:
+            data: Dictionary loaded from YAML
+
+        Returns:
+            Inventory instance
+        """
+        # Handle datetime fields being either string or datetime (PyYAML can auto-parse)
+        created_at = data["created_at"]
+        if isinstance(created_at, str):
+            created_at = datetime.fromisoformat(created_at)
+
+        last_updated = data["last_updated"]
+        if isinstance(last_updated, str):
+            last_updated = datetime.fromisoformat(last_updated)
+
+        return cls(
+            name=data["name"],
+            account_id=data["account_id"],
+            description=data.get("description", ""),
+            include_tags=data.get("include_tags", {}),
+            exclude_tags=data.get("exclude_tags", {}),
+            snapshots=data.get("snapshots", []),
+            active_snapshot=data.get("active_snapshot"),
+            created_at=created_at,
+            last_updated=last_updated,
+        )
+
+    def add_snapshot(self, snapshot_filename: str, set_active: bool = False) -> None:
+        """Add snapshot to inventory, optionally marking as active.
+
+        Args:
+            snapshot_filename: Name of snapshot file to add
+            set_active: Whether to mark this snapshot as active baseline
+        """
+        if snapshot_filename not in self.snapshots:
+            self.snapshots.append(snapshot_filename)
+        if set_active:
+            self.active_snapshot = snapshot_filename
+        self.last_updated = datetime.now(timezone.utc)
+
+    def remove_snapshot(self, snapshot_filename: str) -> None:
+        """Remove snapshot from inventory, clearing active if it was active.
+
+        Args:
+            snapshot_filename: Name of snapshot file to remove
+        """
+        if snapshot_filename in self.snapshots:
+            self.snapshots.remove(snapshot_filename)
+        if self.active_snapshot == snapshot_filename:
+            self.active_snapshot = None
+        self.last_updated = datetime.now(timezone.utc)
+
+    def validate(self) -> List[str]:
+        """Validate inventory data, return list of errors.
+
+        Returns:
+            List of validation error messages (empty if valid)
+        """
+        errors = []
+
+        # Validate name format (alphanumeric + hyphens + underscores only)
+        if not self.name or not re.match(r"^[a-zA-Z0-9_-]+$", self.name):
+            errors.append("Name must contain only alphanumeric characters, hyphens, and underscores")
+
+        # Validate name length
+        if len(self.name) > 50:
+            errors.append("Name must be 50 characters or less")
+
+        # Validate account ID format (12 digits)
+        if not self.account_id or not re.match(r"^\d{12}$", self.account_id):
+            errors.append("Account ID must be 12 digits")
+
+        # Validate active snapshot exists in snapshots list
+        if self.active_snapshot and self.active_snapshot not in self.snapshots:
+            errors.append("Active snapshot must exist in snapshots list")
+
+        return errors

src/models/protection_rule.py

@@ -0,0 +1,123 @@
+"""Protection rule model.
+
+Configuration defining which resources should never be deleted.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class RuleType(Enum):
+    """Protection rule type."""
+
+    TAG = "tag"
+    TYPE = "type"
+    AGE = "age"
+    COST = "cost"
+    NATIVE = "native"
+
+
+@dataclass
+class ProtectionRule:
+    """Protection rule entity.
+
+    Configuration defining which resources should never be deleted. Rules are
+    evaluated against resources before deletion, with higher priority rules
+    taking precedence.
+
+    Rule types and patterns:
+        - TAG: Match resources by tag key/value
+            patterns: {tag_key: str, tag_values: list, match_mode: str}
+        - TYPE: Match resources by AWS type
+            patterns: {resource_types: list, match_mode: str}
+        - AGE: Protect resources younger than threshold
+            patterns: {environment: str}, threshold_value: days
+        - COST: Protect resources exceeding cost threshold
+            patterns: {action: str}, threshold_value: USD/month
+        - NATIVE: Check AWS native protection flags
+            patterns: {protection_types: list}
+
+    Validation rules:
+        - patterns cannot be empty
+        - priority must be 1-100
+        - AGE and COST rules require threshold_value >= 0
+
+    Attributes:
+        rule_id: Unique identifier
+        rule_type: Rule type (tag, type, age, cost, native)
+        enabled: Whether rule is active
+        priority: Rule precedence (1=highest)
+        patterns: Type-specific match patterns
+        threshold_value: Numeric threshold for age/cost rules (optional)
+        description: Human-readable explanation (optional)
+    """
+
+    rule_id: str
+    rule_type: RuleType
+    enabled: bool
+    priority: int
+    patterns: dict = field(default_factory=dict)
+    threshold_value: Optional[float] = None
+    description: Optional[str] = None
+
+    def validate(self) -> bool:
+        """Validate rule configuration.
+
+        Returns:
+            True if validation passes
+
+        Raises:
+            ValueError: If any validation rule fails
+        """
+        # Threshold requirements
+        if self.rule_type in [RuleType.AGE, RuleType.COST]:
+            if self.threshold_value is None or self.threshold_value < 0:
+                raise ValueError(f"{self.rule_type.value} rule requires positive threshold")
+
+        # Pattern validation
+        if not self.patterns:
+            raise ValueError("Patterns cannot be empty")
+
+        # Priority range
+        if not (1 <= self.priority <= 100):
+            raise ValueError("Priority must be 1-100")
+
+        return True
+
+    def matches(self, resource: dict) -> bool:
+        """Check if resource matches this rule.
+
+        Args:
+            resource: Resource metadata dictionary
+
+        Returns:
+            True if resource matches this protection rule
+        """
+        if not self.enabled:
+            return False
+
+        if self.rule_type == RuleType.TAG:
+            tag_key = self.patterns.get("tag_key")
+            tag_values = self.patterns.get("tag_values", [])
+            resource_tag_value = resource.get("tags", {}).get(tag_key)
+            return resource_tag_value in tag_values
+
+        elif self.rule_type == RuleType.TYPE:
+            resource_types = self.patterns.get("resource_types", [])
+            return resource.get("resource_type") in resource_types
+
+        elif self.rule_type == RuleType.AGE:
+            resource_age_days = resource.get("age_days", 0)
+            return resource_age_days < self.threshold_value
+
+        elif self.rule_type == RuleType.COST:
+            resource_cost = resource.get("estimated_monthly_cost", 0)
+            return resource_cost >= self.threshold_value
+
+        elif self.rule_type == RuleType.NATIVE:
+            return resource.get("has_native_protection", False)
+
+        return False

src/models/report.py

@@ -0,0 +1,288 @@
+"""
+Data models for snapshot resource reporting.
+
+This module defines the data structures used for generating and displaying
+snapshot resource reports, including metadata, summaries, filtered views,
+and detailed resource information.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Dict, List, Literal, Optional, Tuple
+
+
+@dataclass
+class SnapshotMetadata:
+    """
+    Snapshot identification information for report header.
+
+    Attributes:
+        name: Snapshot name (e.g., "baseline-2025-01-29")
+        created_at: Snapshot creation timestamp
+        account_id: AWS account ID
+        regions: List of AWS regions included in snapshot
+        inventory_name: Parent inventory name
+        total_resource_count: Total number of resources in snapshot
+    """
+
+    name: str
+    created_at: datetime
+    account_id: str
+    regions: List[str]
+    inventory_name: str
+    total_resource_count: int
+
+    @property
+    def region_summary(self) -> str:
+        """Human-readable region list (e.g., 'us-east-1, us-west-2 (2 regions)')."""
+        if len(self.regions) <= 3:
+            return ", ".join(self.regions)
+        else:
+            return f"{', '.join(self.regions[:3])} ... ({len(self.regions)} regions)"
+
+
+@dataclass
+class ResourceSummary:
+    """
+    Aggregated resource counts for summary view.
+
+    Attributes:
+        total_count: Total number of resources
+        by_service: Count per AWS service (e.g., {"EC2": 100, "S3": 50})
+        by_region: Count per AWS region (e.g., {"us-east-1": 80, "us-west-2": 70})
+        by_type: Count per resource type (e.g., {"AWS::EC2::Instance": 50})
+    """
+
+    total_count: int = 0
+    by_service: Dict[str, int] = field(default_factory=dict)
+    by_region: Dict[str, int] = field(default_factory=dict)
+    by_type: Dict[str, int] = field(default_factory=dict)
+
+    @property
+    def service_count(self) -> int:
+        """Number of distinct AWS services."""
+        return len(self.by_service)
+
+    @property
+    def region_count(self) -> int:
+        """Number of distinct AWS regions."""
+        return len(self.by_region)
+
+    @property
+    def type_count(self) -> int:
+        """Number of distinct resource types."""
+        return len(self.by_type)
+
+    def top_services(self, limit: int = 5) -> List[Tuple[str, int]]:
+        """Return top N services by resource count."""
+        return sorted(self.by_service.items(), key=lambda x: x[1], reverse=True)[:limit]
+
+    def top_regions(self, limit: int = 5) -> List[Tuple[str, int]]:
+        """Return top N regions by resource count."""
+        return sorted(self.by_region.items(), key=lambda x: x[1], reverse=True)[:limit]
+
+
+@dataclass
+class FilteredResource:
+    """
+    Minimal resource info for filtered view (non-detailed).
+
+    Attributes:
+        arn: AWS Resource Name (unique identifier)
+        resource_type: CloudFormation resource type (e.g., "AWS::EC2::Instance")
+        name: Resource name or identifier
+        region: AWS region (e.g., "us-east-1")
+    """
+
+    arn: str
+    resource_type: str
+    name: str
+    region: str
+
+    @property
+    def service(self) -> str:
+        """Extract service name from resource type (e.g., "EC2" from "AWS::EC2::Instance")."""
+        parts = self.resource_type.split("::")
+        return parts[1] if len(parts) >= 2 else "Unknown"
+
+    @property
+    def short_type(self) -> str:
+        """Short resource type (e.g., "Instance" from "AWS::EC2::Instance")."""
+        parts = self.resource_type.split("::")
+        return parts[-1] if parts else self.resource_type
+
+
+@dataclass
+class DetailedResource:
+    """
+    Full resource details for detailed view.
+
+    Attributes:
+        arn: AWS Resource Name
+        resource_type: CloudFormation resource type
+        name: Resource name or identifier
+        region: AWS region
+        tags: Key-value tag pairs
+        created_at: Resource creation timestamp (if available)
+        config_hash: Configuration hash for change detection
+    """
+
+    arn: str
+    resource_type: str
+    name: str
+    region: str
+    tags: Dict[str, str]
+    created_at: Optional[datetime]
+    config_hash: str
+
+    @property
+    def service(self) -> str:
+        """Extract service name from resource type."""
+        parts = self.resource_type.split("::")
+        return parts[1] if len(parts) >= 2 else "Unknown"
+
+    @property
+    def age_days(self) -> Optional[int]:
+        """Calculate resource age in days (if creation date available)."""
+        if self.created_at:
+            from datetime import timezone
+
+            # Handle string dates (convert to datetime)
+            created_at = self.created_at
+            if isinstance(created_at, str):
+                try:
+                    created_at = datetime.fromisoformat(created_at.replace("Z", "+00:00"))
+                except ValueError:
+                    return None
+
+            # Ensure we have a datetime object
+            if not isinstance(created_at, datetime):
+                return None
+
+            # Ensure we're comparing timezone-aware datetimes
+            now_utc = datetime.now(timezone.utc)
+            created = created_at if created_at.tzinfo else created_at.replace(tzinfo=timezone.utc)
+            return (now_utc - created).days
+        return None
+
+    @property
+    def tag_count(self) -> int:
+        """Number of tags applied to resource."""
+        return len(self.tags)
+
+    def has_tag(self, key: str, value: Optional[str] = None) -> bool:
+        """Check if resource has specific tag (optionally with value)."""
+        if key not in self.tags:
+            return False
+        if value is not None:
+            return self.tags[key] == value
+        return True
+
+
+@dataclass
+class FilterCriteria:
+    """
+    Filter specification for narrowing report results.
+
+    Attributes:
+        resource_types: List of resource types to include (flexible matching)
+        regions: List of AWS regions to include (exact matching)
+        match_mode: Matching strategy ("flexible" or "exact")
+    """
+
+    resource_types: Optional[List[str]] = None
+    regions: Optional[List[str]] = None
+    match_mode: Literal["flexible", "exact"] = "flexible"
+
+    def __post_init__(self) -> None:
+        """Normalize filter values (lowercase for case-insensitive matching)."""
+        if self.resource_types:
+            self.resource_types = [rt.lower() for rt in self.resource_types]
+        if self.regions:
+            self.regions = [r.lower() for r in self.regions]
+
+    @property
+    def has_filters(self) -> bool:
+        """Check if any filters are applied."""
+        return bool(self.resource_types or self.regions)
+
+    @property
+    def filter_count(self) -> int:
+        """Total number of filter criteria."""
+        count = 0
+        if self.resource_types:
+            count += len(self.resource_types)
+        if self.regions:
+            count += len(self.regions)
+        return count
+
+    def matches_resource(self, resource: FilteredResource) -> bool:
+        """
+        Check if resource matches filter criteria.
+
+        Uses flexible matching for resource types (see research.md Task 2).
+        Uses exact matching for regions (case-insensitive).
+        """
+        # Region filter (exact match, case-insensitive)
+        if self.regions and resource.region.lower() not in self.regions:
+            return False
+
+        # Resource type filter (flexible matching)
+        if self.resource_types:
+            type_match = any(
+                self._match_resource_type(resource.resource_type, filter_type) for filter_type in self.resource_types
+            )
+            if not type_match:
+                return False
+
+        return True
+
+    def _match_resource_type(self, resource_type: str, filter_value: str) -> bool:
+        """Three-tier matching: exact → prefix → contains (see research.md)."""
+        resource_lower = resource_type.lower()
+        filter_lower = filter_value.lower()
+
+        # Tier 1: Exact match
+        if resource_lower == filter_lower:
+            return True
+
+        # Tier 2: Service prefix match
+        service_prefix = f"aws::{filter_lower}::"
+        if resource_lower.startswith(service_prefix):
+            return True
+
+        # Tier 3: Contains match
+        if filter_lower in resource_lower:
+            return True
+
+        return False
+
+
+@dataclass
+class ResourceReport:
+    """
+    Complete report data structure.
+
+    Attributes:
+        snapshot_metadata: Information about the snapshot being reported
+        summary: Aggregated resource counts by service/region/type
+        filtered_resources: Minimal resource list (if filtering applied)
+        detailed_resources: Full resource details (if detailed view requested)
+    """
+
+    snapshot_metadata: SnapshotMetadata
+    summary: ResourceSummary
+    filtered_resources: Optional[List[FilteredResource]] = None
+    detailed_resources: Optional[List[DetailedResource]] = None
+
+    @property
+    def has_filters(self) -> bool:
+        """Check if report includes filtered results."""
+        return self.filtered_resources is not None
+
+    @property
+    def has_details(self) -> bool:
+        """Check if report includes detailed resource info."""
+        return self.detailed_resources is not None

src/models/resource.py

@@ -0,0 +1,111 @@
+"""Resource data model representing a single AWS resource."""
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class Resource:
+    """Represents a single AWS resource captured in a snapshot."""
+
+    arn: str
+    resource_type: str
+    name: str
+    region: str
+    config_hash: str
+    raw_config: Optional[Dict[str, Any]] = None  # Optional for backward compatibility with v1.0 snapshots
+    tags: Dict[str, str] = field(default_factory=dict)
+    created_at: Optional[datetime] = None
+    source: str = "direct_api"  # Collection source: "config" or "direct_api"
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert resource to dictionary for serialization.
+
+        Note: raw_config is included in v1.1+ snapshots for drift analysis support.
+        """
+        return {
+            "arn": self.arn,
+            "type": self.resource_type,
+            "name": self.name,
+            "region": self.region,
+            "tags": self.tags,
+            "config_hash": self.config_hash,
+            "created_at": self.created_at.isoformat() if self.created_at else None,
+            "raw_config": self.raw_config if self.raw_config is not None else {},
+            "source": self.source,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Resource":
+        """Create resource from dictionary.
+
+        Supports both v1.0 (without raw_config) and v1.1+ (with raw_config) snapshots.
+        """
+        created_at = None
+        if data.get("created_at"):
+            if isinstance(data["created_at"], str):
+                created_at = datetime.fromisoformat(data["created_at"])
+            else:
+                created_at = data["created_at"]  # Already a datetime
+
+        return cls(
+            arn=data["arn"],
+            resource_type=data["type"],
+            name=data["name"],
+            region=data["region"],
+            config_hash=data["config_hash"],
+            raw_config=data.get("raw_config"),  # Optional for backward compatibility
+            tags=data.get("tags", {}),
+            created_at=created_at,
+            source=data.get("source", "direct_api"),  # Default for older snapshots
+        )
+
+    def validate(self) -> bool:
+        """Validate resource data integrity.
+
+        Returns:
+            True if valid, raises ValueError if invalid
+        """
+        # Validate ARN format
+        arn_pattern = r"^arn:aws:[a-z0-9-]+:[a-z0-9-]*:[0-9]*:.*$"
+        if not re.match(arn_pattern, self.arn):
+            raise ValueError(f"Invalid ARN format: {self.arn}")
+
+        # Validate config_hash is 64-character hex string (SHA256)
+        if not re.match(r"^[a-fA-F0-9]{64}$", self.config_hash):
+            raise ValueError(f"Invalid config_hash: {self.config_hash}. Must be 64-character SHA256 hex string.")
+
+        # Validate region format
+        valid_regions = ["global"] + [
+            "us-east-1",
+            "us-east-2",
+            "us-west-1",
+            "us-west-2",
+            "eu-west-1",
+            "eu-west-2",
+            "eu-west-3",
+            "eu-central-1",
+            "ap-southeast-1",
+            "ap-southeast-2",
+            "ap-northeast-1",
+            "ap-northeast-2",
+            "ca-central-1",
+            "sa-east-1",
+            "ap-south-1",
+        ]
+        # Basic validation - starts with region pattern or is 'global'
+        if self.region != "global" and not any(self.region.startswith(r[:6]) for r in valid_regions if r != "global"):
+            # Allow it anyway - AWS adds new regions regularly
+            pass
+
+        return True
+
+    @property
+    def service(self) -> str:
+        """Extract service name from resource type.
+
+        Example: 'iam:role' -> 'iam'
+        """
+        return self.resource_type.split(":")[0] if ":" in self.resource_type else self.resource_type