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

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",
+]

src/restore/audit.py

@@ -0,0 +1,175 @@
+"""Audit storage for deletion operations.
+
+Stores and retrieves audit logs in YAML format for compliance and troubleshooting.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from src.models.deletion_operation import DeletionOperation
+from src.models.deletion_record import DeletionRecord
+
+
+class AuditStorage:
+    """Audit log storage and retrieval.
+
+    Stores deletion operation audit logs as YAML files organized by year/month.
+    Supports querying operations by date range and retrieving detailed operation logs.
+
+    Storage structure:
+        ~/.snapshots/audit-logs/
+            2025/
+                11/
+                    operation-op_123.yaml
+                    operation-op_456.yaml
+
+    Attributes:
+        storage_dir: Base directory for audit logs
+    """
+
+    def __init__(self, storage_dir: Optional[str] = None) -> None:
+        """Initialize audit storage.
+
+        Args:
+            storage_dir: Base directory for audit logs (default: ~/.snapshots/audit-logs)
+        """
+        if storage_dir is None:
+            storage_dir = str(Path.home() / ".snapshots" / "audit-logs")
+
+        self.storage_dir = Path(storage_dir)
+        self.storage_dir.mkdir(parents=True, exist_ok=True)
+
+    def log_operation(self, operation: DeletionOperation, records: list[DeletionRecord]) -> None:
+        """Log deletion operation to audit storage.
+
+        Creates YAML file with operation metadata and all deletion records.
+        Overwrites existing log if operation ID already exists.
+
+        Args:
+            operation: Deletion operation to log
+            records: List of deletion records for this operation
+        """
+        # Create year/month directory structure
+        year = operation.timestamp.year
+        month = operation.timestamp.month
+        year_month_dir = self.storage_dir / str(year) / f"{month:02d}"
+        year_month_dir.mkdir(parents=True, exist_ok=True)
+
+        # Create audit log structure
+        audit_data = {
+            "metadata": {
+                "version": "1.0",
+                "log_type": "resource_deletion",
+                "created_at": datetime.utcnow().isoformat() + "Z",
+            },
+            "operation": {
+                "operation_id": operation.operation_id,
+                "baseline_snapshot": operation.baseline_snapshot,
+                "timestamp": operation.timestamp.isoformat() + "Z",
+                "aws_profile": operation.aws_profile,
+                "account_id": operation.account_id,
+                "mode": operation.mode.value,
+                "status": operation.status.value,
+                "filters": operation.filters,
+                "total_resources": operation.total_resources,
+                "succeeded_count": operation.succeeded_count,
+                "failed_count": operation.failed_count,
+                "skipped_count": operation.skipped_count,
+                "started_at": operation.started_at.isoformat() + "Z" if operation.started_at else None,
+                "completed_at": operation.completed_at.isoformat() + "Z" if operation.completed_at else None,
+                "duration_seconds": operation.duration_seconds,
+            },
+            "records": [
+                {
+                    "record_id": record.record_id,
+                    "operation_id": record.operation_id,
+                    "resource_arn": record.resource_arn,
+                    "resource_id": record.resource_id,
+                    "resource_type": record.resource_type,
+                    "region": record.region,
+                    "timestamp": record.timestamp.isoformat() + "Z",
+                    "status": record.status.value,
+                    "error_code": record.error_code,
+                    "error_message": record.error_message,
+                    "protection_reason": record.protection_reason,
+                    "deletion_tier": record.deletion_tier,
+                    "tags": record.tags,
+                    "estimated_monthly_cost": record.estimated_monthly_cost,
+                }
+                for record in records
+            ],
+        }
+
+        # Write YAML file
+        audit_file = year_month_dir / f"operation-{operation.operation_id}.yaml"
+        with open(audit_file, "w") as f:
+            yaml.dump(audit_data, f, default_flow_style=False, sort_keys=False)
+
+    def get_operation(self, operation_id: str) -> Optional[dict]:
+        """Retrieve operation audit log by ID.
+
+        Args:
+            operation_id: Operation ID to retrieve
+
+        Returns:
+            Audit log dictionary if found, None otherwise
+        """
+        # Search all year/month directories
+        for year_dir in self.storage_dir.glob("*"):
+            if not year_dir.is_dir():
+                continue
+
+            for month_dir in year_dir.glob("*"):
+                if not month_dir.is_dir():
+                    continue
+
+                audit_file = month_dir / f"operation-{operation_id}.yaml"
+                if audit_file.exists():
+                    with open(audit_file, "r") as f:
+                        return yaml.safe_load(f)
+
+        return None
+
+    def query_operations(self, since: Optional[datetime] = None, until: Optional[datetime] = None) -> list[dict]:
+        """Query operations within date range.
+
+        Args:
+            since: Start date (inclusive), None for all
+            until: End date (inclusive), None for all
+
+        Returns:
+            List of operation audit logs matching criteria
+        """
+        results = []
+
+        # Search all year/month directories
+        for year_dir in sorted(self.storage_dir.glob("*")):
+            if not year_dir.is_dir():
+                continue
+
+            for month_dir in sorted(year_dir.glob("*")):
+                if not month_dir.is_dir():
+                    continue
+
+                for audit_file in sorted(month_dir.glob("operation-*.yaml")):
+                    with open(audit_file, "r") as f:
+                        audit_data = yaml.safe_load(f)
+
+                    # Parse timestamp
+                    timestamp_str = audit_data["operation"]["timestamp"]
+                    timestamp = datetime.fromisoformat(timestamp_str.rstrip("Z"))
+
+                    # Filter by date range
+                    if since and timestamp < since:
+                        continue
+                    if until and timestamp > until:
+                        continue
+
+                    results.append(audit_data)
+
+        return results