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

iam_validator/core/config/service_principals.py

@@ -0,0 +1,132 @@
+"""
+Service principals utilities for resource policy validation.
+
+This module provides:
+- Default list of common AWS service principals
+- Utility to check if a principal is any AWS service principal
+- Functions to categorize service principals by type
+
+Configuration:
+- Use "*" in allowed_service_principals to allow ALL AWS service principals
+- Use explicit list to restrict to specific services only
+- AWS service principals end with .amazonaws.com or .amazonaws.com.cn
+"""
+
+from typing import Final
+
+# ============================================================================
+# Allowed Service Principals
+# ============================================================================
+# These AWS service principals are commonly used in resource policies
+# and are generally considered safe to allow
+
+DEFAULT_SERVICE_PRINCIPALS: Final[tuple[str, ...]] = (
+    "cloudfront.amazonaws.com",
+    "s3.amazonaws.com",
+    "sns.amazonaws.com",
+    "lambda.amazonaws.com",
+    "logs.amazonaws.com",
+    "events.amazonaws.com",
+    "elasticloadbalancing.amazonaws.com",
+    "cloudtrail.amazonaws.com",
+    "config.amazonaws.com",
+    "backup.amazonaws.com",
+    "cloudwatch.amazonaws.com",
+    "monitoring.amazonaws.com",
+    "ec2.amazonaws.com",
+    "ecs-tasks.amazonaws.com",
+    "eks.amazonaws.com",
+    "apigateway.amazonaws.com",
+)
+
+
+def get_service_principals() -> tuple[str, ...]:
+    """
+    Get tuple of allowed service principals.
+
+    Returns:
+        Tuple of AWS service principal names
+    """
+    return DEFAULT_SERVICE_PRINCIPALS
+
+
+def is_allowed_service_principal(principal: str) -> bool:
+    """
+    Check if a principal is an allowed service principal.
+
+    Args:
+        principal: Principal to check (e.g., "lambda.amazonaws.com")
+
+    Returns:
+        True if principal is in allowed list
+
+    Performance: O(n) but small list (~16 items)
+    """
+    return principal in DEFAULT_SERVICE_PRINCIPALS
+
+
+def is_aws_service_principal(principal: str) -> bool:
+    """
+    Check if a principal is an AWS service principal (any AWS service).
+
+    This checks if the principal matches the AWS service principal pattern.
+    AWS service principals typically end with ".amazonaws.com" or ".amazonaws.com.cn"
+
+    Args:
+        principal: Principal to check (e.g., "lambda.amazonaws.com", "s3.amazonaws.com.cn")
+
+    Returns:
+        True if principal matches AWS service principal pattern
+
+    Examples:
+        >>> is_aws_service_principal("lambda.amazonaws.com")
+        True
+        >>> is_aws_service_principal("s3.amazonaws.com.cn")
+        True
+        >>> is_aws_service_principal("arn:aws:iam::123456789012:root")
+        False
+        >>> is_aws_service_principal("*")
+        False
+    """
+    if not isinstance(principal, str):
+        return False
+
+    # AWS service principals end with .amazonaws.com or .amazonaws.com.cn
+    return principal.endswith(".amazonaws.com") or principal.endswith(".amazonaws.com.cn")
+
+
+def get_service_principals_by_category() -> dict[str, tuple[str, ...]]:
+    """
+    Get service principals organized by service category.
+
+    Returns:
+        Dictionary mapping categories to service principal tuples
+    """
+    return {
+        "storage": (
+            "s3.amazonaws.com",
+            "backup.amazonaws.com",
+        ),
+        "compute": (
+            "lambda.amazonaws.com",
+            "ec2.amazonaws.com",
+            "ecs-tasks.amazonaws.com",
+            "eks.amazonaws.com",
+        ),
+        "networking": (
+            "cloudfront.amazonaws.com",
+            "elasticloadbalancing.amazonaws.com",
+            "apigateway.amazonaws.com",
+        ),
+        "monitoring": (
+            "logs.amazonaws.com",
+            "cloudwatch.amazonaws.com",
+            "monitoring.amazonaws.com",
+            "cloudtrail.amazonaws.com",
+        ),
+        "messaging": (
+            "sns.amazonaws.com",
+            "events.amazonaws.com",
+        ),
+        "management": ("config.amazonaws.com",),
+    }

iam_validator/core/config/wildcards.py

@@ -0,0 +1,127 @@
+"""
+Default wildcard configurations for security best practices checks.
+
+These wildcards define which actions are considered "safe" to use with
+Resource: "*" (e.g., read-only describe operations).
+
+Using Python tuples instead of YAML lists provides:
+- Zero parsing overhead
+- Immutable by default (tuples)
+- Better performance
+- Easy PyPI packaging
+"""
+
+from typing import Final
+
+# ============================================================================
+# Allowed Wildcards for Resource: "*"
+# ============================================================================
+# These action patterns are considered safe to use with wildcard resources
+# They are typically read-only operations that need broad resource access
+
+DEFAULT_ALLOWED_WILDCARDS: Final[tuple[str, ...]] = (
+    # Auto Scaling
+    "autoscaling:Describe*",
+    # CloudWatch
+    "cloudwatch:Describe*",
+    "cloudwatch:Get*",
+    "cloudwatch:List*",
+    # DynamoDB
+    "dynamodb:Describe*",
+    "dynamodb:Get*",
+    "dynamodb:List*",
+    # EC2
+    "ec2:Describe*",
+    "ec2:List*",
+    # Elastic Load Balancing
+    "elasticloadbalancing:Describe*",
+    # IAM (non-sensitive read operations)
+    "iam:Get*",
+    "iam:List*",
+    # KMS
+    "kms:Describe*",
+    # Lambda
+    "lambda:Get*",
+    "lambda:List*",
+    # CloudWatch Logs
+    "logs:Describe*",
+    "logs:Filter*",
+    "logs:Get*",
+    # RDS
+    "rds:Describe*",
+    # Route53
+    "route53:Get*",
+    "route53:List*",
+    # S3 (safe read operations only)
+    "s3:Describe*",
+    "s3:GetBucket*",
+    "s3:GetM*",
+    "s3:List*",
+    # SQS
+    "sqs:Get*",
+    "sqs:List*",
+    # API Gateway
+    "apigateway:GET",
+)
+
+# ============================================================================
+# Service-Level Wildcards (Allowed Services)
+# ============================================================================
+# Services that are allowed to use service-level wildcards like "logs:*"
+# These are typically low-risk monitoring/logging services
+
+DEFAULT_SERVICE_WILDCARDS: Final[tuple[str, ...]] = (
+    "logs",
+    "cloudwatch",
+    "xray",
+)
+
+
+def get_allowed_wildcards() -> tuple[str, ...]:
+    """
+    Get tuple of allowed wildcard action patterns.
+
+    Returns:
+        Tuple of action patterns that are safe to use with Resource: "*"
+    """
+    return DEFAULT_ALLOWED_WILDCARDS
+
+
+def get_allowed_service_wildcards() -> tuple[str, ...]:
+    """
+    Get tuple of services allowed to use service-level wildcards.
+
+    Returns:
+        Tuple of service names (e.g., "logs", "cloudwatch")
+    """
+    return DEFAULT_SERVICE_WILDCARDS
+
+
+def is_allowed_wildcard(pattern: str) -> bool:
+    """
+    Check if a wildcard pattern is in the allowed list.
+
+    Args:
+        pattern: Action pattern to check (e.g., "s3:List*")
+
+    Returns:
+        True if pattern is in allowed wildcards
+
+    Performance: O(n) but typically small list (~25 items)
+    """
+    return pattern in DEFAULT_ALLOWED_WILDCARDS
+
+
+def is_allowed_service_wildcard(service: str) -> bool:
+    """
+    Check if a service is allowed to use service-level wildcards.
+
+    Args:
+        service: Service name (e.g., "logs", "s3")
+
+    Returns:
+        True if service is in allowed list
+
+    Performance: O(n) but very small list (~3 items)
+    """
+    return service in DEFAULT_SERVICE_WILDCARDS

iam_validator/core/constants.py

@@ -0,0 +1,149 @@
+"""
+Core constants for IAM Policy Validator.
+
+This module defines constants used across the validator to ensure consistency
+and provide a single source of truth for shared values. These constants are
+based on AWS service limits and documentation.
+
+References:
+- AWS IAM Policy Size Limits: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html
+- AWS ARN Format: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html
+"""
+
+# ============================================================================
+# ARN Validation
+# ============================================================================
+
+# ARN Validation Pattern
+# This pattern is specifically designed for validation and allows wildcards (*) in region and account fields
+# Unlike the parsing pattern in CompiledPatterns, this is more lenient for validation purposes
+# Supports all AWS partitions: aws, aws-cn, aws-us-gov, aws-eusc, aws-iso*
+DEFAULT_ARN_VALIDATION_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*]*:.+$"
+
+# Maximum allowed ARN length to prevent ReDoS attacks
+# AWS maximum ARN length is approximately 2048 characters
+MAX_ARN_LENGTH = 2048
+
+# ============================================================================
+# AWS IAM Policy Size Limits
+# ============================================================================
+# These limits are enforced by AWS and policies exceeding them will be rejected
+# Note: AWS does not count whitespace when calculating policy size
+
+# Managed policy maximum size (characters, excluding whitespace)
+MAX_MANAGED_POLICY_SIZE = 6144
+
+# Inline policy maximum size for IAM users (characters, excluding whitespace)
+MAX_INLINE_USER_POLICY_SIZE = 2048
+
+# Inline policy maximum size for IAM groups (characters, excluding whitespace)
+MAX_INLINE_GROUP_POLICY_SIZE = 5120
+
+# Inline policy maximum size for IAM roles (characters, excluding whitespace)
+MAX_INLINE_ROLE_POLICY_SIZE = 10240
+
+# Policy size limits dictionary (for backward compatibility and easy lookup)
+AWS_POLICY_SIZE_LIMITS = {
+    "managed": MAX_MANAGED_POLICY_SIZE,
+    "inline_user": MAX_INLINE_USER_POLICY_SIZE,
+    "inline_group": MAX_INLINE_GROUP_POLICY_SIZE,
+    "inline_role": MAX_INLINE_ROLE_POLICY_SIZE,
+}
+
+# ============================================================================
+# Configuration Defaults
+# ============================================================================
+
+# Default configuration file names (searched in order)
+DEFAULT_CONFIG_FILENAMES = [
+    "iam-validator.yaml",
+    "iam-validator.yml",
+    ".iam-validator.yaml",
+    ".iam-validator.yml",
+]
+
+# ============================================================================
+# Severity Levels
+# ============================================================================
+# Severity level groupings for filtering and categorization
+# Used across formatters and report generation
+
+# High severity issues that typically fail validation
+HIGH_SEVERITY_LEVELS = ("error", "critical", "high")
+
+# Medium severity issues (warnings)
+MEDIUM_SEVERITY_LEVELS = ("warning", "medium")
+
+# Low severity issues (informational)
+LOW_SEVERITY_LEVELS = ("info", "low")
+
+# ============================================================================
+# GitHub Integration
+# ============================================================================
+
+# Bot identifier for GitHub comments and reviews
+BOT_IDENTIFIER = "🤖 IAM Policy Validator"
+
+# HTML comment markers for identifying bot-generated content (for cleanup/updates)
+SUMMARY_IDENTIFIER = "<!-- iam-policy-validator-summary -->"
+REVIEW_IDENTIFIER = "<!-- iam-policy-validator-review -->"
+IGNORED_FINDINGS_IDENTIFIER = "<!-- iam-policy-validator-ignored-findings -->"
+
+# GitHub comment size limits
+# GitHub's actual limit is 65536 characters, but we use a smaller limit for safety
+GITHUB_MAX_COMMENT_LENGTH = 65000  # Maximum single comment length
+GITHUB_COMMENT_SPLIT_LIMIT = 60000  # Target size when splitting into multiple parts
+
+# Comment size estimation parameters (used for multi-part comment splitting)
+COMMENT_BASE_OVERHEAD_CHARS = 2000  # Base overhead for headers/footers
+COMMENT_CHARS_PER_ISSUE_ESTIMATE = 500  # Average characters per issue
+COMMENT_CONTINUATION_OVERHEAD_CHARS = 200  # Overhead for continuation markers
+FORMATTING_SAFETY_BUFFER = 100  # Safety buffer for formatting calculations
+
+# ============================================================================
+# Console Display Settings
+# ============================================================================
+
+# Panel width for formatted console output
+CONSOLE_PANEL_WIDTH = 100
+
+# Rich console color styles
+CONSOLE_HEADER_COLOR = "bright_blue"
+
+# ============================================================================
+# Cache and Timeout Settings
+# ============================================================================
+
+# Cache TTL (Time To Live) - 7 days
+DEFAULT_CACHE_TTL_HOURS = 168  # 7 days in hours
+DEFAULT_CACHE_TTL_SECONDS = 604800  # 7 days in seconds (168 * 3600)
+
+# HTTP request timeout in seconds
+DEFAULT_HTTP_TIMEOUT_SECONDS = 30.0
+
+# Time conversion constants
+SECONDS_PER_HOUR = 3600
+
+# ============================================================================
+# Policy Type Restrictions
+# ============================================================================
+
+# AWS services that support Resource Control Policies (RCP)
+# These services can have wildcard actions in RCP policy statements
+# Reference: https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_rcps.html
+RCP_SUPPORTED_SERVICES = frozenset(
+    {
+        "s3",
+        "sts",
+        "sqs",
+        "secretsmanager",
+        "kms",
+    }
+)
+
+# ============================================================================
+# AWS Documentation URLs
+# ============================================================================
+
+# AWS Service Authorization Reference (for finding valid actions, resources, and condition keys)
+AWS_SERVICE_AUTH_REF_URL = "https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html"