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

iam_validator/checks/policy_type_validation.py

@@ -0,0 +1,299 @@
+"""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"
+                        "{\n"
+                        '  "Effect": "Allow",\n'
+                        '  "Principal": {\n'
+                        '    "AWS": "arn:aws:iam::123456789012:root"\n'
+                        "  },\n"
+                        '  "Action": "s3:GetObject",\n'
+                        '  "Resource": "arn:aws:s3:::bucket/*"\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"
+                        "{\n"
+                        '  "Effect": "Allow",\n'
+                        '  "Action": "s3:GetObject",\n'
+                        '  "Resource": "arn:aws:s3:::bucket/*"\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"
+                        "{\n"
+                        '  "Effect": "Deny",\n'
+                        '  "Action": "ec2:*",\n'
+                        '  "Resource": "*",\n'
+                        '  "Condition": {\n'
+                        '    "StringNotEquals": {\n'
+                        '      "ec2:Region": ["us-east-1", "us-west-2"]\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

iam_validator/checks/principal_validation.py

@@ -0,0 +1,282 @@
+"""Principal Validation Check.
+
+Validates Principal elements in resource-based policies for security best practices.
+This check enforces:
+- Blocked principals (e.g., public access via "*")
+- Allowed principals whitelist (optional)
+- Required conditions for specific principals
+- Service principal validation
+
+Only runs for RESOURCE_POLICY type policies.
+"""
+
+import fnmatch
+
+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
+
+
+class PrincipalValidationCheck(PolicyCheck):
+    """Validates Principal elements in resource policies."""
+
+    @property
+    def check_id(self) -> str:
+        return "principal_validation_check"
+
+    @property
+    def description(self) -> str:
+        return "Validates Principal elements in resource policies for security best practices"
+
+    @property
+    def default_severity(self) -> str:
+        return "high"
+
+    async def execute(
+        self,
+        statement: Statement,
+        statement_idx: int,
+        fetcher: AWSServiceFetcher,
+        config: CheckConfig,
+    ) -> list[ValidationIssue]:
+        """Execute principal 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
+        if statement.principal is None and statement.not_principal is None:
+            return issues
+
+        # Get configuration
+        blocked_principals = config.config.get("blocked_principals", ["*"])
+        allowed_principals = config.config.get("allowed_principals", [])
+        require_conditions_for = config.config.get("require_conditions_for", {})
+        allowed_service_principals = config.config.get(
+            "allowed_service_principals",
+            [
+                "cloudfront.amazonaws.com",
+                "s3.amazonaws.com",
+                "sns.amazonaws.com",
+                "lambda.amazonaws.com",
+                "logs.amazonaws.com",
+                "events.amazonaws.com",
+            ],
+        )
+
+        # Extract principals from statement
+        principals = self._extract_principals(statement)
+
+        for principal in principals:
+            # Check if principal is blocked
+            if self._is_blocked_principal(
+                principal, blocked_principals, allowed_service_principals
+            ):
+                issues.append(
+                    ValidationIssue(
+                        severity=self.get_severity(config),
+                        issue_type="blocked_principal",
+                        message=f"Blocked principal detected: {principal}. "
+                        f"This principal is explicitly blocked by your security policy.",
+                        statement_index=statement_idx,
+                        statement_sid=statement.sid,
+                        line_number=statement.line_number,
+                        suggestion=f"Remove the principal '{principal}' or add appropriate conditions to restrict access. "
+                        "Consider using more specific principals instead of wildcards.",
+                    )
+                )
+                continue
+
+            # Check if principal is in whitelist (if whitelist is configured)
+            if allowed_principals and not self._is_allowed_principal(
+                principal, allowed_principals, allowed_service_principals
+            ):
+                issues.append(
+                    ValidationIssue(
+                        severity=self.get_severity(config),
+                        issue_type="unauthorized_principal",
+                        message=f"Principal not in allowed list: {principal}. "
+                        f"Only principals in the allowed_principals whitelist are permitted.",
+                        statement_index=statement_idx,
+                        statement_sid=statement.sid,
+                        line_number=statement.line_number,
+                        suggestion=f"Add '{principal}' to the allowed_principals list in your config, "
+                        "or use a principal that matches an allowed pattern.",
+                    )
+                )
+                continue
+
+            # Check if principal requires conditions
+            required_conditions = self._get_required_conditions(principal, require_conditions_for)
+            if required_conditions:
+                missing_conditions = self._check_required_conditions(statement, required_conditions)
+                if missing_conditions:
+                    issues.append(
+                        ValidationIssue(
+                            severity=self.get_severity(config),
+                            issue_type="missing_principal_conditions",
+                            message=f"Principal '{principal}' requires conditions: {', '.join(missing_conditions)}. "
+                            f"This principal must have these condition keys to restrict access.",
+                            statement_index=statement_idx,
+                            statement_sid=statement.sid,
+                            line_number=statement.line_number,
+                            suggestion=f"Add conditions to restrict access:\n"
+                            f"Example:\n"
+                            f'"Condition": {{\n'
+                            f'  "StringEquals": {{\n'
+                            f'    "{missing_conditions[0]}": "value"\n'
+                            f"  }}\n"
+                            f"}}",
+                        )
+                    )
+
+        return issues
+
+    def _extract_principals(self, statement: Statement) -> list[str]:
+        """Extract all principals from a statement.
+
+        Args:
+            statement: The statement to extract principals from
+
+        Returns:
+            List of principal strings
+        """
+        principals = []
+
+        # Handle Principal field
+        if statement.principal:
+            if isinstance(statement.principal, str):
+                # Simple string principal like "*"
+                principals.append(statement.principal)
+            elif isinstance(statement.principal, dict):
+                # Dict with AWS, Service, Federated, etc.
+                for key, value in statement.principal.items():
+                    if isinstance(value, str):
+                        principals.append(value)
+                    elif isinstance(value, list):
+                        principals.extend(value)
+
+        # Handle NotPrincipal field (similar logic)
+        if statement.not_principal:
+            if isinstance(statement.not_principal, str):
+                principals.append(statement.not_principal)
+            elif isinstance(statement.not_principal, dict):
+                for key, value in statement.not_principal.items():
+                    if isinstance(value, str):
+                        principals.append(value)
+                    elif isinstance(value, list):
+                        principals.extend(value)
+
+        return principals
+
+    def _is_blocked_principal(
+        self, principal: str, blocked_list: list[str], service_whitelist: list[str]
+    ) -> bool:
+        """Check if a principal is blocked.
+
+        Args:
+            principal: The principal to check
+            blocked_list: List of blocked principal patterns
+            service_whitelist: List of allowed service principals
+
+        Returns:
+            True if the principal is blocked
+        """
+        # Service principals are never blocked
+        if principal in service_whitelist:
+            return False
+
+        # Check against blocked list (supports wildcards)
+        for blocked_pattern in blocked_list:
+            # Special case: "*" in blocked list should only match literal "*" (public access)
+            # not use it as a wildcard pattern that matches everything
+            if blocked_pattern == "*":
+                if principal == "*":
+                    return True
+            elif fnmatch.fnmatch(principal, blocked_pattern):
+                return True
+
+        return False
+
+    def _is_allowed_principal(
+        self, principal: str, allowed_list: list[str], service_whitelist: list[str]
+    ) -> bool:
+        """Check if a principal is in the allowed list.
+
+        Args:
+            principal: The principal to check
+            allowed_list: List of allowed principal patterns
+            service_whitelist: List of allowed service principals
+
+        Returns:
+            True if the principal is allowed
+        """
+        # Service principals are always allowed
+        if principal in service_whitelist:
+            return True
+
+        # Check against allowed list (supports wildcards)
+        for allowed_pattern in allowed_list:
+            # Special case: "*" in allowed list should only match literal "*" (public access)
+            # not use it as a wildcard pattern that matches everything
+            if allowed_pattern == "*":
+                if principal == "*":
+                    return True
+            elif fnmatch.fnmatch(principal, allowed_pattern):
+                return True
+
+        return False
+
+    def _get_required_conditions(
+        self, principal: str, requirements: dict[str, list[str]]
+    ) -> list[str]:
+        """Get required condition keys for a principal.
+
+        Args:
+            principal: The principal to check
+            requirements: Dict mapping principal patterns to required condition keys
+
+        Returns:
+            List of required condition keys
+        """
+        for pattern, condition_keys in requirements.items():
+            # Special case: "*" pattern should only match literal "*" (public access)
+            if pattern == "*":
+                if principal == "*":
+                    return condition_keys
+            elif fnmatch.fnmatch(principal, pattern):
+                return condition_keys
+        return []
+
+    def _check_required_conditions(
+        self, statement: Statement, required_keys: list[str]
+    ) -> list[str]:
+        """Check if statement has required condition keys.
+
+        Args:
+            statement: The statement to check
+            required_keys: List of required condition keys
+
+        Returns:
+            List of missing condition keys
+        """
+        if not statement.condition:
+            return required_keys
+
+        # Flatten all condition keys from all condition operators
+        present_keys = set()
+        for operator_conditions in statement.condition.values():
+            if isinstance(operator_conditions, dict):
+                present_keys.update(operator_conditions.keys())
+
+        # Find missing keys
+        missing = [key for key in required_keys if key not in present_keys]
+        return missing

iam_validator/checks/resource_validation.py

@@ -0,0 +1,108 @@
+"""Resource validation check - validates ARN formats."""
+
+import re
+
+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
+
+
+class ResourceValidationCheck(PolicyCheck):
+    """Validates ARN format for resources."""
+
+    # Maximum allowed length for ARN to prevent ReDoS attacks
+    MAX_ARN_LENGTH = 2048  # AWS max ARN length is ~2048 characters
+
+    @property
+    def check_id(self) -> str:
+        return "resource_validation"
+
+    @property
+    def description(self) -> str:
+        return "Validates ARN format for resources"
+
+    @property
+    def default_severity(self) -> str:
+        return "error"
+
+    async def execute(
+        self,
+        statement: Statement,
+        statement_idx: int,
+        fetcher: AWSServiceFetcher,
+        config: CheckConfig,
+    ) -> list[ValidationIssue]:
+        """Execute resource ARN validation on a statement."""
+        issues = []
+
+        # Get resources from statement
+        resources = statement.get_resources()
+        statement_sid = statement.sid
+        line_number = statement.line_number
+
+        # Get ARN pattern from config, or use default
+        # Pattern allows wildcards (*) in region and account fields
+        arn_pattern_str = config.config.get(
+            "arn_pattern",
+            r"^arn:(aws|aws-cn|aws-us-gov|aws-eusc|aws-iso|aws-iso-b|aws-iso-e|aws-iso-f):[a-z0-9\-]+:[a-z0-9\-*]*:[0-9*]*:.+$",
+        )
+
+        # Compile pattern with timeout protection (available in Python 3.11+)
+        try:
+            arn_pattern = re.compile(arn_pattern_str)
+        except re.error:
+            # Fallback to using fetcher's pre-compiled pattern
+            arn_pattern = fetcher._patterns.arn_pattern
+
+        for resource in resources:
+            # Skip wildcard resources (handled by security checks)
+            if resource == "*":
+                continue
+
+            # Validate ARN length to prevent ReDoS attacks
+            if len(resource) > self.MAX_ARN_LENGTH:
+                issues.append(
+                    ValidationIssue(
+                        severity=self.get_severity(config),
+                        statement_sid=statement_sid,
+                        statement_index=statement_idx,
+                        issue_type="invalid_resource",
+                        message=f"Resource ARN exceeds maximum length ({len(resource)} > {self.MAX_ARN_LENGTH}): {resource[:100]}...",
+                        resource=resource[:100] + "...",
+                        suggestion="ARN is too long and may be invalid",
+                        line_number=line_number,
+                    )
+                )
+                continue
+
+            # Validate ARN format
+            try:
+                if not arn_pattern.match(resource):
+                    issues.append(
+                        ValidationIssue(
+                            severity=self.get_severity(config),
+                            statement_sid=statement_sid,
+                            statement_index=statement_idx,
+                            issue_type="invalid_resource",
+                            message=f"Invalid ARN format: {resource}",
+                            resource=resource,
+                            suggestion="ARN should follow format: arn:partition:service:region:account-id:resource",
+                            line_number=line_number,
+                        )
+                    )
+            except Exception:
+                # If regex matching fails (shouldn't happen with length check), treat as invalid
+                issues.append(
+                    ValidationIssue(
+                        severity=self.get_severity(config),
+                        statement_sid=statement_sid,
+                        statement_index=statement_idx,
+                        issue_type="invalid_resource",
+                        message=f"Could not validate ARN format: {resource}",
+                        resource=resource,
+                        suggestion="ARN validation failed - may contain unexpected characters",
+                        line_number=line_number,
+                    )
+                )
+
+        return issues