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

iam_validator/core/config/__init__.py

@@ -0,0 +1,81 @@
+"""
+Core configuration modules for IAM Policy Validator.
+
+This package contains default configuration data used by validators, organized into
+logical modules for better maintainability and performance.
+
+All configuration is defined as Python code (not YAML/JSON) for:
+- Faster loading (no parsing overhead)
+- Better PyPI packaging (no data files to manage)
+- Type hints and IDE support
+- Compiled to .pyc for even faster imports
+
+Performance benefits:
+- 5-10x faster than YAML parsing
+- Zero runtime parsing overhead
+- Lazy loading support
+- O(1) frozenset lookups
+"""
+
+from iam_validator.core.config.aws_api import (
+    AWS_SERVICE_REFERENCE_BASE_URL,
+    get_service_reference_url,
+)
+from iam_validator.core.config.aws_global_conditions import (
+    AWS_GLOBAL_CONDITION_KEYS,
+    AWSGlobalConditions,
+    get_global_conditions,
+)
+from iam_validator.core.config.condition_requirements import CONDITION_REQUIREMENTS
+from iam_validator.core.config.defaults import DEFAULT_CONFIG
+from iam_validator.core.config.principal_requirements import (
+    ALL_PRINCIPAL_REQUIREMENTS,
+    DEFAULT_ENABLED_REQUIREMENTS,
+    get_all_principal_requirement_names,
+    get_default_principal_requirements,
+    get_principal_requirement,
+    get_principal_requirements_by_names,
+    get_principal_requirements_by_severity,
+)
+from iam_validator.core.config.sensitive_actions import (
+    DEFAULT_SENSITIVE_ACTIONS,
+    get_sensitive_actions,
+)
+from iam_validator.core.config.service_principals import DEFAULT_SERVICE_PRINCIPALS
+from iam_validator.core.config.wildcards import (
+    DEFAULT_ALLOWED_WILDCARDS,
+    DEFAULT_SERVICE_WILDCARDS,
+)
+
+# NOTE: ConfigLoader is NOT imported here to avoid circular imports
+# Import it directly from iam_validator.core.config.config_loader when needed
+
+__all__ = [
+    # Default configuration
+    "DEFAULT_CONFIG",
+    # AWS API endpoints
+    "AWS_SERVICE_REFERENCE_BASE_URL",
+    "get_service_reference_url",
+    # AWS Global Conditions
+    "AWS_GLOBAL_CONDITION_KEYS",
+    "AWSGlobalConditions",
+    "get_global_conditions",
+    # Sensitive actions
+    "DEFAULT_SENSITIVE_ACTIONS",
+    "get_sensitive_actions",
+    # Condition requirements (for actions)
+    "CONDITION_REQUIREMENTS",
+    # Principal requirements (for principals)
+    "ALL_PRINCIPAL_REQUIREMENTS",
+    "DEFAULT_ENABLED_REQUIREMENTS",
+    "get_default_principal_requirements",
+    "get_principal_requirement",
+    "get_all_principal_requirement_names",
+    "get_principal_requirements_by_names",
+    "get_principal_requirements_by_severity",
+    # Wildcards
+    "DEFAULT_ALLOWED_WILDCARDS",
+    "DEFAULT_SERVICE_WILDCARDS",
+    # Service principals
+    "DEFAULT_SERVICE_PRINCIPALS",
+]

iam_validator/core/config/aws_api.py

@@ -0,0 +1,35 @@
+"""
+AWS API configuration constants.
+
+This module centralizes AWS API endpoints and related configuration
+used throughout the IAM Policy Validator.
+"""
+
+# AWS Service Reference API base URL
+# This is the official AWS service reference that provides action, resource, and condition key metadata
+AWS_SERVICE_REFERENCE_BASE_URL = "https://servicereference.us-east-1.amazonaws.com/"
+
+# Alternative endpoints for different regions (currently not used, but available for future expansion)
+AWS_SERVICE_REFERENCE_ENDPOINTS = {
+    "us-east-1": "https://servicereference.us-east-1.amazonaws.com/",
+    # Add other regional endpoints if they become available
+}
+
+
+def get_service_reference_url(region: str = "us-east-1") -> str:
+    """
+    Get the AWS Service Reference API URL for a specific region.
+
+    Args:
+        region: AWS region (default: us-east-1)
+
+    Returns:
+        The service reference base URL for the specified region
+
+    Example:
+        >>> get_service_reference_url()
+        'https://servicereference.us-east-1.amazonaws.com/'
+        >>> get_service_reference_url("us-east-1")
+        'https://servicereference.us-east-1.amazonaws.com/'
+    """
+    return AWS_SERVICE_REFERENCE_ENDPOINTS.get(region, AWS_SERVICE_REFERENCE_BASE_URL)

iam_validator/core/config/aws_global_conditions.py

@@ -0,0 +1,160 @@
+"""
+AWS Global Condition Keys Management.
+
+Provides access to the list of valid AWS global condition keys
+that can be used across all AWS services.
+
+Reference: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html
+Last updated: 2025-01-17
+"""
+
+import re
+from typing import Any
+
+# AWS Global Condition Keys with Type Information
+# These condition keys are available for use in IAM policies across all AWS services
+# Format: {key: type} where type is one of: String, ARN, Bool, Date, IPAddress, Numeric
+AWS_GLOBAL_CONDITION_KEYS = {
+    # Properties of the Principal
+    "aws:PrincipalArn": "ARN",  # ARN of the principal making the request
+    "aws:PrincipalAccount": "String",  # Account to which the requesting principal belongs
+    "aws:PrincipalOrgPaths": "String",  # AWS Organizations path for the principal
+    "aws:PrincipalOrgID": "String",  # Organization identifier of the principal
+    "aws:PrincipalIsAWSService": "Bool",  # Checks if call is made directly by AWS service principal
+    "aws:PrincipalServiceName": "String",  # Service principal name making the request
+    "aws:PrincipalServiceNamesList": "String",  # List of all service principal names
+    "aws:PrincipalType": "String",  # Type of principal making the request
+    "aws:userid": "String",  # Principal identifier of the requester
+    "aws:username": "String",  # User name of the requester
+    # Properties of a Role Session
+    "aws:AssumedRoot": "Bool",  # Checks if request used AssumeRoot for privileged access
+    "aws:FederatedProvider": "String",  # Principal's issuing identity provider
+    "aws:TokenIssueTime": "Date",  # When temporary security credentials were issued
+    "aws:MultiFactorAuthAge": "Numeric",  # Seconds since MFA authorization
+    "aws:MultiFactorAuthPresent": "Bool",  # Whether MFA was used for temporary credentials
+    "aws:ChatbotSourceArn": "ARN",  # Source chat configuration ARN
+    "aws:Ec2InstanceSourceVpc": "String",  # VPC where EC2 IAM role credentials were delivered
+    "aws:Ec2InstanceSourcePrivateIPv4": "IPAddress",  # Private IPv4 of EC2 instance
+    "aws:SourceIdentity": "String",  # Source identity set when assuming a role
+    "ec2:RoleDelivery": "Numeric",  # Instance metadata service version
+    # Network Properties
+    "aws:SourceIp": "IPAddress",  # Requester's IP address (IPv4/IPv6)
+    "aws:SourceVpc": "String",  # VPC through which request travels
+    "aws:SourceVpce": "String",  # VPC endpoint identifier
+    "aws:VpceAccount": "String",  # AWS account owning the VPC endpoint
+    "aws:VpceOrgID": "String",  # Organization ID of VPC endpoint owner
+    "aws:VpceOrgPaths": "String",  # AWS Organizations path of VPC endpoint
+    "aws:VpcSourceIp": "IPAddress",  # IP address from VPC endpoint request
+    # Resource Properties
+    "aws:ResourceAccount": "String",  # Resource owner's AWS account ID
+    "aws:ResourceOrgID": "String",  # Organization ID of resource owner
+    "aws:ResourceOrgPaths": "String",  # AWS Organizations path of resource
+    # Request Properties
+    "aws:CurrentTime": "Date",  # Current date and time
+    "aws:EpochTime": "Date",  # Request timestamp in epoch format (also accepts Numeric)
+    "aws:referer": "String",  # HTTP referer header value (note: lowercase 'r')
+    "aws:Referer": "String",  # HTTP referer header value (alternate capitalization)
+    "aws:RequestedRegion": "String",  # AWS Region for the request
+    "aws:TagKeys": "String",  # Tag keys present in request
+    "aws:SecureTransport": "Bool",  # Whether HTTPS was used
+    "aws:SourceAccount": "String",  # Account making the request
+    "aws:SourceArn": "ARN",  # ARN of request source
+    "aws:SourceOrgID": "String",  # Organization ID of request source
+    "aws:SourceOrgPaths": "String",  # Organization paths of request source
+    "aws:UserAgent": "String",  # HTTP user agent string
+    # Cross-Service Keys
+    "aws:CalledVia": "String",  # Services called in request chain
+    "aws:CalledViaFirst": "String",  # First service in call chain
+    "aws:CalledViaLast": "String",  # Last service in call chain
+    "aws:ViaAWSService": "Bool",  # Whether AWS service made the request
+}
+
+# Patterns that should be recognized (wildcards and tag-based keys)
+# These allow things like aws:RequestTag/Department or aws:PrincipalTag/Environment
+AWS_CONDITION_KEY_PATTERNS = [
+    {
+        "pattern": r"^aws:RequestTag/[a-zA-Z0-9+\-=._:/@]+$",
+        "description": "Tag keys in the request (for tag-based access control)",
+    },
+    {
+        "pattern": r"^aws:ResourceTag/[a-zA-Z0-9+\-=._:/@]+$",
+        "description": "Tags on the resource being accessed",
+    },
+    {
+        "pattern": r"^aws:PrincipalTag/[a-zA-Z0-9+\-=._:/@]+$",
+        "description": "Tags attached to the principal making the request",
+    },
+]
+
+
+class AWSGlobalConditions:
+    """Manages AWS global condition keys."""
+
+    def __init__(self):
+        """Initialize with global condition keys."""
+        self._global_keys: dict[str, str] = AWS_GLOBAL_CONDITION_KEYS.copy()
+        self._patterns: list[dict[str, Any]] = AWS_CONDITION_KEY_PATTERNS.copy()
+
+    def is_valid_global_key(self, condition_key: str) -> bool:
+        """
+        Check if a condition key is a valid AWS global condition key.
+
+        Args:
+            condition_key: The condition key to validate (e.g., "aws:SourceIp")
+
+        Returns:
+            True if valid global condition key, False otherwise
+        """
+        # Check exact matches first
+        if condition_key in self._global_keys:
+            return True
+
+        # Check patterns (for tags and wildcards)
+        for pattern_config in self._patterns:
+            pattern = pattern_config["pattern"]
+            if re.match(pattern, condition_key):
+                return True
+
+        return False
+
+    def get_key_type(self, condition_key: str) -> str | None:
+        """
+        Get the expected type for a global condition key.
+
+        Args:
+            condition_key: The condition key (e.g., "aws:SourceIp")
+
+        Returns:
+            Type string (String, ARN, Bool, Date, IPAddress, Numeric) or None if not found
+        """
+        # Check exact matches
+        if condition_key in self._global_keys:
+            return self._global_keys[condition_key]
+
+        # Check patterns - all tag-based keys are String type
+        for pattern_config in self._patterns:
+            pattern = pattern_config["pattern"]
+            if re.match(pattern, condition_key):
+                return "String"
+
+        return None
+
+    def get_all_keys(self) -> dict[str, str]:
+        """Get all explicit global condition keys with their types."""
+        return self._global_keys.copy()
+
+    def get_patterns(self) -> list[dict[str, Any]]:
+        """Get all condition key patterns."""
+        return self._patterns.copy()
+
+
+# Singleton instance
+_global_conditions_instance = None
+
+
+def get_global_conditions() -> AWSGlobalConditions:
+    """Get singleton instance of AWSGlobalConditions."""
+    global _global_conditions_instance
+    if _global_conditions_instance is None:
+        _global_conditions_instance = AWSGlobalConditions()
+    return _global_conditions_instance

iam_validator/core/config/category_suggestions.py

@@ -0,0 +1,104 @@
+"""
+Category-specific suggestions for sensitive actions.
+
+This module defines ABAC-focused (Attribute-Based Access Control) suggestions
+and examples for each sensitive action category. These provide actionable
+guidance for securing sensitive AWS actions.
+
+ABAC is the recommended approach as it:
+- Scales across all AWS services
+- Reduces policy maintenance overhead
+- Provides fine-grained access control
+- Enables self-service resource management
+"""
+
+from typing import Any, Final
+
+# ============================================================================
+# ABAC-Focused Category Suggestions
+# ============================================================================
+# Each category provides tailored guidance based on the security risk profile
+# ============================================================================
+
+DEFAULT_CATEGORY_SUGGESTIONS: Final[dict[str, dict[str, Any]]] = {
+    "credential_exposure": {
+        "suggestion": (
+            "This action can expose credentials or secrets. Use ABAC to restrict access:\n"
+            "• Match principal tags to resource tags (aws:PrincipalTag/team = aws:ResourceTag/team)\n"
+            "• Require MFA (aws:MultiFactorAuthPresent = true)\n"
+            "• Restrict to trusted networks (aws:SourceIp)\n"
+            "• Limit to business hours (aws:CurrentTime)"
+        ),
+        "example": (
+            '"Condition": {\n'
+            '  "StringEquals": {\n'
+            '    "aws:PrincipalTag/owner": "${aws:ResourceTag/owner}"\n'
+            "  },\n"
+            '  "Bool": {"aws:MultiFactorAuthPresent": "true"}\n'
+            "}"
+        ),
+    },
+    "data_access": {
+        "suggestion": (
+            "This action retrieves sensitive data. Use ABAC to control data access:\n"
+            "• Match principal tags to resource tags (aws:PrincipalTag/data-access = aws:ResourceTag/data-classification)\n"
+            "• Limit by department/team (aws:PrincipalTag/department = aws:ResourceTag/owner)\n"
+            "• Restrict data exfiltration (aws:SourceIp or aws:SourceVpc)\n"
+            "• Consider data classification levels"
+        ),
+        "example": (
+            '"Condition": {\n'
+            '  "StringEquals": {\n'
+            '    "aws:PrincipalTag/owner": "${aws:ResourceTag/owner}",\n'
+            '    "aws:ResourceTag/data-classification": ["public", "internal"]\n'
+            "  }\n"
+            "}"
+        ),
+    },
+    "priv_esc": {
+        "suggestion": (
+            "This action enables privilege escalation. Use ABAC + strong controls:\n"
+            "• Require specific role tags (aws:PrincipalTag/role = admin)\n"
+            "• Enforce permissions boundary (iam:PermissionsBoundary)\n"
+            "• Require MFA (aws:MultiFactorAuthPresent = true) - CRITICAL\n"
+            "• Limit request tags (aws:RequestTag/environment != production)"
+        ),
+        "example": (
+            '"Condition": {\n'
+            '  "StringEquals": {\n'
+            '    "aws:PrincipalTag/role": "security-admin",\n'
+            '    "iam:PermissionsBoundary": "arn:aws:iam::*:policy/MaxPermissions"\n'
+            "  },\n"
+            '  "Bool": {"aws:MultiFactorAuthPresent": "true"}\n'
+            "}"
+        ),
+    },
+    "resource_exposure": {
+        "suggestion": (
+            "This action modifies resource policies. Use ABAC to prevent unauthorized changes:\n"
+            "• Match principal tags to resource tags (aws:PrincipalTag/team = aws:ResourceTag/managed-by)\n"
+            "• Restrict by environment (aws:ResourceTag/environment = development)\n"
+            "• Prevent external access (aws:PrincipalOrgID)\n"
+            "• Require approval tags (aws:RequestTag/change-approved = true)"
+        ),
+        "example": (
+            '"Condition": {\n'
+            '  "StringEquals": {\n'
+            '    "aws:PrincipalTag/owner": "${aws:ResourceTag/managed-by}",\n'
+            '    "aws:ResourceTag/environment": "${aws:PrincipalTag/environment}",\n'
+            '    "aws:PrincipalOrgID": "o-xxxxxxxxxx"\n'
+            "  }\n"
+            "}"
+        ),
+    },
+}
+
+
+def get_category_suggestions() -> dict[str, dict[str, Any]]:
+    """
+    Get default category suggestions.
+
+    Returns:
+        Dictionary mapping category IDs to suggestion/example dictionaries
+    """
+    return DEFAULT_CATEGORY_SUGGESTIONS.copy()

iam_validator/core/config/condition_requirements.py

@@ -0,0 +1,155 @@
+"""
+Condition requirement configurations for action_condition_enforcement check.
+
+This module defines default condition requirements for sensitive actions,
+making it easy to manage complex condition enforcement rules without
+deeply nested YAML/dict structures.
+
+Configuration Fields Reference:
+- description: Technical description of what the requirement does (shown in output)
+- example: Concrete code example showing proper condition usage
+- condition_key: The IAM condition key to validate
+- expected_value: (Optional) Expected value for the condition key
+- severity: (Optional) Override default severity for this requirement
+
+Field Progression: detect (condition_key) → explain (description) → demonstrate (example)
+
+For detailed explanation of these fields and how to customize requirements,
+see: docs/condition-requirements.md and docs/configuration.md#customizing-messages
+"""
+
+from typing import Any, Final
+
+# ============================================================================
+# Condition Requirement Definitions
+# ============================================================================
+
+# IAM PassRole - CRITICAL: Prevent privilege escalation
+IAM_PASS_ROLE_REQUIREMENT: Final[dict[str, Any]] = {
+    "actions": ["iam:PassRole"],
+    "severity": "high",
+    "required_conditions": [
+        {
+            "condition_key": "iam:PassedToService",
+            "description": (
+                "Restrict which AWS services can assume the passed role to prevent privilege escalation"
+            ),
+            "example": (
+                '"Condition": {\n'
+                '  "StringEquals": {\n'
+                '    "iam:PassedToService": [\n'
+                '      "lambda.amazonaws.com",\n'
+                '      "ecs-tasks.amazonaws.com",\n'
+                '      "ec2.amazonaws.com",\n'
+                '      "glue.amazonaws.com"\n'
+                "    ]\n"
+                "  }\n"
+                "}"
+            ),
+        },
+    ],
+}
+
+# S3 Write Operations - Require organization ID
+S3_WRITE_ORG_ID: Final[dict[str, Any]] = {
+    "actions": ["s3:PutObject"],
+    "severity": "medium",
+    "required_conditions": [
+        {
+            "condition_key": "aws:ResourceOrgId",
+            "description": (
+                "Require aws:ResourceAccount, aws:ResourceOrgID or aws:ResourceOrgPaths condition(s) for S3 write actions to enforce organization-level access control"
+            ),
+            "example": (
+                "{\n"
+                '  "Condition": {\n'
+                '    "StringEquals": {\n'
+                '      "aws:ResourceOrgId": "${aws:PrincipalOrgID}"\n'
+                "    }\n"
+                "  }\n"
+                "}"
+            ),
+        },
+    ],
+}
+
+# IP Restrictions - Source IP requirements
+SOURCE_IP_RESTRICTIONS: Final[dict[str, Any]] = {
+    "action_patterns": [
+        "^ssm:StartSession$",
+        "^ssm:Run.*$",
+        "^s3:GetObject$",
+        "^rds-db:Connect$",
+    ],
+    "severity": "low",
+    "required_conditions": [
+        {
+            "condition_key": "aws:SourceIp",
+            "description": "Restrict access to corporate IP ranges",
+            "example": (
+                "{\n"
+                '  "Condition": {\n'
+                '    "IpAddress": {\n'
+                '      "aws:SourceIp": [\n'
+                '        "10.0.0.0/8",\n'
+                '        "172.16.0.0/12"\n'
+                "      ]\n"
+                "    }\n"
+                "  }\n"
+                "}"
+            ),
+        },
+    ],
+}
+
+# S3 Secure Transport - Never allow insecure transport
+S3_SECURE_TRANSPORT: Final[dict[str, Any]] = {
+    "actions": ["s3:GetObject", "s3:PutObject"],
+    "severity": "critical",
+    "required_conditions": {
+        "none_of": [
+            {
+                "condition_key": "aws:SecureTransport",
+                "expected_value": False,
+                "description": "Never allow insecure transport to be explicitly permitted",
+                "example": (
+                    "# Set this condition to true to enforce secure transport or remove it entirely\n"
+                    "{\n"
+                    '  "Condition": {\n'
+                    '    "Bool": {\n'
+                    '      "aws:SecureTransport": "true"\n'
+                    "    }\n"
+                    "  }\n"
+                    "}"
+                ),
+            },
+        ],
+    },
+}
+
+# Prevent overly permissive IP ranges
+PREVENT_PUBLIC_IP: Final[dict[str, Any]] = {
+    "action_patterns": ["^s3:.*"],
+    "severity": "high",
+    "required_conditions": {
+        "none_of": [
+            {
+                "condition_key": "aws:SourceIp",
+                "expected_value": "0.0.0.0/0",
+                "description": "Do not allow access from any IP address",
+            },
+        ],
+    },
+}
+
+# ============================================================================
+# Condition Requirements
+# ============================================================================
+
+CONDITION_REQUIREMENTS: Final[list[dict[str, Any]]] = [
+    IAM_PASS_ROLE_REQUIREMENT,
+    S3_WRITE_ORG_ID,
+    SOURCE_IP_RESTRICTIONS,
+    S3_SECURE_TRANSPORT,
+    PREVENT_PUBLIC_IP,
+]