iam-policy-validator 1.8.0__py3-none-any.whl → 1.9.0__py3-none-any.whl

iam_validator/core/aws_service/parsers.py

@@ -0,0 +1,149 @@
+"""Parsing and pattern matching for AWS actions and resources.
+
+This module provides functionality to parse IAM actions, validate ARN formats,
+and perform wildcard matching on action patterns.
+"""
+
+import re
+
+from iam_validator.core.aws_service.patterns import CompiledPatterns
+
+
+class ServiceParser:
+    """Parses and matches AWS actions, ARNs, and wildcards.
+
+    This class provides methods for:
+    - Parsing IAM actions into service prefix and action name
+    - Validating ARN format
+    - Detecting and matching wildcard patterns
+    - Expanding wildcard actions to full action lists
+    """
+
+    def __init__(self) -> None:
+        """Initialize parser with compiled patterns."""
+        self._patterns = CompiledPatterns()
+
+    def parse_action(self, action: str) -> tuple[str, str]:
+        """Parse IAM action into service prefix and action name.
+
+        Args:
+            action: Full action string (e.g., "s3:GetObject", "iam:CreateUser")
+
+        Returns:
+            Tuple of (service_prefix, action_name) both lowercase
+
+        Raises:
+            ValueError: If action format is invalid
+
+        Example:
+            >>> parser = ServiceParser()
+            >>> parser.parse_action("s3:GetObject")
+            ('s3', 'GetObject')
+        """
+        match = self._patterns.action_pattern.match(action)
+        if not match:
+            raise ValueError(f"Invalid action format: {action}")
+
+        return match.group("service").lower(), match.group("action")
+
+    def validate_arn_format(self, arn: str) -> tuple[bool, str | None]:
+        """Validate ARN format using compiled regex.
+
+        Args:
+            arn: ARN string to validate
+
+        Returns:
+            Tuple of (is_valid, error_message). error_message is None if valid.
+
+        Example:
+            >>> parser = ServiceParser()
+            >>> parser.validate_arn_format("arn:aws:s3:::my-bucket/*")
+            (True, None)
+            >>> parser.validate_arn_format("invalid")
+            (False, "Invalid ARN format: invalid")
+        """
+        if arn == "*":
+            return True, None
+
+        match = self._patterns.arn_pattern.match(arn)
+        if not match:
+            return False, f"Invalid ARN format: {arn}"
+
+        return True, None
+
+    def is_wildcard_action(self, action_name: str) -> bool:
+        """Check if action name contains wildcards.
+
+        Args:
+            action_name: Action name to check (e.g., "GetObject", "Get*", "*")
+
+        Returns:
+            True if action contains wildcard characters
+
+        Example:
+            >>> parser = ServiceParser()
+            >>> parser.is_wildcard_action("GetObject")
+            False
+            >>> parser.is_wildcard_action("Get*")
+            True
+        """
+        return bool(self._patterns.wildcard_pattern.search(action_name))
+
+    def match_wildcard_action(self, pattern: str, actions: list[str]) -> tuple[bool, list[str]]:
+        """Match wildcard pattern against list of actions.
+
+        Args:
+            pattern: Action pattern with wildcards (e.g., "Get*", "*Object", "Describe*")
+            actions: List of valid action names to match against
+
+        Returns:
+            Tuple of (has_matches, list_of_matched_actions)
+
+        Example:
+            >>> parser = ServiceParser()
+            >>> actions = ["GetObject", "GetBucket", "PutObject"]
+            >>> parser.match_wildcard_action("Get*", actions)
+            (True, ['GetObject', 'GetBucket'])
+        """
+        # Convert wildcard pattern to regex
+        # Escape special regex chars except *, then replace * with .*
+        regex_pattern = "^" + re.escape(pattern).replace(r"\*", ".*") + "$"
+        compiled_pattern = re.compile(regex_pattern, re.IGNORECASE)
+
+        matched = [a for a in actions if compiled_pattern.match(a)]
+        return len(matched) > 0, matched
+
+    def expand_wildcard_to_actions(
+        self,
+        action_pattern: str,
+        available_actions: list[str],
+        service_prefix: str,
+    ) -> list[str]:
+        """Expand wildcard pattern to full list of actions.
+
+        Args:
+            action_pattern: Action pattern (e.g., "s3:Get*", "iam:*")
+            available_actions: List of available action names for the service
+            service_prefix: Service prefix (e.g., "s3", "iam")
+
+        Returns:
+            Sorted list of fully-qualified actions matching the pattern
+
+        Example:
+            >>> parser = ServiceParser()
+            >>> actions = ["GetObject", "PutObject", "DeleteObject"]
+            >>> parser.expand_wildcard_to_actions("s3:*Object", actions, "s3")
+            ['s3:DeleteObject', 's3:GetObject', 's3:PutObject']
+        """
+        # Parse to get action name part
+        _, action_name = self.parse_action(action_pattern)
+
+        # Handle full service wildcard (e.g., "iam:*")
+        if action_name == "*":
+            return sorted([f"{service_prefix}:{action}" for action in available_actions])
+
+        # Match wildcard pattern
+        _, matched_actions = self.match_wildcard_action(action_name, available_actions)
+
+        # Return fully-qualified actions
+        return sorted([f"{service_prefix}:{action}" for action in matched_actions])

iam_validator/core/aws_service/patterns.py

@@ -0,0 +1,51 @@
+"""Pre-compiled regex patterns for AWS service validation.
+
+This module provides a singleton class containing pre-compiled regex patterns
+used across the AWS service validation system for better performance.
+"""
+
+import re
+
+
+class CompiledPatterns:
+    """Pre-compiled regex patterns for validation.
+
+    This class implements the Singleton pattern to ensure patterns are compiled only once
+    and reused across all instances for better performance.
+    """
+
+    _instance: "CompiledPatterns | None" = None
+    _initialized: bool = False
+
+    def __new__(cls) -> "CompiledPatterns":
+        """Create or return the singleton instance."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self) -> None:
+        """Initialize compiled patterns (only once due to Singleton pattern)."""
+        # Only initialize once, even if __init__ is called multiple times
+        if CompiledPatterns._initialized:
+            return
+
+        CompiledPatterns._initialized = True
+
+        # ARN validation pattern
+        self.arn_pattern = re.compile(
+            r"^arn:(?P<partition>(aws|aws-cn|aws-us-gov|aws-eusc|aws-iso|aws-iso-b|aws-iso-e|aws-iso-f)):"
+            r"(?P<service>[a-z0-9\-]+):"
+            r"(?P<region>[a-z0-9\-]*):"
+            r"(?P<account>[0-9]*):"
+            r"(?P<resource>.+)$",
+            re.IGNORECASE,
+        )
+
+        # Action format pattern
+        self.action_pattern = re.compile(
+            r"^(?P<service>[a-zA-Z0-9_-]+):(?P<action>[a-zA-Z0-9*_-]+)$"
+        )
+
+        # Wildcard detection patterns
+        self.wildcard_pattern = re.compile(r"\*")
+        self.partial_wildcard_pattern = re.compile(r"^[^*]+\*$")

iam_validator/core/aws_service/storage.py

@@ -0,0 +1,291 @@
+"""File storage operations for AWS service data.
+
+This module handles disk caching and offline file loading for AWS service definitions.
+"""
+
+import hashlib
+import json
+import logging
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+from iam_validator.core.models import ServiceDetail, ServiceInfo
+
+logger = logging.getLogger(__name__)
+
+
+class ServiceFileStorage:
+    """Handles disk cache and offline AWS service file operations.
+
+    This class manages:
+    - Disk-based caching with TTL
+    - Loading AWS service definitions from local files
+    - Platform-specific cache directory management
+    """
+
+    def __init__(
+        self,
+        cache_dir: Path | str | None = None,
+        aws_services_dir: Path | str | None = None,
+        cache_ttl: int = 86400,
+        enable_cache: bool = True,
+    ) -> None:
+        """Initialize storage with cache and offline directories.
+
+        Args:
+            cache_dir: Custom cache directory path (uses platform default if None)
+            aws_services_dir: Directory containing pre-downloaded AWS service JSON files.
+                When set, enables offline mode. Directory should contain:
+                - _services.json: List of all services
+                - {service}.json: Individual service files (e.g., s3.json)
+            cache_ttl: Cache time-to-live in seconds
+            enable_cache: Enable persistent disk caching
+        """
+        self.cache_ttl = cache_ttl
+        self.enable_cache = enable_cache
+        self._cache_dir = self.get_cache_directory(cache_dir)
+
+        # AWS services directory for offline mode
+        self.aws_services_dir: Path | None = None
+        if aws_services_dir:
+            self.aws_services_dir = Path(aws_services_dir)
+            if not self.aws_services_dir.exists():
+                raise ValueError(f"AWS services directory does not exist: {aws_services_dir}")
+            logger.info(f"Using local AWS services from: {self.aws_services_dir}")
+
+        # Create cache directory if needed
+        if self.enable_cache:
+            self._cache_dir.mkdir(parents=True, exist_ok=True)
+
+    @staticmethod
+    def get_cache_directory(cache_dir: Path | str | None = None) -> Path:
+        """Get the cache directory path, using platform-appropriate defaults.
+
+        Priority:
+        1. Provided cache_dir parameter
+        2. Platform-specific user cache directory
+           - Linux/Unix: ~/.cache/iam-validator/aws_services
+           - macOS: ~/Library/Caches/iam-validator/aws_services
+           - Windows: %LOCALAPPDATA%/iam-validator/cache/aws_services
+
+        Args:
+            cache_dir: Optional custom cache directory path
+
+        Returns:
+            Path object for the cache directory
+        """
+        if cache_dir is not None:
+            return Path(cache_dir)
+
+        # Determine platform-specific cache directory
+        if sys.platform == "darwin":
+            # macOS
+            base_cache = Path.home() / "Library" / "Caches"
+        elif sys.platform == "win32":
+            # Windows
+            base_cache = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
+        else:
+            # Linux and other Unix-like systems
+            base_cache = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
+
+        return base_cache / "iam-validator" / "aws_services"
+
+    def set_cache_directory(self, cache_dir: Path | str) -> None:
+        """Set a new cache directory path dynamically.
+
+        This method allows library users to change the cache location at runtime.
+        The new directory will be created if it doesn't exist and caching is enabled.
+
+        Args:
+            cache_dir: New cache directory path
+
+        Example:
+            >>> storage = ServiceFileStorage()
+            >>> storage.set_cache_directory("/tmp/my-custom-cache")
+            >>> # Future cache operations will use the new directory
+        """
+        self._cache_dir = Path(cache_dir)
+
+        # Create new cache directory if caching is enabled
+        if self.enable_cache:
+            self._cache_dir.mkdir(parents=True, exist_ok=True)
+            logger.info(f"Cache directory updated to: {self._cache_dir}")
+
+    @property
+    def cache_directory(self) -> Path:
+        """Get the current cache directory path.
+
+        Returns:
+            Current cache directory as Path object
+
+        Example:
+            >>> storage = ServiceFileStorage()
+            >>> print(storage.cache_directory)
+            PosixPath('/Users/username/Library/Caches/iam-validator/aws_services')
+        """
+        return self._cache_dir
+
+    def _get_cache_path(self, url: str, base_url: str) -> Path:
+        """Generate cache file path for URL.
+
+        Args:
+            url: URL to generate cache path for
+            base_url: Base URL for service reference API
+
+        Returns:
+            Path to cache file
+        """
+        url_hash = hashlib.md5(url.encode()).hexdigest()
+
+        # Extract service name for better organization
+        filename = f"{url_hash}.json"
+        if "/v1/" in url:
+            service_name = url.split("/v1/")[1].split("/")[0]
+            filename = f"{service_name}_{url_hash[:8]}.json"
+        elif url == base_url:
+            filename = "services_list.json"
+
+        return self._cache_dir / filename
+
+    def read_from_cache(self, url: str, base_url: str) -> Any | None:
+        """Read from disk cache with TTL checking.
+
+        Args:
+            url: URL to read from cache
+            base_url: Base URL for service reference API
+
+        Returns:
+            Cached data if valid, None otherwise
+        """
+        if not self.enable_cache:
+            return None
+
+        cache_path = self._get_cache_path(url, base_url)
+
+        if not cache_path.exists():
+            return None
+
+        try:
+            # Check file modification time for TTL
+            mtime = cache_path.stat().st_mtime
+            if time.time() - mtime > self.cache_ttl:
+                logger.debug(f"Cache expired for {url}")
+                cache_path.unlink()  # Remove expired cache
+                return None
+
+            with open(cache_path, encoding="utf-8") as f:
+                data = json.load(f)
+            logger.debug(f"Disk cache hit for {url}")
+            return data
+
+        except Exception as e:  # pylint: disable=broad-exception-caught
+            logger.warning(f"Failed to read cache for {url}: {e}")
+            return None
+
+    def write_to_cache(self, url: str, data: Any, base_url: str) -> None:
+        """Write to disk cache.
+
+        Args:
+            url: URL to cache data for
+            data: Data to cache
+            base_url: Base URL for service reference API
+        """
+        if not self.enable_cache:
+            return
+
+        cache_path = self._get_cache_path(url, base_url)
+
+        try:
+            with open(cache_path, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2)
+            logger.debug(f"Written to disk cache: {url}")
+        except Exception as e:  # pylint: disable=broad-exception-caught
+            logger.warning(f"Failed to write cache for {url}: {e}")
+
+    def load_services_from_file(self) -> list[ServiceInfo]:
+        """Load services list from local _services.json file.
+
+        Returns:
+            List of ServiceInfo objects loaded from _services.json
+
+        Raises:
+            ValueError: If aws_services_dir is not set or _services.json is invalid
+            FileNotFoundError: If _services.json doesn't exist
+        """
+        if not self.aws_services_dir:
+            raise ValueError("aws_services_dir is not set")
+
+        services_file = self.aws_services_dir / "_services.json"
+        if not services_file.exists():
+            raise FileNotFoundError(f"_services.json not found in {self.aws_services_dir}")
+
+        try:
+            with open(services_file, encoding="utf-8") as f:
+                data = json.load(f)
+
+            if not isinstance(data, list):
+                raise ValueError("Expected list of services from _services.json")
+
+            services: list[ServiceInfo] = []
+            for item in data:
+                if isinstance(item, dict):
+                    service = item.get("service")
+                    url = item.get("url")
+                    if service and url:
+                        services.append(ServiceInfo(service=str(service), url=str(url)))
+
+            logger.info(f"Loaded {len(services)} services from local file: {services_file}")
+            return services
+
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in _services.json: {e}") from e
+
+    def load_service_from_file(self, service_name: str) -> ServiceDetail:
+        """Load service detail from local JSON file.
+
+        Args:
+            service_name: Name of the service (case-insensitive)
+
+        Returns:
+            ServiceDetail object loaded from {service}.json
+
+        Raises:
+            ValueError: If aws_services_dir is not set or service JSON is invalid
+            FileNotFoundError: If service JSON file doesn't exist
+        """
+        if not self.aws_services_dir:
+            raise ValueError("aws_services_dir is not set")
+
+        # Normalize filename (lowercase, replace spaces with underscores)
+        filename = f"{service_name.lower().replace(' ', '_')}.json"
+        service_file = self.aws_services_dir / filename
+
+        if not service_file.exists():
+            raise FileNotFoundError(f"Service file not found: {service_file}")
+
+        try:
+            with open(service_file, encoding="utf-8") as f:
+                data = json.load(f)
+
+            service_detail = ServiceDetail.model_validate(data)
+            logger.debug(f"Loaded service {service_name} from local file: {service_file}")
+            return service_detail
+
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in {service_file}: {e}") from e
+
+    def clear_disk_cache(self) -> None:
+        """Remove all cached files from disk."""
+        if not self.enable_cache or not self._cache_dir.exists():
+            return
+
+        for cache_file in self._cache_dir.glob("*.json"):
+            try:
+                cache_file.unlink()
+            except Exception as e:  # pylint: disable=broad-exception-caught
+                logger.warning(f"Failed to delete cache file {cache_file}: {e}")
+
+        logger.info("Cleared disk cache")