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

iam_validator/core/config/principal_requirements.py

@@ -0,0 +1,421 @@
+"""
+Principal condition requirement configurations for principal_validation check.
+
+This module defines default condition requirements for principals in resource-based
+policies, making it easy to manage complex principal condition enforcement rules
+without deeply nested YAML/dict structures.
+
+Using Python provides:
+- Better readability and maintainability
+- Type hints and IDE support
+- Easy to add/modify requirements
+- No parsing overhead
+- Compiled to .pyc
+
+Configuration Fields Reference:
+- principals: List of principal patterns to match (supports wildcards)
+- severity: Override default severity for this requirement
+- required_conditions: Conditions that must be present (supports all_of/any_of/none_of)
+- condition_key: The IAM condition key to validate
+- expected_value: (Optional) Expected value for the condition key
+- operator: (Optional) Specific operator to validate (e.g., "StringEquals", "IpAddress")
+- description: Technical description of what the requirement does
+- example: Concrete code example showing proper condition usage
+
+Field Progression: detect (condition_key) → explain (description) → demonstrate (example)
+
+For detailed explanation of these fields and how to customize requirements,
+see: docs/configuration.md#principal-validation
+"""
+
+from typing import Any, Final
+
+# ============================================================================
+# Principal Condition Requirement Definitions
+# ============================================================================
+
+# Public Access (*) - CRITICAL: Must have source restrictions
+PUBLIC_ACCESS_REQUIREMENT: Final[dict[str, Any]] = {
+    "principals": ["*"],
+    "severity": "critical",
+    "required_conditions": {
+        "any_of": [
+            {
+                "condition_key": "aws:SourceArn",
+                "description": (
+                    "Public access must be scoped to a specific source ARN "
+                    "(e.g., SNS topic, EventBridge rule, CloudFront distribution)"
+                ),
+                "example": (
+                    "# Example: S3 bucket policy allowing access from SNS topic\n"
+                    '"Condition": {\n'
+                    '  "StringEquals": {\n'
+                    '    "aws:SourceArn": "arn:aws:sns:us-east-1:123456789012:my-topic"\n'
+                    "  }\n"
+                    "}"
+                ),
+            },
+            {
+                "condition_key": "aws:SourceAccount",
+                "description": (
+                    "Public access must be limited to a specific AWS account to prevent "
+                    "unauthorized access from other accounts"
+                ),
+                "example": (
+                    '"Condition": {\n'
+                    '  "StringEquals": {\n'
+                    '    "aws:SourceAccount": "123456789012"\n'
+                    "  }\n"
+                    "}"
+                ),
+            },
+            {
+                "condition_key": "aws:SourceVpce",
+                "description": (
+                    "Or limit public access to a specific VPC endpoint for network-level isolation"
+                ),
+                "example": (
+                    '"Condition": {\n'
+                    '  "StringEquals": {\n'
+                    '    "aws:SourceVpce": "vpce-1a2b3c4d"\n'
+                    "  }\n"
+                    "}"
+                ),
+            },
+            {
+                "condition_key": "aws:SourceIp",
+                "description": ("Or limit public access to specific IP addresses or CIDR ranges"),
+                "example": (
+                    '"Condition": {\n'
+                    '  "IpAddress": {\n'
+                    '    "aws:SourceIp": ["10.0.0.0/8", "172.16.0.0/12"]\n'
+                    "  }\n"
+                    "}"
+                ),
+            },
+        ]
+    },
+}
+
+# Cross-Account Root Access - HIGH: Must be from same organization
+CROSS_ACCOUNT_ORG_REQUIREMENT: Final[dict[str, Any]] = {
+    "principals": ["arn:aws:iam::*:root"],
+    "severity": "high",
+    "required_conditions": {
+        "any_of": [
+            {
+                "condition_key": "aws:PrincipalOrgID",
+                "operator": "StringEquals",
+                "description": (
+                    "Cross-account root access must be from principals in the same AWS Organization "
+                    "to prevent unauthorized third-party access"
+                ),
+                "example": (
+                    "# Replace with your organization ID\n"
+                    '"Condition": {\n'
+                    '  "StringEquals": {\n'
+                    '    "aws:PrincipalOrgID": "o-123456789"\n'
+                    "  }\n"
+                    "}"
+                ),
+            },
+            {
+                "condition_key": "aws:PrincipalOrgPaths",
+                "operator": "StringEquals",
+                "description": (
+                    "Cross-account root access must be from principals in the same AWS Organization "
+                    "to prevent unauthorized third-party access"
+                ),
+                "example": (
+                    "# Replace with your organization ID\n"
+                    '"Condition": {\n'
+                    '  "StringEquals": {\n'
+                    '    "aws:PrincipalOrgPaths": "o-123456789/*"\n'
+                    "  }\n"
+                    "}"
+                ),
+            },
+        ],
+    },
+}
+
+# IAM Roles - HIGH: Must have MFA or VPC endpoint
+IAM_ROLE_MFA_OR_VPC: Final[dict[str, Any]] = {
+    "principals": ["arn:aws:iam::*:role/*"],
+    "severity": "high",
+    "required_conditions": {
+        "any_of": [
+            {
+                "condition_key": "aws:MultiFactorAuthPresent",
+                "expected_value": True,
+                "description": "Require MFA authentication for IAM role access",
+                "example": (
+                    '"Condition": {\n  "Bool": {\n    "aws:MultiFactorAuthPresent": "true"\n  }\n}'
+                ),
+            },
+            {
+                "condition_key": "aws:SourceVpce",
+                "description": (
+                    "Or require access from a specific VPC endpoint to ensure network-level isolation"
+                ),
+                "example": (
+                    '"Condition": {\n'
+                    '  "StringEquals": {\n'
+                    '    "aws:SourceVpce": "vpce-12345678"\n'
+                    "  }\n"
+                    "}"
+                ),
+            },
+        ]
+    },
+}
+
+# IAM Users - MEDIUM: Must have MFA and IP restrictions
+IAM_USER_MFA_AND_IP: Final[dict[str, Any]] = {
+    "principals": ["arn:aws:iam::*:user/*"],
+    "severity": "medium",
+    "required_conditions": {
+        "all_of": [
+            {
+                "condition_key": "aws:MultiFactorAuthPresent",
+                "expected_value": True,
+                "severity": "high",  # Override for this specific condition
+                "description": "IAM users must have MFA enabled for security",
+                "example": (
+                    '"Condition": {\n  "Bool": {\n    "aws:MultiFactorAuthPresent": "true"\n  }\n}'
+                ),
+            },
+            {
+                "condition_key": "aws:SourceIp",
+                "operator": "IpAddress",
+                "description": "IAM users must access from approved corporate IP ranges",
+                "example": (
+                    '"Condition": {\n'
+                    '  "IpAddress": {\n'
+                    '    "aws:SourceIp": ["10.0.0.0/8", "172.16.0.0/12"]\n'
+                    "  }\n"
+                    "}"
+                ),
+            },
+        ]
+    },
+}
+
+# Federated Users - HIGH: Tag-based access control (ABAC)
+FEDERATED_USER_ABAC: Final[dict[str, Any]] = {
+    "principals": ["arn:aws:iam::*:federated-user/*"],
+    "severity": "high",
+    "required_conditions": {
+        "all_of": [
+            {
+                "condition_key": "aws:PrincipalTag/Department",
+                "description": "Federated users must have Department tag for access control",
+                "example": (
+                    '"Condition": {\n'
+                    '  "StringEquals": {\n'
+                    '    "aws:PrincipalTag/Department": "Engineering"\n'
+                    "  }\n"
+                    "}"
+                ),
+            },
+            {
+                "condition_key": "aws:RequestTag/Owner",
+                "operator": "StringEquals",
+                "expected_value": "${aws:PrincipalTag/Owner}",
+                "description": (
+                    "Resource owner must match principal's owner tag (Attribute-Based Access Control)"
+                ),
+                "example": (
+                    "# ABAC: Principal tag must match resource tag\n"
+                    '"Condition": {\n'
+                    '  "StringEquals": {\n'
+                    '    "aws:RequestTag/Owner": "${aws:PrincipalTag/Owner}"\n'
+                    "  }\n"
+                    "}"
+                ),
+            },
+        ]
+    },
+}
+
+# Prevent Insecure Transport - CRITICAL: Never allow HTTP
+PREVENT_INSECURE_TRANSPORT: Final[dict[str, Any]] = {
+    "principals": ["*", "arn:aws:iam::*:*"],
+    "severity": "critical",
+    "required_conditions": {
+        "none_of": [
+            {
+                "condition_key": "aws:SecureTransport",
+                "expected_value": False,
+                "description": (
+                    "Insecure transport (HTTP) must never be explicitly allowed. "
+                    "This prevents man-in-the-middle attacks and data interception"
+                ),
+                "example": (
+                    "# INCORRECT - Never allow this:\n"
+                    '"Condition": {\n'
+                    '  "Bool": {\n'
+                    '    "aws:SecureTransport": "false"  # ❌ This is forbidden\n'
+                    "  }\n"
+                    "}\n\n"
+                    "# CORRECT - Require HTTPS:\n"
+                    '"Condition": {\n'
+                    '  "Bool": {\n'
+                    '    "aws:SecureTransport": "true"  # ✅ Always use this\n'
+                    "  }\n"
+                    "}"
+                ),
+            }
+        ]
+    },
+}
+
+# Assumed Role Sessions - MEDIUM: Require session tags
+ASSUMED_ROLE_SESSION_TAGS: Final[dict[str, Any]] = {
+    "principals": ["arn:aws:sts::*:assumed-role/*"],
+    "severity": "medium",
+    "required_conditions": [
+        {
+            "condition_key": "aws:PrincipalTag/SessionName",
+            "description": (
+                "Assumed role sessions should be tagged with session name for audit trails "
+                "and access attribution"
+            ),
+            "example": (
+                '"Condition": {\n  "StringLike": {\n    "aws:PrincipalTag/SessionName": "*"\n  }\n}'
+            ),
+        }
+    ],
+}
+
+# ============================================================================
+# Registry and Helper Functions
+# ============================================================================
+
+# All available requirement definitions
+ALL_PRINCIPAL_REQUIREMENTS: Final[dict[str, dict[str, Any]]] = {
+    "public_access": PUBLIC_ACCESS_REQUIREMENT,
+    "cross_account_org": CROSS_ACCOUNT_ORG_REQUIREMENT,
+    "iam_role_mfa_or_vpc": IAM_ROLE_MFA_OR_VPC,
+    "iam_user_mfa_and_ip": IAM_USER_MFA_AND_IP,
+    "federated_user_abac": FEDERATED_USER_ABAC,
+    "prevent_insecure_transport": PREVENT_INSECURE_TRANSPORT,
+    "assumed_role_session_tags": ASSUMED_ROLE_SESSION_TAGS,
+}
+
+# Default requirements enabled by default (most critical ones)
+DEFAULT_ENABLED_REQUIREMENTS: Final[list[str]] = [
+    "public_access",  # CRITICAL: Public access must have restrictions
+    "prevent_insecure_transport",  # CRITICAL: Never allow insecure transport
+]
+
+
+def get_default_principal_requirements() -> list[dict[str, Any]]:
+    """Get default principal condition requirements (most critical ones enabled by default).
+
+    Returns:
+        List of default principal condition requirements
+    """
+    return [ALL_PRINCIPAL_REQUIREMENTS[name] for name in DEFAULT_ENABLED_REQUIREMENTS]
+
+
+def get_principal_requirement(name: str) -> dict[str, Any] | None:
+    """Get a single principal condition requirement by name.
+
+    Args:
+        name: The requirement name
+
+    Returns:
+        The principal condition requirement or None if not found
+    """
+    return ALL_PRINCIPAL_REQUIREMENTS.get(name)
+
+
+def get_principal_requirements_by_names(names: list[str]) -> list[dict[str, Any]]:
+    """Get multiple principal condition requirements by name.
+
+    Args:
+        names: List of requirement names
+
+    Returns:
+        List of principal condition requirements
+    """
+    return [
+        ALL_PRINCIPAL_REQUIREMENTS[name] for name in names if name in ALL_PRINCIPAL_REQUIREMENTS
+    ]
+
+
+def get_principal_requirements_by_severity(severity: str) -> list[dict[str, Any]]:
+    """Get principal condition requirements filtered by severity.
+
+    Args:
+        severity: The severity level (critical, high, medium, low)
+
+    Returns:
+        List of principal condition requirements with matching severity
+    """
+    return [req for req in ALL_PRINCIPAL_REQUIREMENTS.values() if req.get("severity") == severity]
+
+
+def get_all_principal_requirement_names() -> list[str]:
+    """Get all available principal condition requirement names.
+
+    Returns:
+        List of all requirement names
+    """
+    return list(ALL_PRINCIPAL_REQUIREMENTS.keys())
+
+
+# ============================================================================
+# Usage Examples
+# ============================================================================
+
+"""
+# Example 1: Use default requirements (public_access + prevent_insecure_transport)
+from iam_validator.core.config import get_default_principal_requirements
+
+config = {
+    "principal_validation": {
+        "enabled": True,
+        "principal_condition_requirements": get_default_principal_requirements(),
+    }
+}
+
+# Example 2: Use specific requirements by name
+from iam_validator.core.config import get_principal_requirements_by_names
+
+config = {
+    "principal_validation": {
+        "enabled": True,
+        "principal_condition_requirements": get_principal_requirements_by_names([
+            "public_access",
+            "cross_account_org",
+            "iam_role_mfa_or_vpc",
+        ]),
+    }
+}
+
+# Example 3: Get all critical severity requirements
+from iam_validator.core.config import get_principal_requirements_by_severity
+
+config = {
+    "principal_validation": {
+        "enabled": True,
+        "principal_condition_requirements": get_principal_requirements_by_severity("critical"),
+    }
+}
+
+# Example 4: Get all available requirement names
+from iam_validator.core.config import get_all_principal_requirement_names
+
+print(get_all_principal_requirement_names())
+# Output: ['public_access', 'cross_account_org', 'iam_role_mfa_or_vpc', ...]
+
+# Example 5: Get a single requirement
+from iam_validator.core.config import get_principal_requirement
+
+req = get_principal_requirement("public_access")
+if req:
+    print(req["principals"])  # ["*"]
+    print(req["severity"])    # "critical"
+"""

iam_validator/core/config/sensitive_actions.py

@@ -0,0 +1,133 @@
+"""
+Sensitive actions catalog for IAM Policy Validator.
+
+This module defines a curated list of sensitive AWS actions that should
+typically have IAM conditions to limit when they can be used.
+
+Using Python instead of YAML/JSON provides:
+- Zero parsing overhead (compiled to .pyc)
+- Better PyPI packaging (no data files)
+- Type hints and IDE autocomplete
+- Easy to extend and maintain
+
+The list is a frozenset for O(1) lookup performance.
+"""
+
+from typing import Final
+
+# ============================================================================
+# Sensitive Actions List
+# ============================================================================
+# These actions are considered sensitive and should typically have IAM
+# conditions to limit when they can be used. Examples include:
+# - IAM identity and access management changes
+# - Secrets and credential operations
+# - Destructive operations (deletions)
+# - Security configuration changes
+# - Network and firewall modifications
+# - Logging and audit trail changes
+# ============================================================================
+
+DEFAULT_SENSITIVE_ACTIONS: Final[frozenset[str]] = frozenset(
+    {
+        # IAM & Identity Management
+        "iam:AddClientIDToOpenIDConnectProvider",
+        "iam:AttachRolePolicy",
+        "iam:AttachUserPolicy",
+        "iam:CreateAccessKey",
+        "iam:CreateOpenIDConnectProvider",
+        "iam:CreatePolicyVersion",
+        "iam:CreateRole",
+        "iam:CreateSAMLProvider",
+        "iam:CreateUser",
+        "iam:DeleteAccessKey",
+        "iam:DeleteLoginProfile",
+        "iam:DeleteOpenIDConnectProvider",
+        "iam:DeleteRole",
+        "iam:DeleteRolePolicy",
+        "iam:DeleteSAMLProvider",
+        "iam:DeleteUser",
+        "iam:DeleteUserPolicy",
+        "iam:DetachRolePolicy",
+        "iam:DetachUserPolicy",
+        "iam:PutRolePolicy",
+        "iam:PutUserPolicy",
+        "iam:SetDefaultPolicyVersion",
+        "iam:UpdateAccessKey",
+        "iam:UpdateAssumeRolePolicy",
+        # Secrets & Credentials
+        "kms:DisableKey",
+        "kms:PutKeyPolicy",
+        "kms:ScheduleKeyDeletion",
+        "secretsmanager:DeleteSecret",
+        "secretsmanager:GetSecretValue",
+        "secretsmanager:PutSecretValue",
+        "ssm:DeleteParameter",
+        "ssm:PutParameter",
+        # Compute & Containers
+        "ec2:DeleteSnapshot",
+        "ec2:DeleteVolume",
+        "ec2:DeleteVpc",
+        "ec2:ModifyInstanceAttribute",
+        "ec2:TerminateInstances",
+        "ecr:DeleteRepository",
+        "ecs:DeleteCluster",
+        "ecs:DeleteService",
+        "eks:DeleteCluster",
+        "lambda:DeleteFunction",
+        "lambda:DeleteFunctionConcurrency",
+        "lambda:PutFunctionConcurrency",
+        # Database & Storage
+        "dynamodb:DeleteTable",
+        "efs:DeleteFileSystem",
+        "elasticache:DeleteCacheCluster",
+        "fsx:DeleteFileSystem",
+        "rds:DeleteDBCluster",
+        "rds:DeleteDBInstance",
+        "redshift:DeleteCluster",
+        # S3 & Backup
+        "backup:DeleteBackupVault",
+        "glacier:DeleteArchive",
+        "s3:DeleteBucket",
+        "s3:DeleteBucketPolicy",
+        "s3:DeleteObject",
+        "s3:PutBucketPolicy",
+        "s3:PutLifecycleConfiguration",
+        # Network & Security
+        "ec2:ApplySecurityGroupsToClientVpnTargetNetwork",
+        "ec2:AssociateClientVpnTargetNetwork",
+        "ec2:AssociateSecurityGroupVpc",
+        "ec2:AttachVpnGateway",
+        "ec2:AuthorizeClientVpnIngress",
+        "ec2:AuthorizeSecurityGroupIngress",
+        "ec2:CreateClientVpnRoute",
+        "ec2:CreateVpnConnection",
+        "ec2:DeleteSecurityGroup",
+        "ec2:DeleteVpnConnection",
+        "ec2:DisassociateRouteTable",
+        "ec2:RevokeSecurityGroupEgress",
+        # Access & Logging
+        "cloudtrail:DeleteTrail",
+        "cloudtrail:StopLogging",
+        "cloudwatch:DeleteLogGroup",
+        "config:DeleteConfigurationRecorder",
+        "guardduty:DeleteDetector",
+        # Account & Organization
+        "account:CloseAccount",
+        "account:CreateAccount",
+        "account:DeleteAccount",
+        "organizations:DeleteOrganization",
+        "organizations:LeaveOrganization",
+        "organizations:RemoveAccountFromOrganization",
+    }
+)
+
+
+def get_sensitive_actions() -> frozenset[str]:
+    """
+    Get all sensitive actions.
+
+    Returns:
+        Frozenset of all sensitive actions for O(1) membership testing
+    """
+    return DEFAULT_SENSITIVE_ACTIONS

iam_validator/core/config/service_principals.py

@@ -0,0 +1,95 @@
+"""
+Default service principals for resource policy validation.
+
+These are AWS service principals that are commonly used and considered safe
+in resource-based policies (S3 bucket policies, SNS topic policies, etc.).
+"""
+
+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 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",),
+    }