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

iam_validator/checks/set_operator_validation.py

@@ -73,7 +73,7 @@ class SetOperatorValidationCheck(PolicyCheck):
 
         # First pass: Identify set operators and Null checks
         for operator, conditions in statement.condition.items():
-            base_operator, operator_type, set_prefix = normalize_operator(operator)
+            base_operator, _operator_type, set_prefix = normalize_operator(operator)
 
             # Track Null checks
             if base_operator == "Null":
@@ -87,22 +87,22 @@ class SetOperatorValidationCheck(PolicyCheck):
 
         # Second pass: Validate set operator usage
         for operator, conditions in statement.condition.items():
-            base_operator, operator_type, set_prefix = normalize_operator(operator)
+            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():
+            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"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,
@@ -120,9 +120,9 @@ class SetOperatorValidationCheck(PolicyCheck):
                             ValidationIssue(
                                 severity="warning",
                                 message=(
-                                    f"Security risk: ForAllValues with Allow effect on '{condition_key}' "
+                                    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'`{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,
@@ -140,10 +140,10 @@ class SetOperatorValidationCheck(PolicyCheck):
                             ValidationIssue(
                                 severity="warning",
                                 message=(
-                                    f"Unpredictable behavior: ForAnyValue with Deny effect on '{condition_key}' "
+                                    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"`{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,

iam_validator/checks/sid_uniqueness.py

@@ -35,6 +35,10 @@ def _check_sid_uniqueness_impl(policy: IAMPolicy, severity: str) -> list[Validat
     # 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):
@@ -43,15 +47,15 @@ def _check_sid_uniqueness_impl(policy: IAMPolicy, severity: str) -> list[Validat
             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"
+                    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(' ', '')}'"
+                        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}"
+                    issue_msg = f"Statement ID `{statement.sid}` contains invalid characters: `{invalid_chars}`"
                     suggestion = (
                         "SIDs must contain only alphanumeric characters, hyphens, and underscores"
                     )
@@ -91,7 +95,7 @@ def _check_sid_uniqueness_impl(policy: IAMPolicy, severity: str) -> list[Validat
                     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})",
+                    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,
                 )

iam_validator/checks/trust_policy_validation.py

@@ -0,0 +1,512 @@
+"""Trust Policy Validation Check.
+
+Validates trust policies (role assumption policies) for security best practices.
+This check ensures that assume role actions have appropriate principals and conditions.
+
+Trust policies are resource-based policies attached to IAM roles that control
+who can assume the role and under what conditions.
+
+Key Validations:
+1. Action-Principal Type Matching
+   - sts:AssumeRole → AWS or Service principals
+   - sts:AssumeRoleWithSAML → Federated (SAML provider) principals
+   - sts:AssumeRoleWithWebIdentity → Federated (OIDC provider) principals
+
+2. Provider ARN Validation
+   - SAML providers must match: arn:aws:iam::account:saml-provider/name
+   - OIDC providers must match: arn:aws:iam::account:oidc-provider/domain
+
+3. Required Conditions
+   - SAML: Requires SAML:aud condition
+   - OIDC: Requires provider-specific audience/subject conditions
+   - Cross-account: Should have ExternalId or PrincipalOrgID
+
+Complements existing checks:
+- principal_validation: Validates which principals are allowed/blocked
+- action_condition_enforcement: Validates required conditions for actions
+- trust_policy_validation: Validates action-principal coupling and trust-specific rules
+
+This check is DISABLED by default. Enable it for trust policy validation:
+
+    trust_policy_validation:
+      enabled: true
+      severity: high
+"""
+
+import re
+from typing import TYPE_CHECKING, Any
+
+from iam_validator.core.aws_fetcher import AWSServiceFetcher
+from iam_validator.core.check_registry import CheckConfig, PolicyCheck
+from iam_validator.core.models import Statement, ValidationIssue
+
+if TYPE_CHECKING:
+    pass
+
+
+class TrustPolicyValidationCheck(PolicyCheck):
+    """Validates trust policies for role assumption security."""
+
+    # Default validation rules for assume actions
+    DEFAULT_RULES = {
+        "sts:AssumeRole": {
+            "allowed_principal_types": ["AWS", "Service"],
+            "description": "Standard role assumption",
+        },
+        "sts:AssumeRoleWithSAML": {
+            "allowed_principal_types": ["Federated"],
+            "provider_pattern": r"^arn:aws:iam::\d{12}:saml-provider/[\w+=,.@-]+$",
+            "required_conditions": ["SAML:aud"],
+            "description": "SAML-based federated role assumption",
+        },
+        "sts:AssumeRoleWithWebIdentity": {
+            "allowed_principal_types": ["Federated"],
+            "provider_pattern": r"^arn:aws:iam::\d{12}:oidc-provider/[\w./-]+$",
+            "required_conditions": ["*:aud"],  # Require audience condition (provider-specific key)
+            "description": "OIDC-based federated role assumption",
+        },
+        "sts:TagSession": {
+            "allowed_principal_types": ["AWS", "Service", "Federated"],
+            "description": "Session tagging during role assumption (can be combined with any assume action)",
+        },
+        "sts:SetSourceIdentity": {
+            "allowed_principal_types": ["AWS", "Service", "Federated"],
+            "description": "Set source identity during role assumption (tracks original identity through role chains)",
+        },
+        "sts:SetContext": {
+            "allowed_principal_types": ["AWS", "Service", "Federated"],
+            "description": "Set session context during role assumption",
+        },
+    }
+
+    @property
+    def check_id(self) -> str:
+        return "trust_policy_validation"
+
+    @property
+    def description(self) -> str:
+        return "Validates trust policies for role assumption security and action-principal coupling"
+
+    @property
+    def default_severity(self) -> str:
+        return "high"
+
+    async def execute(
+        self,
+        statement: Statement,
+        statement_idx: int,
+        fetcher: AWSServiceFetcher,
+        config: CheckConfig,
+    ) -> list[ValidationIssue]:
+        """Execute trust policy validation on a single statement.
+
+        Args:
+            statement: The statement to validate
+            statement_idx: Index of the statement in the policy
+            fetcher: AWS service fetcher instance
+            config: Configuration for this check
+
+        Returns:
+            List of validation issues
+        """
+        issues = []
+
+        # Skip if no principal (trust policies must have principals)
+        if statement.principal is None and statement.not_principal is None:
+            return issues
+
+        # Get actions from statement
+        actions = self._get_actions(statement)
+        if not actions:
+            return issues
+
+        # Get validation rules (use custom rules if provided, otherwise defaults)
+        validation_rules = config.config.get("validation_rules", self.DEFAULT_RULES)
+
+        # Check each assume action
+        for action in actions:
+            # Skip wildcard actions (too broad to validate specifically)
+            if action == "*" or action == "sts:*":
+                continue
+
+            # Find matching rule (exact matches for assume actions)
+            rule = self._find_matching_rule(action, validation_rules)
+            if not rule:
+                continue  # Not an assume action we validate
+
+            # Validate principal type for this action
+            principal_issues = self._validate_principal_type(
+                statement, action, rule, statement_idx, config
+            )
+            issues.extend(principal_issues)
+
+            # Validate provider ARN format if required
+            if "provider_pattern" in rule:
+                provider_issues = self._validate_provider_format(
+                    statement, action, rule, statement_idx, config
+                )
+                issues.extend(provider_issues)
+
+            # Validate required conditions
+            if "required_conditions" in rule:
+                condition_issues = self._validate_required_conditions(
+                    statement, action, rule, statement_idx, config
+                )
+                issues.extend(condition_issues)
+
+        return issues
+
+    def _get_actions(self, statement: Statement) -> list[str]:
+        """Extract actions from statement.
+
+        Args:
+            statement: IAM policy statement
+
+        Returns:
+            List of action strings
+        """
+        if statement.action is None:
+            return []
+        return [statement.action] if isinstance(statement.action, str) else statement.action
+
+    def _find_matching_rule(self, action: str, rules: dict[str, Any]) -> dict[str, Any] | None:
+        """Find validation rule matching the action.
+
+        Supports wildcards in action names.
+
+        Args:
+            action: Action to find rule for (e.g., "sts:AssumeRole")
+            rules: Validation rules dict
+
+        Returns:
+            Matching rule dict or None
+        """
+        # Exact match first (performance optimization)
+        if action in rules:
+            return rules[action]
+
+        # Check for wildcard patterns in action
+        for rule_action, rule_config in rules.items():
+            # Support wildcards in the action being validated
+            if "*" in action:
+                pattern = action.replace("*", ".*")
+                if re.match(f"^{pattern}$", rule_action):
+                    return rule_config
+
+        return None
+
+    def _extract_principal_types(self, statement: Statement) -> dict[str, list[str]]:
+        """Extract principals grouped by type (AWS, Service, Federated, etc.).
+
+        Args:
+            statement: IAM policy statement
+
+        Returns:
+            Dict mapping principal type to list of principal values
+        """
+        principal_types: dict[str, list[str]] = {}
+
+        if statement.principal:
+            if isinstance(statement.principal, str):
+                # Simple string principal like "*"
+                principal_types["AWS"] = [statement.principal]
+            elif isinstance(statement.principal, dict):
+                for key, value in statement.principal.items():
+                    if isinstance(value, str):
+                        principal_types[key] = [value]
+                    elif isinstance(value, list):
+                        principal_types[key] = value
+
+        return principal_types
+
+    def _validate_principal_type(
+        self,
+        statement: Statement,
+        action: str,
+        rule: dict[str, Any],
+        statement_idx: int,
+        config: CheckConfig,
+    ) -> list[ValidationIssue]:
+        """Validate that principal type matches the assume action.
+
+        Args:
+            statement: IAM policy statement
+            action: Assume action being validated
+            rule: Validation rule for this action
+            statement_idx: Statement index
+
+        Returns:
+            List of validation issues
+        """
+        issues = []
+
+        allowed_types = rule.get("allowed_principal_types", [])
+        if not allowed_types:
+            return issues
+
+        principal_types = self._extract_principal_types(statement)
+
+        # Check if any principal type is not allowed
+        for principal_type, principals in principal_types.items():
+            if principal_type not in allowed_types:
+                principals_list = ", ".join(f"`{p}`" for p in principals)
+                allowed_list = ", ".join(f"`{t}`" for t in allowed_types)
+
+                issues.append(
+                    ValidationIssue(
+                        severity=self.get_severity(config),
+                        issue_type="invalid_principal_type_for_assume_action",
+                        message=f"Action `{action}` should not use Principal type `{principal_type}`. "
+                        f"Expected principal types: {allowed_list}",
+                        statement_index=statement_idx,
+                        statement_sid=statement.sid,
+                        line_number=statement.line_number,
+                        action=action,
+                        suggestion=f"For `{action}`, use {allowed_list} principal type instead of `{principal_type}`. "
+                        f"\n\nFound principals: `{principals_list}`\n\n"
+                        f"{rule.get('description', '')}",
+                        example=self._get_example_for_action(
+                            action, allowed_types[0] if allowed_types else "AWS"
+                        ),
+                    )
+                )
+
+        return issues
+
+    def _validate_provider_format(
+        self,
+        statement: Statement,
+        action: str,
+        rule: dict[str, Any],
+        statement_idx: int,
+        config: CheckConfig,
+    ) -> list[ValidationIssue]:
+        """Validate that federated provider ARN matches expected format.
+
+        Args:
+            statement: IAM policy statement
+            action: Assume action being validated
+            rule: Validation rule for this action
+            statement_idx: Statement index
+
+        Returns:
+            List of validation issues
+        """
+        issues = []
+
+        provider_pattern = rule.get("provider_pattern")
+        if not provider_pattern:
+            return issues
+
+        principal_types = self._extract_principal_types(statement)
+        federated_principals = principal_types.get("Federated", [])
+
+        for principal in federated_principals:
+            if not re.match(provider_pattern, principal):
+                provider_type = "SAML" if "saml-provider" in provider_pattern else "OIDC"
+
+                issues.append(
+                    ValidationIssue(
+                        severity=self.get_severity(config),
+                        issue_type="invalid_provider_format",
+                        message=f"Federated principal `{principal}` does not match expected `{provider_type}` provider format for `{action}`",
+                        statement_index=statement_idx,
+                        statement_sid=statement.sid,
+                        line_number=statement.line_number,
+                        action=action,
+                        suggestion=f"For `{action}`, use a valid `{provider_type}` provider ARN.\n\n"
+                        f"Expected pattern: `{provider_pattern}`\n"
+                        f"Found: `{principal}`",
+                        example=self._get_provider_example(provider_type),
+                    )
+                )
+
+        return issues
+
+    def _validate_required_conditions(
+        self,
+        statement: Statement,
+        action: str,
+        rule: dict[str, Any],
+        statement_idx: int,
+        config: CheckConfig,
+    ) -> list[ValidationIssue]:
+        """Validate that required conditions are present.
+
+        Args:
+            statement: IAM policy statement
+            action: Assume action being validated
+            rule: Validation rule for this action
+            statement_idx: Statement index
+
+        Returns:
+            List of validation issues
+        """
+        issues = []
+
+        required_conditions = rule.get("required_conditions", [])
+        if not required_conditions:
+            return issues
+
+        # Get all condition keys from statement
+        condition_keys = set()
+        if statement.condition:
+            for _operator, keys_dict in statement.condition.items():
+                if isinstance(keys_dict, dict):
+                    condition_keys.update(keys_dict.keys())
+
+        # Check for missing required conditions (supports wildcards like *:aud)
+        missing_conditions = []
+        for required_cond in required_conditions:
+            if "*:" in required_cond:
+                # Wildcard pattern - check if any key ends with the suffix
+                suffix = required_cond.split("*:")[1]
+                if not any(key.endswith(f":{suffix}") for key in condition_keys):
+                    missing_conditions.append(required_cond)
+            else:
+                # Exact match
+                if required_cond not in condition_keys:
+                    missing_conditions.append(required_cond)
+
+        if missing_conditions:
+            missing_list = ", ".join(f"`{c}`" for c in missing_conditions)
+
+            issues.append(
+                ValidationIssue(
+                    severity=self.get_severity(config),
+                    issue_type="missing_required_condition_for_assume_action",
+                    message=f"Action `{action}` is missing required conditions: `{missing_list}`",
+                    statement_index=statement_idx,
+                    statement_sid=statement.sid,
+                    line_number=statement.line_number,
+                    action=action,
+                    suggestion=f"Add required condition(s) to restrict when `{action}` can be performed. "
+                    f"Missing: `{missing_list}`\n\n"
+                    f"{rule.get('description', '')}",
+                    example=self._get_condition_example(action, required_conditions[0]),
+                )
+            )
+
+        return issues
+
+    def _get_example_for_action(self, action: str, principal_type: str) -> str:
+        """Generate example JSON for an assume action.
+
+        Args:
+            action: Assume action
+            principal_type: Expected principal type
+
+        Returns:
+            JSON example string
+        """
+        examples = {
+            ("sts:AssumeRole", "AWS"): """{
+  "Effect": "Allow",
+  "Principal": {
+    "AWS": "arn:aws:iam::123456789012:root"
+  },
+  "Action": "sts:AssumeRole",
+  "Condition": {
+    "StringEquals": {
+      "sts:ExternalId": "unique-external-id"
+    }
+  }
+}""",
+            ("sts:AssumeRole", "Service"): """{
+  "Effect": "Allow",
+  "Principal": {
+    "Service": "lambda.amazonaws.com"
+  },
+  "Action": "sts:AssumeRole"
+}""",
+            ("sts:AssumeRoleWithSAML", "Federated"): """{
+  "Effect": "Allow",
+  "Principal": {
+    "Federated": "arn:aws:iam::123456789012:saml-provider/MyProvider"
+  },
+  "Action": "sts:AssumeRoleWithSAML",
+  "Condition": {
+    "StringEquals": {
+      "SAML:aud": "https://signin.aws.amazon.com/saml"
+    }
+  }
+}""",
+            ("sts:AssumeRoleWithWebIdentity", "Federated"): """{
+  "Effect": "Allow",
+  "Principal": {
+    "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
+  },
+  "Action": "sts:AssumeRoleWithWebIdentity",
+  "Condition": {
+    "StringEquals": {
+      "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
+    },
+    "StringLike": {
+      "token.actions.githubusercontent.com:sub": "repo:myorg/myrepo:*"
+    }
+  }
+}""",
+        }
+
+        return examples.get((action, principal_type), "")
+
+    def _get_provider_example(self, provider_type: str) -> str:
+        """Get example provider ARN.
+
+        Args:
+            provider_type: Type of provider (SAML or OIDC)
+
+        Returns:
+            Example ARN string
+        """
+        if provider_type == "SAML":
+            return """{
+  "Principal": {
+    "Federated": "arn:aws:iam::123456789012:saml-provider/MyProvider"
+  }
+}"""
+        else:  # OIDC
+            return """{
+  "Principal": {
+    "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
+  }
+}"""
+
+    def _get_condition_example(self, action: str, condition_key: str) -> str:
+        """Get example condition for an action.
+
+        Args:
+            action: Assume action
+            condition_key: Required condition key
+
+        Returns:
+            JSON example string
+        """
+        examples = {
+            "SAML:aud": """{
+  "Condition": {
+    "StringEquals": {
+      "SAML:aud": "https://signin.aws.amazon.com/saml"
+    }
+  }
+}""",
+            "sts:ExternalId": """{
+  "Condition": {
+    "StringEquals": {
+      "sts:ExternalId": "unique-external-id-shared-with-trusted-party"
+    }
+  }
+}""",
+            "aws:PrincipalOrgID": """{
+  "Condition": {
+    "StringEquals": {
+      "aws:PrincipalOrgID": "o-123456789"
+    }
+  }
+}""",
+        }
+
+        return examples.get(
+            condition_key,
+            f'{{\n  "Condition": {{\n    "StringEquals": {{\n      "{condition_key}": "value"\n    }}\n  }}\n}}',
+        )