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

iam_validator/checks/policy_type_validation.py

@@ -0,0 +1,305 @@
+"""Policy Type Validation Check.
+
+This check validates policy-type-specific requirements:
+- Resource policies (RESOURCE_POLICY) must have a Principal element
+- Identity policies (IDENTITY_POLICY) should not have a Principal element
+- Service Control Policies (SERVICE_CONTROL_POLICY) have specific requirements
+- Resource Control Policies (RESOURCE_CONTROL_POLICY) have strict requirements
+
+This check runs automatically based on:
+1. The --policy-type flag value
+2. Auto-detection: If any statement has a Principal, provides helpful guidance
+"""
+
+from iam_validator.core.models import IAMPolicy, ValidationIssue
+
+
+async def execute_policy(
+    policy: IAMPolicy, policy_file: str, policy_type: str = "IDENTITY_POLICY", **kwargs
+) -> list[ValidationIssue]:
+    """Validate policy-type-specific requirements.
+
+    Args:
+        policy: IAM policy document
+        policy_file: Path to policy file
+        policy_type: Type of policy (IDENTITY_POLICY, RESOURCE_POLICY, SERVICE_CONTROL_POLICY)
+        **kwargs: Additional context (fetcher, statement index, etc.)
+
+    Returns:
+        List of validation issues
+    """
+    issues = []
+
+    # Check if any statement has Principal
+    has_any_principal = any(
+        stmt.principal is not None or stmt.not_principal is not None for stmt in policy.statement
+    )
+
+    # If policy has Principal but type is IDENTITY_POLICY (default), provide helpful info
+    if has_any_principal and policy_type == "IDENTITY_POLICY":
+        issues.append(
+            ValidationIssue(
+                severity="info",
+                issue_type="policy_type_hint",
+                message="Policy contains Principal element - this suggests it's a resource policy. "
+                "Use --policy-type RESOURCE_POLICY for proper validation.",
+                statement_index=0,
+                statement_sid=None,
+                line_number=None,
+                suggestion="If this is a resource policy (S3 bucket policy, SNS topic policy, etc.), "
+                "run validation with: iam-validator validate --path <file> --policy-type RESOURCE_POLICY",
+            )
+        )
+        # Don't run further checks if we're just hinting
+        return issues
+
+    # Resource policies MUST have Principal
+    if policy_type == "RESOURCE_POLICY":
+        for idx, statement in enumerate(policy.statement):
+            has_principal = statement.principal is not None or statement.not_principal is not None
+
+            if not has_principal:
+                issues.append(
+                    ValidationIssue(
+                        severity="error",
+                        issue_type="missing_principal",
+                        message="Resource policy statement missing required Principal element. "
+                        "Resource-based policies (S3 bucket policies, SNS topic policies, etc.) "
+                        "must include a Principal element to specify who can access the resource.",
+                        statement_index=idx,
+                        statement_sid=statement.sid,
+                        line_number=statement.line_number,
+                        suggestion="Add a Principal element to specify who can access this resource.\n"
+                        "Example:\n"
+                        "```json\n"
+                        "{\n"
+                        '  "Effect": "Allow",\n'
+                        '  "Principal": {\n'
+                        '    "AWS": "arn:aws:iam::123456789012:root"\n'
+                        "  },\n"
+                        '  "Action": "s3:GetObject",\n'
+                        '  "Resource": "arn:aws:s3:::bucket/*"\n'
+                        "}\n"
+                        "```",
+                    )
+                )
+
+    # Identity policies should NOT have Principal (warning, not error)
+    elif policy_type == "IDENTITY_POLICY":
+        for idx, statement in enumerate(policy.statement):
+            has_principal = statement.principal is not None or statement.not_principal is not None
+
+            if has_principal:
+                issues.append(
+                    ValidationIssue(
+                        severity="warning",
+                        issue_type="unexpected_principal",
+                        message="Identity policy should not contain Principal element. "
+                        "Identity-based policies (attached to IAM users, groups, or roles) "
+                        "do not need a Principal element because the principal is implicit "
+                        "(the entity the policy is attached to).",
+                        statement_index=idx,
+                        statement_sid=statement.sid,
+                        line_number=statement.line_number,
+                        suggestion="Remove the Principal element from this identity policy statement.\n"
+                        "Example:\n"
+                        "```json\n"
+                        "{\n"
+                        '  "Effect": "Allow",\n'
+                        '  "Action": "s3:GetObject",\n'
+                        '  "Resource": "arn:aws:s3:::bucket/*"\n'
+                        "}\n"
+                        "```",
+                    )
+                )
+
+    # Service Control Policies (SCPs) should not have Principal
+    elif policy_type == "SERVICE_CONTROL_POLICY":
+        for idx, statement in enumerate(policy.statement):
+            has_principal = statement.principal is not None or statement.not_principal is not None
+
+            if has_principal:
+                issues.append(
+                    ValidationIssue(
+                        severity="error",
+                        issue_type="invalid_principal",
+                        message="Service Control Policy must not contain Principal element. "
+                        "Service Control Policies (SCPs) in AWS Organizations do not support "
+                        "the Principal element. They apply to all principals in the organization or OU.",
+                        statement_index=idx,
+                        statement_sid=statement.sid,
+                        line_number=statement.line_number,
+                        suggestion="Remove the Principal element from this SCP statement.\n"
+                        "Example:\n"
+                        "```json\n"
+                        "{\n"
+                        '  "Effect": "Deny",\n'
+                        '  "Action": "ec2:*",\n'
+                        '  "Resource": "*",\n'
+                        '  "Condition": {\n'
+                        '    "StringNotEquals": {\n'
+                        '      "ec2:Region": ["us-east-1", "us-west-2"]\n'
+                        "    }\n"
+                        "  }\n"
+                        "}\n"
+                        "```",
+                    )
+                )
+
+    # Resource Control Policies (RCPs) have very strict requirements
+    elif policy_type == "RESOURCE_CONTROL_POLICY":
+        # RCP supported services (as of 2025)
+        rcp_supported_services = {"s3", "sts", "sqs", "secretsmanager", "kms"}
+
+        for idx, statement in enumerate(policy.statement):
+            # 1. Effect MUST be Deny (only RCPFullAWSAccess can use Allow)
+            if statement.effect and statement.effect.lower() != "deny":
+                issues.append(
+                    ValidationIssue(
+                        severity="error",
+                        issue_type="invalid_rcp_effect",
+                        message="Resource Control Policy statement must have Effect: Deny. "
+                        "For RCPs that you create, the Effect value must be 'Deny'. "
+                        "Only the AWS-managed RCPFullAWSAccess policy can use 'Allow'.",
+                        statement_index=idx,
+                        statement_sid=statement.sid,
+                        line_number=statement.line_number,
+                        suggestion='Change the Effect to "Deny" for this RCP statement.',
+                    )
+                )
+
+            # 2. Principal MUST be "*" (and only "*")
+            has_principal = statement.principal is not None
+            has_not_principal = statement.not_principal is not None
+
+            if has_not_principal:
+                issues.append(
+                    ValidationIssue(
+                        severity="error",
+                        issue_type="invalid_rcp_not_principal",
+                        message="Resource Control Policy must not contain NotPrincipal element. "
+                        "RCPs only support Principal with value '*'. Use Condition elements "
+                        "to restrict specific principals.",
+                        statement_index=idx,
+                        statement_sid=statement.sid,
+                        line_number=statement.line_number,
+                        suggestion="Remove NotPrincipal and use Principal: '*' with Condition "
+                        "elements to restrict access.",
+                    )
+                )
+            elif not has_principal:
+                issues.append(
+                    ValidationIssue(
+                        severity="error",
+                        issue_type="missing_rcp_principal",
+                        message="Resource Control Policy statement must have Principal: '*'. "
+                        "RCPs require the Principal element with value '*'. Use Condition "
+                        "elements to restrict specific principals.",
+                        statement_index=idx,
+                        statement_sid=statement.sid,
+                        line_number=statement.line_number,
+                        suggestion='Add Principal: "*" to this RCP statement.',
+                    )
+                )
+            elif statement.principal != "*":
+                # Check if it's the dict format {"AWS": "*"} or other variations
+                principal_str = str(statement.principal)
+                if principal_str != "*":
+                    issues.append(
+                        ValidationIssue(
+                            severity="error",
+                            issue_type="invalid_rcp_principal",
+                            message="Resource Control Policy Principal must be '*'. "
+                            f"Found: {statement.principal}. RCPs can only specify '*' in the "
+                            "Principal element. Use Condition elements to restrict specific principals.",
+                            statement_index=idx,
+                            statement_sid=statement.sid,
+                            line_number=statement.line_number,
+                            suggestion='Change Principal to "*" and use Condition elements to restrict access.',
+                        )
+                    )
+
+            # 3. Check for unsupported actions (actions not in supported services)
+            if statement.action:
+                actions = (
+                    statement.action if isinstance(statement.action, list) else [statement.action]
+                )
+                unsupported_actions = []
+
+                for action in actions:
+                    if isinstance(action, str):
+                        # Check if action uses wildcard "*" alone (not allowed in customer RCPs)
+                        if action == "*":
+                            issues.append(
+                                ValidationIssue(
+                                    severity="error",
+                                    issue_type="invalid_rcp_wildcard_action",
+                                    message="Resource Control Policy must not use '*' alone in Action element. "
+                                    "Customer-managed RCPs cannot use '*' as the action wildcard. "
+                                    "Use service-specific wildcards like 's3:*' instead.",
+                                    statement_index=idx,
+                                    statement_sid=statement.sid,
+                                    line_number=statement.line_number,
+                                    suggestion="Replace '*' with service-specific actions from supported "
+                                    f"services: {', '.join(sorted(rcp_supported_services))}",
+                                )
+                            )
+                        else:
+                            # Extract service from action (format: service:ActionName)
+                            service = action.split(":")[0] if ":" in action else action
+                            # Handle wildcards in service name
+                            service_base = service.rstrip("*")
+
+                            if service_base and service_base not in rcp_supported_services:
+                                unsupported_actions.append(action)
+
+                if unsupported_actions:
+                    issues.append(
+                        ValidationIssue(
+                            severity="error",
+                            issue_type="unsupported_rcp_service",
+                            message=f"Resource Control Policy contains actions from unsupported services: "
+                            f"{', '.join(unsupported_actions)}. RCPs only support these services: "
+                            f"{', '.join(sorted(rcp_supported_services))}",
+                            statement_index=idx,
+                            statement_sid=statement.sid,
+                            line_number=statement.line_number,
+                            suggestion=f"Use only actions from supported RCP services: "
+                            f"{', '.join(sorted(rcp_supported_services))}",
+                        )
+                    )
+
+            # 4. NotAction is not supported in RCPs
+            if statement.not_action:
+                issues.append(
+                    ValidationIssue(
+                        severity="error",
+                        issue_type="invalid_rcp_not_action",
+                        message="Resource Control Policy must not contain NotAction element. "
+                        "RCPs do not support NotAction. Use Action element instead.",
+                        statement_index=idx,
+                        statement_sid=statement.sid,
+                        line_number=statement.line_number,
+                        suggestion="Replace NotAction with Action element listing the specific "
+                        "actions to deny.",
+                    )
+                )
+
+            # 5. Resource or NotResource is required
+            has_resource = statement.resource is not None
+            has_not_resource = statement.not_resource is not None
+
+            if not has_resource and not has_not_resource:
+                issues.append(
+                    ValidationIssue(
+                        severity="error",
+                        issue_type="missing_rcp_resource",
+                        message="Resource Control Policy statement must have Resource or NotResource element.",
+                        statement_index=idx,
+                        statement_sid=statement.sid,
+                        line_number=statement.line_number,
+                        suggestion='Add Resource: "*" or specify specific resource ARNs.',
+                    )
+                )
+
+    return issues