iam-policy-validator 1.14.0__py3-none-any.whl

iam_validator/checks/set_operator_validation.py

@@ -0,0 +1,153 @@
+"""Set Operator Validation Check.
+
+Validates proper usage of ForAllValues and ForAnyValue set operators in IAM policies.
+
+Based on AWS IAM best practices:
+https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-single-vs-multi-valued-context-keys.html
+"""
+
+from typing import ClassVar
+
+from iam_validator.core.aws_service import AWSServiceFetcher
+from iam_validator.core.check_registry import CheckConfig, PolicyCheck
+from iam_validator.core.condition_validators import (
+    is_multivalued_context_key,
+    normalize_operator,
+)
+from iam_validator.core.models import Statement, ValidationIssue
+
+
+class SetOperatorValidationCheck(PolicyCheck):
+    """Check for proper usage of ForAllValues and ForAnyValue set operators."""
+
+    check_id: ClassVar[str] = "set_operator_validation"
+    description: ClassVar[str] = (
+        "Validates proper usage of ForAllValues and ForAnyValue set operators"
+    )
+    default_severity: ClassVar[str] = "error"
+
+    async def execute(
+        self,
+        statement: Statement,
+        statement_idx: int,
+        fetcher: AWSServiceFetcher,
+        config: CheckConfig,
+    ) -> list[ValidationIssue]:
+        """
+        Execute the set operator validation check.
+
+        Validates:
+        1. ForAllValues/ForAnyValue not used with single-valued context keys (anti-pattern)
+        2. ForAllValues with Allow effect includes Null condition check (security)
+        3. ForAnyValue with Deny effect includes Null condition check (predictability)
+
+        Args:
+            statement: The IAM statement to check
+            statement_idx: Index of this statement in the policy
+            fetcher: AWS service fetcher (unused but required by interface)
+            config: Check configuration
+
+        Returns:
+            List of validation issues found
+        """
+        issues = []
+
+        # Only check statements with conditions
+        if not statement.condition:
+            return issues
+
+        statement_sid = statement.sid
+        line_number = statement.line_number
+        effect = statement.effect
+
+        # Track which condition keys have set operators and Null checks
+        set_operator_keys: dict[str, str] = {}  # key -> operator prefix
+        null_checked_keys: set[str] = set()
+
+        # First pass: Identify set operators and Null checks
+        for operator, conditions in statement.condition.items():
+            base_operator, _operator_type, set_prefix = normalize_operator(operator)
+
+            # Track Null checks
+            if base_operator == "Null":
+                for condition_key in conditions.keys():
+                    null_checked_keys.add(condition_key)
+
+            # Track set operators
+            if set_prefix in ["ForAllValues", "ForAnyValue"]:
+                for condition_key in conditions.keys():
+                    set_operator_keys[condition_key] = set_prefix
+
+        # Second pass: Validate set operator usage
+        for operator, conditions in statement.condition.items():
+            base_operator, _operator_type, set_prefix = normalize_operator(operator)
+
+            if not set_prefix:
+                continue
+
+            # Check each condition key used with a set operator
+            for condition_key, _condition_values in conditions.items():
+                # Issue 1: Set operator used with single-valued context key (anti-pattern)
+                if not is_multivalued_context_key(condition_key):
+                    issues.append(
+                        ValidationIssue(
+                            severity=self.get_severity(config),
+                            message=(
+                                f"Set operator `{set_prefix}` should not be used with single-valued "
+                                f"condition key `{condition_key}`. This can lead to overly permissive policies. "
+                                f"Set operators are designed for multivalued context keys like `aws:TagKeys`. "
+                                f"See: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-single-vs-multi-valued-context-keys.html"
+                            ),
+                            statement_sid=statement_sid,
+                            statement_index=statement_idx,
+                            issue_type="set_operator_on_single_valued_key",
+                            condition_key=condition_key,
+                            line_number=line_number,
+                            field_name="condition",
+                        )
+                    )
+
+                # Issue 2: ForAllValues with Allow effect without Null check (security risk)
+                if set_prefix == "ForAllValues" and effect == "Allow":
+                    if condition_key not in null_checked_keys:
+                        issues.append(
+                            ValidationIssue(
+                                severity="warning",
+                                message=(
+                                    f"Security risk: `ForAllValues` with `Allow` effect on `{condition_key}` "
+                                    f"should include a `Null` condition check. Without it, requests with missing "
+                                    f'`{condition_key}` will be granted access. Add: `"Null": {{"{condition_key}": "false"}}`. '
+                                    f"See: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-single-vs-multi-valued-context-keys.html"
+                                ),
+                                statement_sid=statement_sid,
+                                statement_index=statement_idx,
+                                issue_type="forallvalues_allow_without_null_check",
+                                condition_key=condition_key,
+                                line_number=line_number,
+                                field_name="condition",
+                            )
+                        )
+
+                # Issue 3: ForAnyValue with Deny effect without Null check (unpredictable)
+                if set_prefix == "ForAnyValue" and effect == "Deny":
+                    if condition_key not in null_checked_keys:
+                        issues.append(
+                            ValidationIssue(
+                                severity="warning",
+                                message=(
+                                    f"Unpredictable behavior: `ForAnyValue` with `Deny` effect on `{condition_key}` "
+                                    f"should include a `Null` condition check. Without it, requests with missing "
+                                    f"`{condition_key}` will evaluate to `No match` instead of denying access. "
+                                    f'Add: `"Null": {{"{condition_key}": "false"}}`. '
+                                    f"See: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-single-vs-multi-valued-context-keys.html"
+                                ),
+                                statement_sid=statement_sid,
+                                statement_index=statement_idx,
+                                issue_type="foranyvalue_deny_without_null_check",
+                                field_name="condition",
+                                condition_key=condition_key,
+                                line_number=line_number,
+                            )
+                        )
+
+        return issues

iam_validator/checks/sid_uniqueness.py

@@ -0,0 +1,146 @@
+"""Statement ID (SID) uniqueness and format check.
+
+This check validates that Statement IDs (Sids):
+1. Are unique within a policy
+2. Follow AWS naming requirements (alphanumeric, hyphens, underscores only - no spaces)
+
+According to AWS best practices, while not strictly required, having unique SIDs
+makes it easier to reference specific statements and improves policy maintainability.
+
+This is implemented as a policy-level check that runs once when processing the first
+statement, examining all statements in the policy to find duplicates and format issues.
+"""
+
+import re
+from collections import Counter
+from typing import ClassVar
+
+from iam_validator.core.aws_service import AWSServiceFetcher
+from iam_validator.core.check_registry import CheckConfig, PolicyCheck
+from iam_validator.core.models import IAMPolicy, ValidationIssue
+
+
+def _check_sid_uniqueness_impl(policy: IAMPolicy, severity: str) -> list[ValidationIssue]:
+    """Implementation of SID uniqueness and format checking.
+
+    Args:
+        policy: IAM policy to validate
+        severity: Severity level for issues found
+
+    Returns:
+        List of ValidationIssue objects for duplicate or invalid SIDs
+    """
+    issues: list[ValidationIssue] = []
+
+    # AWS SID requirements: alphanumeric characters, hyphens, and underscores only
+    # No spaces allowed
+    sid_pattern = re.compile(r"^[a-zA-Z0-9_-]+$")
+
+    # Handle policies with no statements
+    if not policy.statement:
+        return []
+
+    # Collect all SIDs (ignoring None/empty values) and check format
+    sids_with_indices: list[tuple[str, int]] = []
+    for idx, statement in enumerate(policy.statement):
+        if statement.sid:  # Only check statements that have a SID
+            # Check SID format
+            if not sid_pattern.match(statement.sid):
+                # Identify the issue
+                if " " in statement.sid:
+                    issue_msg = f"Statement ID `{statement.sid}` contains spaces, which are not allowed by AWS"
+                    suggestion = (
+                        f"Remove spaces from the SID. Example: `{statement.sid.replace(' ', '')}`"
+                    )
+                else:
+                    invalid_chars = "".join(
+                        set(c for c in statement.sid if not c.isalnum() and c not in "_-")
+                    )
+                    issue_msg = f"Statement ID `{statement.sid}` contains invalid characters: `{invalid_chars}`"
+                    suggestion = (
+                        "SIDs must contain only alphanumeric characters, hyphens, and underscores"
+                    )
+
+                issues.append(
+                    ValidationIssue(
+                        severity="error",  # Invalid SID format is an error
+                        statement_sid=statement.sid,
+                        statement_index=idx,
+                        issue_type="invalid_sid_format",
+                        message=issue_msg,
+                        suggestion=suggestion,
+                        line_number=statement.line_number,
+                        field_name="sid",
+                    )
+                )
+
+            sids_with_indices.append((statement.sid, idx))
+
+    # Find duplicates
+    sid_counts = Counter(sid for sid, _ in sids_with_indices)
+    duplicate_sids = {sid: count for sid, count in sid_counts.items() if count > 1}
+
+    # Create issues for each duplicate SID
+    for duplicate_sid, count in duplicate_sids.items():
+        # Find all statement indices with this SID
+        indices = [idx for sid, idx in sids_with_indices if sid == duplicate_sid]
+
+        # Create an issue for each occurrence except the first
+        # (the first occurrence is "original", subsequent ones are "duplicates")
+        for idx in indices[1:]:
+            statement = policy.statement[idx]
+            # Convert to 1-indexed statement numbers for user-facing message
+            statement_numbers = ", ".join(f"#{i + 1}" for i in indices)
+            issues.append(
+                ValidationIssue(
+                    severity=severity,
+                    statement_sid=duplicate_sid,
+                    statement_index=idx,
+                    issue_type="duplicate_sid",
+                    message=f"Statement ID `{duplicate_sid}` is used **{count} times** in this policy (found in statements `{statement_numbers}`)",
+                    suggestion="Change this SID to a unique value. Statement IDs help identify and reference specific statements, so duplicates can cause confusion.",
+                    line_number=statement.line_number,
+                    field_name="sid",
+                )
+            )
+
+    return issues
+
+
+class SidUniquenessCheck(PolicyCheck):
+    """Validates that Statement IDs (Sids) are unique within a policy.
+
+    This is a special policy-level check that examines all statements together.
+    It only runs once when processing the first statement to avoid duplicate work.
+    """
+
+    check_id: ClassVar[str] = "sid_uniqueness"
+    description: ClassVar[str] = (
+        "Validates that Statement IDs (Sids) are unique and follow AWS naming requirements (no spaces)"
+    )
+    default_severity: ClassVar[str] = "warning"
+
+    async def execute_policy(
+        self,
+        policy: IAMPolicy,
+        policy_file: str,
+        fetcher: AWSServiceFetcher,
+        config: CheckConfig,
+        **kwargs,
+    ) -> list[ValidationIssue]:
+        """Execute the SID uniqueness check on the entire policy.
+
+        This method examines all statements together to find duplicate SIDs.
+
+        Args:
+            policy: The complete IAM policy to validate
+            policy_file: Path to the policy file (unused, kept for API consistency)
+            fetcher: AWS service fetcher (unused for this check)
+            config: Configuration for this check instance
+
+        Returns:
+            List of ValidationIssue objects for duplicate SIDs
+        """
+        del policy_file, fetcher  # Unused
+        severity = self.get_severity(config)
+        return _check_sid_uniqueness_impl(policy, severity)