iam-policy-validator 1.14.7__py3-none-any.whl → 1.15.1__py3-none-any.whl

iam_validator/core/aws_service/__init__.py

@@ -12,10 +12,14 @@ Example usage:
 # Re-export main classes for public API
 from iam_validator.core.aws_service.fetcher import AWSServiceFetcher
 from iam_validator.core.aws_service.patterns import CompiledPatterns
-from iam_validator.core.aws_service.validators import ConditionKeyValidationResult
+from iam_validator.core.aws_service.validators import (
+    ConditionKeyValidationResult,
+    condition_key_in_list,
+)
 
 __all__ = [
     "AWSServiceFetcher",
     "ConditionKeyValidationResult",
     "CompiledPatterns",
+    "condition_key_in_list",
 ]

iam_validator/core/aws_service/cache.py

@@ -70,6 +70,26 @@ class ServiceCacheManager:
 
         return None
 
+    async def get_stale(self, url: str | None = None, base_url: str = "") -> Any | None:
+        """Get from disk cache even if expired (stale data fallback).
+
+        Use this method to retrieve stale cache data when a fresh fetch fails.
+        The stale data can serve as a fallback to avoid complete failure.
+
+        Args:
+            url: URL for disk cache lookup
+            base_url: Base URL for service reference API (used for disk cache path)
+
+        Returns:
+            Cached data if found (regardless of TTL), None otherwise
+        """
+        if url and self._storage:
+            cached = self._storage.read_from_cache(url, base_url, allow_stale=True)
+            if cached is not None:
+                logger.info(f"Using stale cache fallback for URL: {url}")
+                return cached
+        return None
+
     async def set(
         self, cache_key: str, value: Any, url: str | None = None, base_url: str = ""
     ) -> None:

iam_validator/core/aws_service/fetcher.py

@@ -245,11 +245,21 @@ class AWSServiceFetcher:
             f"raw:{self.BASE_URL}", url=self.BASE_URL, base_url=self.BASE_URL
         )
         if data is None:
-            data = await self._client.fetch(self.BASE_URL)
-            # Cache the raw data
-            await self._cache.set(
-                f"raw:{self.BASE_URL}", data, url=self.BASE_URL, base_url=self.BASE_URL
-            )
+            try:
+                data = await self._client.fetch(self.BASE_URL)
+                # Cache the raw data (this refreshes the disk cache file)
+                await self._cache.set(
+                    f"raw:{self.BASE_URL}", data, url=self.BASE_URL, base_url=self.BASE_URL
+                )
+            except Exception as e:  # pylint: disable=broad-exception-caught
+                # API fetch failed - try stale cache as fallback
+                logger.warning(f"API fetch failed for services list: {e}")
+                stale_data = await self._cache.get_stale(url=self.BASE_URL, base_url=self.BASE_URL)
+                if stale_data is not None:
+                    logger.info("Using stale cache data for services list due to API failure")
+                    data = stale_data
+                else:
+                    raise
 
         if not isinstance(data, list):
             raise ValueError("Expected list of services from root endpoint")
@@ -332,12 +342,26 @@ class AWSServiceFetcher:
                     f"raw:{service.url}", url=service.url, base_url=self.BASE_URL
                 )
                 if data is None:
-                    # Fetch service detail from API
-                    data = await self._client.fetch(service.url)
-                    # Cache the raw data
-                    await self._cache.set(
-                        f"raw:{service.url}", data, url=service.url, base_url=self.BASE_URL
-                    )
+                    try:
+                        # Fetch service detail from API
+                        data = await self._client.fetch(service.url)
+                        # Cache the raw data (this refreshes the disk cache file)
+                        await self._cache.set(
+                            f"raw:{service.url}", data, url=service.url, base_url=self.BASE_URL
+                        )
+                    except Exception as e:  # pylint: disable=broad-exception-caught
+                        # API fetch failed - try stale cache as fallback
+                        logger.warning(f"API fetch failed for {service_name}: {e}")
+                        stale_data = await self._cache.get_stale(
+                            url=service.url, base_url=self.BASE_URL
+                        )
+                        if stale_data is not None:
+                            logger.info(
+                                f"Using stale cache data for {service_name} due to API failure"
+                            )
+                            data = stale_data
+                        else:
+                            raise
 
                 # Validate and parse
                 service_detail = ServiceDetail.model_validate(data)
@@ -421,6 +445,73 @@ class AWSServiceFetcher:
         service_detail = await self.fetch_service_by_name(service_prefix)
         return await self._validator.validate_action(action, service_detail, allow_wildcards)
 
+    async def validate_actions_batch(
+        self,
+        actions: list[str],
+        allow_wildcards: bool = True,
+    ) -> dict[str, tuple[bool, str | None, bool]]:
+        """Validate multiple IAM actions efficiently in batch.
+
+        Groups actions by service prefix and fetches each service definition once,
+        reducing network overhead when validating multiple actions.
+
+        Args:
+            actions: List of full action strings (e.g., ["s3:GetObject", "iam:CreateUser"])
+            allow_wildcards: Whether to allow wildcard actions
+
+        Returns:
+            Dictionary mapping action -> (is_valid, error_message, is_wildcard)
+
+        Example:
+            >>> async with AWSServiceFetcher() as fetcher:
+            ...     results = await fetcher.validate_actions_batch([
+            ...         "s3:GetObject",
+            ...         "s3:PutObject",
+            ...         "iam:CreateUser"
+            ...     ])
+            ...     for action, (is_valid, error, is_wildcard) in results.items():
+            ...         if not is_valid:
+            ...             print(f"Invalid: {action} - {error}")
+        """
+        if not actions:
+            return {}
+
+        # Group actions by service prefix
+        service_actions: dict[str, list[str]] = {}
+        for action in actions:
+            service_prefix, _ = self._parser.parse_action(action)
+            if service_prefix not in service_actions:
+                service_actions[service_prefix] = []
+            service_actions[service_prefix].append(action)
+
+        # Fetch all service definitions in parallel
+        service_details: dict[str, ServiceDetail] = {}
+        fetch_tasks = [self.fetch_service_by_name(service) for service in service_actions.keys()]
+        fetched = await asyncio.gather(*fetch_tasks, return_exceptions=True)
+
+        for service, result in zip(service_actions.keys(), fetched):
+            if isinstance(result, BaseException):
+                # Store None to indicate fetch failure
+                service_details[service] = None  # type: ignore
+            else:
+                service_details[service] = result
+
+        # Validate all actions using cached service details
+        results: dict[str, tuple[bool, str | None, bool]] = {}
+        for action in actions:
+            service_prefix, _ = self._parser.parse_action(action)
+            service_detail = service_details.get(service_prefix)
+
+            if service_detail is None:
+                # Service fetch failed
+                results[action] = (False, f"Failed to fetch service '{service_prefix}'", False)
+            else:
+                results[action] = await self._validator.validate_action(
+                    action, service_detail, allow_wildcards
+                )
+
+        return results
+
     def validate_arn(self, arn: str) -> tuple[bool, str | None]:
         """Validate ARN format.
 
@@ -466,6 +557,84 @@ class AWSServiceFetcher:
             action, condition_key, service_detail, resources
         )
 
+    async def is_condition_key_supported(
+        self,
+        action: str,
+        condition_key: str,
+    ) -> bool:
+        """Check if a condition key is supported for a specific action.
+
+        This checks two locations for the condition key:
+        1. Action-level condition keys (ActionConditionKeys)
+        2. Resource-level condition keys (for each resource the action operates on)
+
+        Returns True if the condition key is found in either location.
+
+        This is useful for determining if a condition provides meaningful
+        restrictions for an action, particularly for resource-scoping conditions
+        like aws:ResourceTag/*.
+
+        Args:
+            action: IAM action (e.g., "s3:GetObject", "ssm:StartSession")
+            condition_key: Condition key to check (e.g., "aws:ResourceTag/Env")
+
+        Returns:
+            True if the condition key is supported for this action
+
+        Example:
+            >>> async with AWSServiceFetcher() as fetcher:
+            ...     # SSM StartSession has aws:ResourceTag in ActionConditionKeys
+            ...     supported = await fetcher.is_condition_key_supported(
+            ...         "ssm:StartSession", "aws:ResourceTag/Component"
+            ...     )
+            ...     print(f"Tag support: {supported}")  # True
+        """
+        from iam_validator.core.aws_service.validators import (  # pylint: disable=import-outside-toplevel
+            condition_key_in_list,
+        )
+
+        try:
+            service_prefix, action_name = self._parser.parse_action(action)
+        except ValueError:
+            return False  # Invalid action format
+
+        # Can't verify wildcard actions
+        if "*" in action_name or "?" in action_name:
+            return False
+
+        service_detail = await self.fetch_service_by_name(service_prefix)
+        if not service_detail:
+            return False
+
+        # Case-insensitive action lookup
+        action_detail = None
+        action_name_lower = action_name.lower()
+        for name, detail in service_detail.actions.items():
+            if name.lower() == action_name_lower:
+                action_detail = detail
+                break
+
+        if not action_detail:
+            return False
+
+        # Check 1: Action-level condition keys
+        if action_detail.action_condition_keys:
+            if condition_key_in_list(condition_key, action_detail.action_condition_keys):
+                return True
+
+        # Check 2: Resource-level condition keys
+        if action_detail.resources:
+            for res_ref in action_detail.resources:
+                resource_name = res_ref.get("Name")
+                if not resource_name:
+                    continue
+                resource_type = service_detail.resources.get(resource_name)
+                if resource_type and resource_type.condition_keys:
+                    if condition_key_in_list(condition_key, resource_type.condition_keys):
+                        return True
+
+        return False
+
     # --- Parsing Methods (delegate to parser) ---
 
     def parse_action(self, action: str) -> tuple[str, str]:

iam_validator/core/aws_service/storage.py

@@ -150,15 +150,16 @@ class ServiceFileStorage:
 
         return self._cache_dir / filename
 
-    def read_from_cache(self, url: str, base_url: str) -> Any | None:
+    def read_from_cache(self, url: str, base_url: str, allow_stale: bool = False) -> Any | None:
         """Read from disk cache with TTL checking.
 
         Args:
             url: URL to read from cache
             base_url: Base URL for service reference API
+            allow_stale: If True, return stale cache data even if expired
 
         Returns:
-            Cached data if valid, None otherwise
+            Cached data if valid (or if allow_stale and data exists), None otherwise
         """
         if not self.enable_cache:
             return None
@@ -171,14 +172,21 @@ class ServiceFileStorage:
         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
+            is_expired = time.time() - mtime > self.cache_ttl
+
+            if is_expired and not allow_stale:
+                # Cache expired - don't delete the file, just return None
+                # The file will be refreshed (overwritten) on next successful fetch
+                logger.debug(f"Cache expired for {url} (keeping file for refresh)")
                 return None
 
             with open(cache_path, encoding="utf-8") as f:
                 data = json.load(f)
-            logger.debug(f"Disk cache hit for {url}")
+
+            if is_expired:
+                logger.debug(f"Disk cache stale hit for {url} (allow_stale=True)")
+            else:
+                logger.debug(f"Disk cache hit for {url}")
             return data
 
         except Exception as e:  # pylint: disable=broad-exception-caught

iam_validator/core/aws_service/validators.py

@@ -13,7 +13,6 @@ from iam_validator.core.aws_service.parsers import ServiceParser
 from iam_validator.core.constants import (
     AWS_TAG_KEY_ALLOWED_CHARS,
     AWS_TAG_KEY_MAX_LENGTH,
-    AWS_TAG_KEY_PLACEHOLDERS,
 )
 from iam_validator.core.models import ServiceDetail
 
@@ -46,42 +45,17 @@ def _is_valid_tag_key(tag_key: str) -> bool:
     return bool(_TAG_KEY_PATTERN.match(tag_key))
 
 
-def _matches_condition_key_pattern(condition_key: str, pattern: str) -> bool:
-    """Check if a condition key matches a pattern with tag-key placeholders.
+def condition_key_in_list(condition_key: str, condition_keys: list[str]) -> bool:
+    """Check if a condition key matches any key in the list, supporting patterns.
 
-    AWS service definitions use patterns like:
-    - `ssm:resourceTag/tag-key` or `ssm:resourceTag/${TagKey}` to match `ssm:resourceTag/owner`
+    AWS service definitions use patterns with tag-key placeholders like:
+    - `ssm:resourceTag/tag-key` to match `ssm:resourceTag/owner`
     - `aws:ResourceTag/${TagKey}` to match `aws:ResourceTag/Environment`
+    - `s3:RequestObjectTag/<key>` to match `s3:RequestObjectTag/Environment`
 
-    Args:
-        condition_key: The actual condition key from the policy (e.g., "ssm:resourceTag/owner")
-        pattern: The pattern from AWS service definition (e.g., "ssm:resourceTag/tag-key")
-
-    Returns:
-        True if condition_key matches the pattern
-    """
-    # Exact match (fast path)
-    if condition_key == pattern:
-        return True
-
-    # Check for tag-key placeholder patterns
-    for tag_placeholder in AWS_TAG_KEY_PLACEHOLDERS:
-        if tag_placeholder in pattern:
-            # Extract the prefix before the placeholder
-            prefix = pattern.split(tag_placeholder, 1)[0]
-            prefix_with_slash = prefix + "/"
-            # Check if condition_key starts with prefix and has a tag key after it
-            if condition_key.startswith(prefix_with_slash):
-                # Validate tag key format per AWS constraints
-                tag_key = condition_key[len(prefix_with_slash) :]
-                if _is_valid_tag_key(tag_key):
-                    return True
-
-    return False
-
-
-def _condition_key_in_list(condition_key: str, condition_keys: list[str]) -> bool:
-    """Check if a condition key matches any key in the list, supporting patterns.
+    Any pattern containing "/" is treated as a potential tag-key pattern where
+    the prefix before "/" must match exactly and the suffix after "/" in the
+    condition_key must be a valid AWS tag key.
 
     Args:
         condition_key: The condition key to check
@@ -94,13 +68,30 @@ def _condition_key_in_list(condition_key: str, condition_keys: list[str]) -> boo
     if condition_key in condition_keys:
         return True
 
-    # Slower path: check patterns only if no exact match
+    # Check if condition_key could match a pattern (must contain "/")
+    if "/" not in condition_key:
+        return False
+
+    # Extract prefix and tag key from condition_key
+    cond_slash_idx = condition_key.rfind("/")
+    if cond_slash_idx <= 0:
+        return False
+
+    cond_prefix = condition_key[:cond_slash_idx]
+    tag_key = condition_key[cond_slash_idx + 1 :]
+
+    # Validate tag key format
+    if not _is_valid_tag_key(tag_key):
+        return False
+
+    # Check if any pattern has a matching prefix
     for pattern in condition_keys:
-        # Skip exact matches (already checked above)
-        if pattern == condition_key:
+        if "/" not in pattern:
             continue
-        if _matches_condition_key_pattern(condition_key, pattern):
+        pattern_prefix = pattern[: pattern.rfind("/")]
+        if pattern_prefix == cond_prefix:
             return True
+
     return False
 
 
@@ -252,27 +243,35 @@ class ServiceValidator:
             _, action_name = self._parser.parse_action(action)
 
             # Check if it's a global condition key
+            # Note: Some aws: prefixed keys like aws:RequestTag/* and aws:ResourceTag/* are NOT
+            # global keys - they're action-specific or resource-specific. We'll check those later.
             is_global_key = False
             if condition_key.startswith("aws:"):
                 global_conditions = get_global_conditions()
                 if global_conditions.is_valid_global_key(condition_key):
                     is_global_key = True
-                else:
-                    return ConditionKeyValidationResult(
-                        is_valid=False,
-                        error_message=f"Invalid AWS global condition key: `{condition_key}`.",
-                    )
+                # If not a global key, continue to check action/resource-specific keys
+                # Don't return an error yet - aws:RequestTag, aws:ResourceTag are action-specific
 
             # Check service-specific condition keys (with pattern matching for tag keys)
-            if service_detail.condition_keys and _condition_key_in_list(
-                condition_key, list(service_detail.condition_keys.keys())
-            ):
-                return ConditionKeyValidationResult(is_valid=True)
+            # IMPORTANT: aws:RequestTag and aws:ResourceTag patterns in service-level keys
+            # are NOT universally valid for all actions. Skip them here - they'll be checked
+            # at action/resource level.
+            if service_detail.condition_keys:
+                # Check if it matches service-level keys, but exclude RequestTag/ResourceTag
+                if condition_key_in_list(condition_key, list(service_detail.condition_keys.keys())):
+                    # If it's RequestTag or ResourceTag, don't return valid here - check action/resource level
+                    if not (
+                        condition_key.startswith("aws:RequestTag/")
+                        or condition_key.startswith("aws:ResourceTag/")
+                    ):
+                        return ConditionKeyValidationResult(is_valid=True)
+                    # For RequestTag/ResourceTag, continue to check action/resource level
 
             # Check action-specific condition keys
             if action_name in service_detail.actions:
                 action_detail = service_detail.actions[action_name]
-                if action_detail.action_condition_keys and _condition_key_in_list(
+                if action_detail.action_condition_keys and condition_key_in_list(
                     condition_key, action_detail.action_condition_keys
                 ):
                     return ConditionKeyValidationResult(is_valid=True)
@@ -288,7 +287,7 @@ class ServiceValidator:
                         # Look up resource type definition
                         resource_type = service_detail.resources.get(resource_name)
                         if resource_type and resource_type.condition_keys:
-                            if _condition_key_in_list(condition_key, resource_type.condition_keys):
+                            if condition_key_in_list(condition_key, resource_type.condition_keys):
                                 return ConditionKeyValidationResult(is_valid=True)
 
                 # If it's a global key but the action has specific condition keys defined,
@@ -307,8 +306,26 @@ class ServiceValidator:
             if is_global_key:
                 return ConditionKeyValidationResult(is_valid=True)
 
-            # Short error message
-            error_msg = f"Condition key `{condition_key}` is not valid for action `{action}`"
+            # If we reach here, the condition key was not found in any valid location
+            # Check if it's an aws: prefixed key that's not global - provide specific error
+            if condition_key.startswith("aws:"):
+                # Special handling for aws:RequestTag and aws:ResourceTag patterns
+                if condition_key.startswith("aws:RequestTag/"):
+                    error_msg = (
+                        f"Condition key `{condition_key}` is not supported by action `{action}`. "
+                        f"The `aws:RequestTag/${{TagKey}}` condition is only supported by actions that "
+                        f"create or modify resources with tags. This action does not support tag operations."
+                    )
+                elif condition_key.startswith("aws:ResourceTag/"):
+                    error_msg = (
+                        f"Condition key `{condition_key}` is not supported by the resources used by action `{action}`. "
+                        f"The `aws:ResourceTag/${{TagKey}}` condition is only supported by resources that have tags."
+                    )
+                else:
+                    error_msg = f"Invalid AWS condition key: `{condition_key}`. This key is not a valid global condition key and is not supported by action `{action}`."
+            else:
+                # Short error message for non-aws: keys
+                error_msg = f"Condition key `{condition_key}` is not valid for action `{action}`"
 
             # Collect valid condition keys for this action
             valid_keys: set[str] = set()