iam-policy-validator 1.10.2__py3-none-any.whl → 1.11.0__py3-none-any.whl

iam_validator/core/config/condition_requirements.py

@@ -28,6 +28,13 @@ from typing import Any, Final
 IAM_PASS_ROLE_REQUIREMENT: Final[dict[str, Any]] = {
     "actions": ["iam:PassRole"],
     "severity": "high",
+    "suggestion_text": (
+        "This action allows passing IAM roles to AWS services, which can lead to privilege escalation. "
+        "Always restrict which services can receive roles:\n"
+        "• Use `iam:PassedToService` to limit specific AWS services (e.g., lambda.amazonaws.com, ecs-tasks.amazonaws.com)\n"
+        "• Consider adding `iam:AssociatedResourceArn` to restrict which resources can use the role\n"
+        "• Require MFA for sensitive role passing (`aws:MultiFactorAuthPresent` = `true`)"
+    ),
     "required_conditions": [
         {
             "condition_key": "iam:PassedToService",
@@ -50,66 +57,96 @@ IAM_PASS_ROLE_REQUIREMENT: Final[dict[str, Any]] = {
     ],
 }
 
-# S3 Write Operations - Require organization ID
-S3_WRITE_ORG_ID: Final[dict[str, Any]] = {
-    "actions": ["s3:PutObject"],
+# S3 Organization Boundary - Prevent data exfiltration for both reads and writes
+# Enforces that S3 operations only access resources within organizational boundaries
+S3_ORG_BOUNDARY: Final[dict[str, Any]] = {
+    "actions": ["s3:GetObject", "s3:GetObjectVersion", "s3:PutObject"],
     "severity": "medium",
+    "suggestion_text": (
+        "These S3 actions can read or write data. Prevent data exfiltration by ensuring operations only access organization-owned buckets:\n"
+        "• Use organization ID (`aws:ResourceOrgID` = `${aws:PrincipalOrgID}`)\n"
+        "• OR use organization paths (`aws:ResourceOrgPaths` = `${aws:PrincipalOrgPaths}`)\n"
+        "• OR restrict by network boundary (IP/VPC/VPCe) + same account (`aws:ResourceAccount` = `${aws:PrincipalAccount}`)"
+    ),
     "required_conditions": {
         "any_of": [
-            # Option 1: Use organization-level control with ResourceOrgID
+            # Option 1: Restrict to organization resources (strongest)
             {
-                "all_of": [
-                    {
-                        "condition_key": "aws:ResourceOrgID",
-                        "description": "Restrict S3 write actions to resources within your AWS Organization",
-                        "expected_value": "${aws:PrincipalOrgID}",
-                        "example": (
-                            "{\n"
-                            '  "Condition": {\n'
-                            '    "StringEquals": {\n'
-                            '      "aws:ResourceOrgID": "${aws:PrincipalOrgID}",\n'
-                            '      "aws:ResourceAccount": "${aws:PrincipalAccount}"\n'
-                            "    }\n"
-                            "  }\n"
-                            "}"
-                        ),
-                    },
-                    {
-                        "condition_key": "aws:ResourceAccount",
-                        "description": "Ensure the S3 resource belongs to the same AWS account as the principal",
-                        "expected_value": "${aws:PrincipalAccount}",
-                    },
-                ]
+                "condition_key": "aws:ResourceOrgID",
+                "description": "Restrict S3 operations to resources within your AWS Organization",
+                "expected_value": "${aws:PrincipalOrgID}",
+                "example": (
+                    "{\n"
+                    '  "Condition": {\n'
+                    '    "StringEquals": {\n'
+                    '      "aws:ResourceOrgID": "${aws:PrincipalOrgID}"\n'
+                    "    }\n"
+                    "  }\n"
+                    "}"
+                ),
+            },
+            # Option 2: Restrict to organization paths
+            {
+                "condition_key": "aws:ResourceOrgPaths",
+                "description": "Restrict S3 operations to resources within your AWS Organization path",
+                "expected_value": "${aws:PrincipalOrgPaths}",
+                "example": (
+                    "{\n"
+                    '  "Condition": {\n'
+                    '    "StringEquals": {\n'
+                    '      "aws:ResourceOrgPaths": "${aws:PrincipalOrgPaths}"\n'
+                    "    }\n"
+                    "  }\n"
+                    "}"
+                ),
             },
-            # Option 2: Use organization path-based control
+            # Option 3: Network boundary - Source IP + same account
             {
-                "all_of": [
-                    {
-                        "condition_key": "aws:ResourceOrgPaths",
-                        "description": "Restrict S3 write actions to resources within your AWS Organization path",
-                        "expected_value": "${aws:PrincipalOrgPaths}",
-                        "example": (
-                            "{\n"
-                            '  "Condition": {\n'
-                            '    "StringEquals": {\n'
-                            '      "aws:ResourceOrgPaths": "${aws:PrincipalOrgPaths}",\n'
-                            '      "aws:ResourceAccount": "${aws:PrincipalAccount}"\n'
-                            "    }\n"
-                            "  }\n"
-                            "}"
-                        ),
-                    },
-                    {
-                        "condition_key": "aws:ResourceAccount",
-                        "description": "Ensure the S3 resource belongs to the same AWS account as the principal",
-                        "expected_value": "${aws:PrincipalAccount}",
-                    },
-                ]
+                "condition_key": "aws:SourceIp",
+                "description": "Restrict S3 operations by source IP address and same account",
+                "example": (
+                    "{\n"
+                    '  "Condition": {\n'
+                    '    "IpAddress": {"aws:SourceIp": "10.0.0.0/8"},\n'
+                    '    "StringEquals": {"aws:ResourceAccount": "${aws:PrincipalAccount}"}\n'
+                    "  }\n"
+                    "}"
+                ),
+            },
+            # Option 4: Network boundary - Source VPC + same account
+            {
+                "condition_key": "aws:SourceVpc",
+                "description": "Restrict S3 operations by source VPC and same account",
+                "example": (
+                    "{\n"
+                    '  "Condition": {\n'
+                    '    "StringEquals": {\n'
+                    '      "aws:SourceVpc": "vpc-12345678",\n'
+                    '      "aws:ResourceAccount": "${aws:PrincipalAccount}"\n'
+                    "    }\n"
+                    "  }\n"
+                    "}"
+                ),
+            },
+            # Option 5: Network boundary - VPC Endpoint + same account
+            {
+                "condition_key": "aws:SourceVpce",
+                "description": "Restrict S3 operations by VPC endpoint and same account",
+                "example": (
+                    "{\n"
+                    '  "Condition": {\n'
+                    '    "StringEquals": {\n'
+                    '      "aws:SourceVpce": "vpce-12345678",\n'
+                    '      "aws:ResourceAccount": "${aws:PrincipalAccount}"\n'
+                    "    }\n"
+                    "  }\n"
+                    "}"
+                ),
             },
-            # Option 3: Account-only control (less restrictive, but still secure)
+            # Option 6: Minimum - at least require same account
             {
                 "condition_key": "aws:ResourceAccount",
-                "description": "Restrict S3 write actions to resources within the same AWS account",
+                "description": "Restrict S3 operations to resources within the same AWS account",
                 "expected_value": "${aws:PrincipalAccount}",
                 "example": (
                     "{\n"
@@ -130,10 +167,16 @@ SOURCE_IP_RESTRICTIONS: Final[dict[str, Any]] = {
     "action_patterns": [
         "^ssm:StartSession$",
         "^ssm:Run.*$",
-        "^s3:GetObject$",
         "^rds-db:Connect$",
     ],
     "severity": "low",
+    "suggestion_text": (
+        "This action accesses sensitive resources or data. Restrict network access to trusted locations:\n"
+        "• Use `aws:SourceIp` to limit to corporate IP ranges (e.g., office networks, VPN endpoints)\n"
+        "• Alternative: Use `aws:SourceVpc` or `aws:SourceVpce` for VPC-based restrictions\n"
+        "• Consider combining with secure transport requirements\n"
+        "• For S3: Ensure account ownership (`aws:ResourceAccount` = `${aws:PrincipalAccount}`)"
+    ),
     "required_conditions": [
         {
             "condition_key": "aws:SourceIp",
@@ -146,7 +189,9 @@ SOURCE_IP_RESTRICTIONS: Final[dict[str, Any]] = {
                 '        "10.0.0.0/8",\n'
                 '        "172.16.0.0/12"\n'
                 "      ]\n"
-                "    }\n"
+                "    },\n"
+                '    "Bool": {"aws:SecureTransport": "true"},\n'
+                '    "StringEquals": {"aws:ResourceAccount": "${aws:PrincipalAccount}"}\n'
                 "  }\n"
                 "}"
             ),
@@ -158,6 +203,12 @@ SOURCE_IP_RESTRICTIONS: Final[dict[str, Any]] = {
 S3_SECURE_TRANSPORT: Final[dict[str, Any]] = {
     "actions": ["s3:GetObject", "s3:PutObject"],
     "severity": "critical",
+    "suggestion_text": (
+        "CRITICAL: This S3 action must enforce encrypted connections. Unencrypted HTTP connections expose data in transit:\n"
+        "• Set `aws:SecureTransport` to `true` to enforce HTTPS/TLS\n"
+        "• NEVER set `aws:SecureTransport` to `false` (this explicitly allows unencrypted connections)\n"
+        "• Combine with other controls (IP restrictions, account boundaries) for defense in depth"
+    ),
     "required_conditions": {
         "none_of": [
             {
@@ -200,7 +251,7 @@ PREVENT_PUBLIC_IP: Final[dict[str, Any]] = {
 
 CONDITION_REQUIREMENTS: Final[list[dict[str, Any]]] = [
     IAM_PASS_ROLE_REQUIREMENT,
-    S3_WRITE_ORG_ID,
+    S3_ORG_BOUNDARY,  # Unified S3 read/write organization boundary enforcement
     SOURCE_IP_RESTRICTIONS,
     S3_SECURE_TRANSPORT,
     PREVENT_PUBLIC_IP,

iam_validator/core/config/defaults.py

@@ -344,13 +344,41 @@ DEFAULT_CONFIG = {
     # Check for wildcard resources (Resource: "*")
     # Flags statements that apply to all resources
     # Exception: Allowed if ALL actions are in allowed_wildcards list
+    #
+    # DUAL MATCHING STRATEGY:
+    # The check uses two complementary matching strategies for maximum flexibility:
+    #
+    # 1. LITERAL MATCH (Fast Path - no AWS API calls):
+    #    Policy actions match config patterns exactly as strings
+    #    Example: Policy "iam:Get*" matches config "iam:Get*" → PASS
+    #
+    # 2. EXPANDED MATCH (Comprehensive Path - uses AWS API):
+    #    Both policy actions and config patterns expand to actual AWS actions
+    #    Example: Policy "iam:GetUser" matches config "iam:Get*" (expanded) → PASS
+    #
+    # SUPPORTED SCENARIOS:
+    #   Policy Action         Config Pattern        Match Type   Result
+    #   iam:Get*              iam:Get*              Literal      ✅ Pass
+    #   iam:GetUser           iam:Get*              Expanded     ✅ Pass
+    #   iam:Get*, iam:List*   iam:Get*, iam:List*   Literal      ✅ Pass
+    #   iam:Get*, iam:GetUser iam:Get*              Literal      ✅ Pass
+    #   iam:Delete*           iam:Get*              None         ❌ Fail
+    #
+    # PERFORMANCE TIP: Literal matching is faster (no AWS API expansion)
     "wildcard_resource": {
         "enabled": True,
         "severity": "medium",  # Security issue
         "description": "Checks for wildcard resources (*)",
         # Allowed wildcard patterns for actions that can be used with Resource: "*"
+        # Supports BOTH literal matching and pattern expansion via AWS API
+        #
         # Default: 25 read-only patterns (Describe*, List*, Get*)
         # See: iam_validator/core/config/wildcards.py
+        #
+        # Examples:
+        #   ["ec2:Describe*"]  # Matches: ec2:Describe* (literal) OR ec2:DescribeInstances (expanded)
+        #   ["iam:GetUser"]    # Matches: iam:GetUser only
+        #   ["s3:List*"]       # Matches: s3:List* (literal) OR s3:ListBucket (expanded)
         "allowed_wildcards": list(DEFAULT_ALLOWED_WILDCARDS),
         "message": "Statement applies to all resources (*)",
         "suggestion": "Replace wildcard with specific resource ARNs",
@@ -493,6 +521,82 @@ DEFAULT_CONFIG = {
         "ignore_patterns": [
             {"action_matches": "^iam:PassRole$"},
         ],
+        # Cross-statement privilege escalation patterns (policy-wide detection)
+        # These patterns detect dangerous action combinations across ANY statements in the policy
+        # Uses all_of logic: ALL actions must exist somewhere in the policy
+        "sensitive_actions": [
+            # User privilege escalation: Create user + attach admin policy
+            {
+                "all_of": ["iam:CreateUser", "iam:AttachUserPolicy"],
+                "severity": "critical",
+                "message": "Policy grants {actions} across statements - enables privilege escalation. {statements}",
+                "suggestion": (
+                    "This combination allows an attacker to:\n"
+                    "1. Create a new IAM user\n"
+                    "2. Attach AdministratorAccess policy to that user\n"
+                    "3. Escalate to full account access\n\n"
+                    "Mitigation options:\n"
+                    "• Remove both of these permissions\n"
+                    "• Add strict IAM conditions (MFA, IP restrictions, force a specific policy with `iam:PolicyARN` condition)\n"
+                ),
+            },
+            # Role privilege escalation: Create role + attach admin policy
+            {
+                "all_of": ["iam:CreateRole", "iam:AttachRolePolicy"],
+                "severity": "high",
+                "message": "Policy grants {actions} across statements - enables privilege escalation. {statements}",
+                "suggestion": (
+                    "This combination allows creating privileged roles with admin policies.\n\n"
+                    "Mitigation options:\n"
+                    "• Remove both of these permissions\n"
+                    "• Add strict IAM conditions with a Permissions Boundary and ABAC Tagging, force a specific policy with `iam:PolicyARN` condition\n"
+                ),
+            },
+            # Lambda backdoor: Create/update function + invoke
+            {
+                "all_of": ["lambda:CreateFunction", "lambda:InvokeFunction"],
+                "severity": "medium",
+                "message": "Policy grants {actions} across statements - enables code execution. {statements}",
+                "suggestion": (
+                    "This combination allows an attacker to:\n"
+                    "1. Create a Lambda function with malicious code\n"
+                    "2. Execute the function to perform operations with the Lambda's role\n\n"
+                    "Mitigation options:\n"
+                    "• Restrict Lambda creation to specific function names/paths\n"
+                    "• Require resource tags on functions and tag-based invocation controls\n"
+                    "• Require MFA for Lambda function creation\n"
+                    "• Use separate policies for creation vs invocation"
+                ),
+            },
+            # Lambda code modification backdoor
+            {
+                "all_of": ["lambda:UpdateFunctionCode", "lambda:InvokeFunction"],
+                "severity": "medium",
+                "message": "Policy grants {actions} across statements - enables code injection. {statements}",
+                "suggestion": (
+                    "This combination allows modifying existing Lambda functions and executing them.\n\n"
+                    "Mitigation options:\n"
+                    "• Use resource-based policies to restrict which functions can be modified\n"
+                    "• Require MFA for code updates\n"
+                    "• Use separate policies for code updates vs invocation\n"
+                    "• Implement code signing for Lambda functions"
+                ),
+            },
+            # EC2 instance privilege escalation
+            {
+                "all_of": ["ec2:RunInstances", "iam:PassRole"],
+                "severity": "high",
+                "message": "Policy grants {actions} across statements - enables privilege escalation via instance profile. {statements}",
+                "suggestion": (
+                    "This combination allows launching EC2 instances with privileged roles.\n\n"
+                    "Mitigation options:\n"
+                    "• Add iam:PassedToService condition requiring ec2.amazonaws.com\n"
+                    "• Restrict instance creation to specific AMIs or instance types\n"
+                    "• Limit PassRole to specific low-privilege roles\n"
+                    "• Require tagging and ABAC controls"
+                ),
+            },
+        ],
     },
     # ========================================================================
     # 18. ACTION CONDITION ENFORCEMENT
@@ -505,7 +609,7 @@ DEFAULT_CONFIG = {
     # Available requirements:
     #   Default (enabled):
     #     - iam_pass_role: Requires iam:PassedToService
-    #     - s3_org_id: Requires organization ID for S3 writes
+    #     - s3_org_boundary: Prevents S3 data exfiltration (reads + writes)
     #     - source_ip_restrictions: Restricts to corporate IPs
     #     - s3_secure_transport: Prevents insecure transport
     #     - prevent_public_ip: Prevents 0.0.0.0/0 IP ranges
@@ -515,10 +619,10 @@ DEFAULT_CONFIG = {
         "enabled": True,
         "severity": "high",  # Default severity (can be overridden per-requirement)
         "description": "Enforces conditions (MFA, IP, tags, etc.) for specific actions at both statement and policy level",
-        # STATEMENT-LEVEL: Load 5 requirements from Python module
-        # Deep copy to prevent mutation of the originals
-        # These check individual statements independently
-        "action_condition_requirements": __import__("copy").deepcopy(CONDITION_REQUIREMENTS),
+        # CRITICAL: This key is used by sensitive_action check for filtering
+        # It must be named "requirements" (not "action_condition_requirements")
+        # to enable automatic deduplication of warnings
+        "requirements": __import__("copy").deepcopy(CONDITION_REQUIREMENTS),
         # POLICY-LEVEL: Scan entire policy and enforce conditions across ALL matching statements
         # Example: "If ANY statement grants iam:CreateUser, then ALL such statements must have MFA"
         # Default: Empty list (opt-in feature)
@@ -543,6 +647,6 @@ def get_default_config() -> dict:
     Returns:
         A deep copy of the default configuration dictionary
     """
-    import copy
+    import copy  # pylint: disable=import-outside-toplevel
 
     return copy.deepcopy(DEFAULT_CONFIG)

iam_validator/core/config/wildcards.py

@@ -28,8 +28,11 @@ DEFAULT_ALLOWED_WILDCARDS: Final[tuple[str, ...]] = (
     "cloudwatch:List*",
     # DynamoDB
     "dynamodb:Describe*",
+    "dynamodb:Get*",
+    "dynamodb:List*",
     # EC2
     "ec2:Describe*",
+    "ec2:List*",
     # Elastic Load Balancing
     "elasticloadbalancing:Describe*",
     # IAM (non-sensitive read operations)