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

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

src/models/security_finding.py

@@ -0,0 +1,102 @@
+"""Security finding model for representing detected security issues in AWS resources."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, Optional
+
+
+class Severity(Enum):
+    """Security finding severity levels."""
+
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+@dataclass
+class SecurityFinding:
+    """Represents a detected security misconfiguration in an AWS resource.
+
+    Attributes:
+        resource_arn: AWS ARN of the resource with the security issue
+        finding_type: Type of security issue (e.g., "public_s3_bucket", "open_security_group")
+        severity: Severity level of the finding
+        description: Human-readable description of the issue
+        remediation: Guidance on how to fix the issue
+        cis_control: Optional CIS AWS Foundations Benchmark control ID (e.g., "2.1.5")
+        metadata: Additional context-specific metadata
+    """
+
+    resource_arn: str
+    finding_type: str
+    severity: Severity
+    description: str
+    remediation: str
+    cis_control: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+    def __post_init__(self) -> None:
+        """Validate SecurityFinding 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 severity is Severity enum
+        if not isinstance(self.severity, Severity):
+            raise ValueError(f"Invalid severity type: {type(self.severity)}. Must be Severity enum.")
+
+        # Validate required string fields are not empty
+        if not self.finding_type:
+            raise ValueError("finding_type cannot be empty")
+        if not self.description:
+            raise ValueError("description cannot be empty")
+        if not self.remediation:
+            raise ValueError("remediation cannot be empty")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert SecurityFinding to dictionary representation.
+
+        Returns:
+            Dictionary with all finding attributes
+        """
+        return {
+            "resource_arn": self.resource_arn,
+            "finding_type": self.finding_type,
+            "severity": self.severity.value,
+            "description": self.description,
+            "remediation": self.remediation,
+            "cis_control": self.cis_control,
+            "metadata": self.metadata or {},
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> SecurityFinding:
+        """Create SecurityFinding from dictionary representation.
+
+        Args:
+            data: Dictionary with finding attributes
+
+        Returns:
+            SecurityFinding instance
+
+        Raises:
+            ValueError: If severity value is invalid
+        """
+        severity_str = data.get("severity", "").lower()
+        try:
+            severity = Severity(severity_str)
+        except ValueError:
+            raise ValueError(f"Invalid severity value: {severity_str}")
+
+        return cls(
+            resource_arn=data["resource_arn"],
+            finding_type=data["finding_type"],
+            severity=severity,
+            description=data["description"],
+            remediation=data["remediation"],
+            cis_control=data.get("cis_control"),
+            metadata=data.get("metadata"),
+        )

src/models/snapshot.py

@@ -0,0 +1,122 @@
+"""Snapshot data model representing a point-in-time inventory of AWS resources."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Snapshot:
+    """Represents a point-in-time inventory of AWS resources.
+
+    This serves as the baseline reference for delta tracking and cost analysis.
+
+    Schema Versions:
+    - v1.0: Basic snapshot with config_hash only
+    - v1.1: Added raw_config for drift analysis support
+    """
+
+    name: str
+    created_at: datetime
+    account_id: str
+    regions: List[str]
+    resources: List[Any]  # List[Resource] - avoiding circular import
+    is_active: bool = True
+    resource_count: int = 0
+    service_counts: Dict[str, int] = field(default_factory=dict)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    filters_applied: Optional[Dict[str, Any]] = None
+    total_resources_before_filter: Optional[int] = None
+    inventory_name: str = "default"  # Name of inventory this snapshot belongs to
+    schema_version: str = "1.1"  # Schema version for forward/backward compatibility
+
+    def __post_init__(self) -> None:
+        """Calculate derived fields after initialization."""
+        if self.resource_count == 0:
+            self.resource_count = len(self.resources)
+
+        if not self.service_counts:
+            self._calculate_service_counts()
+
+    def _calculate_service_counts(self) -> None:
+        """Calculate resource counts by service type."""
+        counts: Dict[str, int] = {}
+        for resource in self.resources:
+            service = resource.resource_type.split(":")[0] if ":" in resource.resource_type else resource.resource_type
+            counts[service] = counts.get(service, 0) + 1
+        self.service_counts = counts
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert snapshot to dictionary for serialization."""
+        return {
+            "schema_version": self.schema_version,
+            "name": self.name,
+            "created_at": self.created_at.isoformat(),
+            "account_id": self.account_id,
+            "regions": self.regions,
+            "is_active": self.is_active,
+            "resource_count": self.resource_count,
+            "service_counts": self.service_counts,
+            "metadata": self.metadata,
+            "filters_applied": self.filters_applied,
+            "total_resources_before_filter": self.total_resources_before_filter,
+            "inventory_name": self.inventory_name,
+            "resources": [r.to_dict() for r in self.resources],
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Snapshot":
+        """Create snapshot from dictionary.
+
+        Supports both v1.0 and v1.1+ snapshot formats for backward compatibility.
+
+        Note: This requires Resource class to be imported at call time
+        to avoid circular imports.
+        """
+        from .resource import Resource
+
+        # Handle created_at 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)
+
+        return cls(
+            name=data["name"],
+            created_at=created_at,
+            account_id=data["account_id"],
+            regions=data["regions"],
+            resources=[Resource.from_dict(r) for r in data["resources"]],
+            is_active=data.get("is_active", True),
+            resource_count=data.get("resource_count", 0),
+            service_counts=data.get("service_counts", {}),
+            metadata=data.get("metadata", {}),
+            filters_applied=data.get("filters_applied"),
+            total_resources_before_filter=data.get("total_resources_before_filter"),
+            inventory_name=data.get("inventory_name", "default"),  # Default for backward compatibility
+            schema_version=data.get("schema_version", "1.0"),  # Default to 1.0 for old snapshots
+        )
+
+    def validate(self) -> bool:
+        """Validate snapshot data integrity.
+
+        Returns:
+            True if valid, raises ValueError if invalid
+        """
+        import re
+
+        # Validate name format (alphanumeric, hyphens, underscores)
+        if not re.match(r"^[a-zA-Z0-9_-]+$", self.name):
+            raise ValueError(
+                f"Invalid snapshot name: {self.name}. "
+                f"Must contain only alphanumeric characters, hyphens, and underscores."
+            )
+
+        # Validate account ID (12-digit string)
+        if not re.match(r"^\d{12}$", self.account_id):
+            raise ValueError(f"Invalid AWS account ID: {self.account_id}. Must be a 12-digit string.")
+
+        # Validate regions list is not empty
+        if not self.regions:
+            raise ValueError("Snapshot must include at least one AWS region.")
+
+        return True

src/restore/__init__.py

@@ -0,0 +1,20 @@
+"""Resource cleanup/restoration module.
+
+This module provides functionality to delete AWS resources created after a baseline
+snapshot, with comprehensive safety protections.
+
+Classes:
+    ResourceCleaner: Main orchestrator for restore operations
+    DependencyResolver: Dependency graph construction and deletion ordering
+    SafetyChecker: Protection rule evaluation
+    AuditStorage: Audit log storage and retrieval
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "ResourceCleaner",
+    "DependencyResolver",
+    "SafetyChecker",
+    "AuditStorage",
+]