iam-policy-validator 1.12.0__py3-none-any.whl → 1.13.0__py3-none-any.whl

{iam_policy_validator-1.12.0.dist-info → iam_policy_validator-1.13.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iam-policy-validator
-Version: 1.12.0
+Version: 1.13.0
 Summary: Validate AWS IAM policies for correctness and security using AWS Service Reference API
 Project-URL: Homepage, https://github.com/boogy/iam-policy-validator
 Project-URL: Documentation, https://github.com/boogy/iam-policy-validator/tree/main/docs

{iam_policy_validator-1.12.0.dist-info → iam_policy_validator-1.13.0.dist-info}/RECORD

@@ -1,8 +1,8 @@
 iam_validator/__init__.py,sha256=xHdUASOxFHwEXfT_GSr_KrkLlnxZ-pAAr1wW1PwAGko,693
 iam_validator/__main__.py,sha256=to_nz3n_IerJpVVZZ6WSFlFR5s_06J0csfPOTfQZG8g,197
-iam_validator/__version__.py,sha256=W6lxpjiojokhUhDmTpeymt8Z-W7jmcwUbVTvLyrpAko,374
+iam_validator/__version__.py,sha256=Gh6xEIE-FdIaY_5D-vLQn-lzIOGKaeGM8vbVmUci1V4,374
 iam_validator/checks/__init__.py,sha256=OTkPnmlelu4YjMO8krjhu2wXiTV72RzopA5u1SfPQA0,1990
-iam_validator/checks/action_condition_enforcement.py,sha256=oj3hsh3LwPneYAsQ6iBd61ToIJMr6aDIixKP-zkaqKI,55053
+iam_validator/checks/action_condition_enforcement.py,sha256=aXCB9hZ7OxucUyJjgW6Y6X1dWPeUAFJIBjz6G_lTWsI,60380
 iam_validator/checks/action_resource_matching.py,sha256=WiGJmCIJfx5yituMjZxpKmk-99N6nK20ueN02ddy9oM,19296
 iam_validator/checks/action_validation.py,sha256=QXfNamcstQIO41zNed1-bCmXYkXdV77owu8G2cZ09-A,2517
 iam_validator/checks/condition_key_validation.py,sha256=QJjG82wxvjdG2m-YuEzAjKRRiWaaPkf_LChdUTvm9g4,3919
@@ -14,7 +14,7 @@ iam_validator/checks/policy_structure.py,sha256=9eR8EEcERKcc5n7D3_LmFIQyDNzVV5Me
 iam_validator/checks/policy_type_validation.py,sha256=z4RiAvmPhtrf6Gj3z1Ln4dDFWnFclsokVL7x-YhkMiM,15986
 iam_validator/checks/principal_validation.py,sha256=jusBVEA-sHHft3Kfq_YdvPUgX3cBnxKqC1zhth74kCU,27691
 iam_validator/checks/resource_validation.py,sha256=G_Pfh3WZ6-C3KTk3XPpUKhOESwIO5ISgbsUXc-aK1SE,5988
-iam_validator/checks/sensitive_action.py,sha256=ckyb2n47hKuyr1smC4_Q0dkcdngfhaMueyesQcNE_6k,14912
+iam_validator/checks/sensitive_action.py,sha256=vLGgFMDpW_CmKnKiQcR5pyAZRaDQtqeAAgS3D4CSPDU,18911
 iam_validator/checks/service_wildcard.py,sha256=ycggiozWm1Z4lkWsDlooMEvRJflzLxZkihQDPZ9G_zw,3949
 iam_validator/checks/set_operator_validation.py,sha256=FyxZ7qWlp9-ABzZaRRkxRP_Hws7Re7qZgeQCCM9sJAM,7258
 iam_validator/checks/sid_uniqueness.py,sha256=vfpk88b9G9OApxtrotABI2mPXvGd_C_X4gJKeqIURlk,5968
@@ -22,7 +22,7 @@ iam_validator/checks/trust_policy_validation.py,sha256=a8Sm2xu3gFOHLd7rXDl-ibqiL
 iam_validator/checks/wildcard_action.py,sha256=CyURgURDt2fQT2468LK813RupQ3WWvpmvLVLjUZf9QQ,1960
 iam_validator/checks/wildcard_resource.py,sha256=lRNZN7f3ZQrvnbGdVDCefUQF8lESIMoXVfhIgpln3mM,6679
 iam_validator/checks/utils/__init__.py,sha256=j0X4ibUB6RGx2a-kNoJnlVZwHfoEvzZsIeTmJIAoFzA,45
-iam_validator/checks/utils/policy_level_checks.py,sha256=hZjexXgxuELf-wrO-JwVK8VzP8oRHK3sk0PyaG7QVfI,7070
+iam_validator/checks/utils/policy_level_checks.py,sha256=pr-uLo-otB612YLZ-rd8W5Kl9ENaTHuzTNOUhQaULKc,7593
 iam_validator/checks/utils/sensitive_action_matcher.py,sha256=qDXcJa_2sCJu9pBbjDlI7x5lPtLRc6jQCpKPMheCOJQ,11215
 iam_validator/checks/utils/wildcard_expansion.py,sha256=3W13hlyWcP2wJ6w-BwM887VOnRzglK6Bk3eHMjUtOco,3131
 iam_validator/commands/__init__.py,sha256=RBEz-Kgt3aRVn_9B1HRy_XgQMIKzlSSQs4Gtg2jQEv8,729
@@ -49,7 +49,7 @@ iam_validator/core/models.py,sha256=FhQ7fpX6T9AOvHsAPlBZL0NmPuPE_xghD3dp4cAGLZw,
 iam_validator/core/policy_checks.py,sha256=FNVuS2GTffwCjjrlupVIazC172gSxKYAAT_ObV6Apbo,8803
 iam_validator/core/policy_loader.py,sha256=2KJnXzGg3g9pDXWZHk3DO0xpZnZZ-wXWFEOdQ_naJ8s,17862
 iam_validator/core/pr_commenter.py,sha256=vDN9meq861nVpno-GyhGX4wnBE1Z7clCIhv6pq9rZGs,22755
-iam_validator/core/report.py,sha256=BkhBFZHBKuF5WiUqXuNgEpFxcDCnbVRjzIy9qfezxdk,36071
+iam_validator/core/report.py,sha256=mi4zjlWHRakO2cTek5NCpiP92kUfJe_j5tAhB5yS02Q,36528
 iam_validator/core/aws_service/__init__.py,sha256=UqMh4HUdGlx2QF5OoueJJ2UlCnhX4QW_x3KeE_bxRQc,735
 iam_validator/core/aws_service/cache.py,sha256=DPuOOPPJC867KAYgV1e0RyQs_k3mtefMdYli3jPaN64,3589
 iam_validator/core/aws_service/client.py,sha256=Zv7rIpEFdUCDXKGp3migPDkj8L5eZltgrGe64M2t2Ko,7336
@@ -64,7 +64,7 @@ iam_validator/core/config/aws_global_conditions.py,sha256=gdmMxXGBy95B3uYUG-J7rn
 iam_validator/core/config/category_suggestions.py,sha256=fopaZ9kXDrsLgi_r0pERrLwgdPPJl5VIiKvXtQK9tj0,8583
 iam_validator/core/config/condition_requirements.py,sha256=1CeQJfWV-Y2ImW0Mq9YdrgvH-hj9IXe0gVOm3B36Rc8,10655
 iam_validator/core/config/config_loader.py,sha256=qKD8aR8YAswaFf68pnYJLFNwKznvcc6lNxSQWU3i6SY,17713
-iam_validator/core/config/defaults.py,sha256=HYCuVXVRMT-0E8R6g609STFBU_IeMG0fFMHUYXsArAU,34685
+iam_validator/core/config/defaults.py,sha256=AdbqyUlsw4YViOWXFBENN3scoVx98hF6_dUKmfyZHNU,37057
 iam_validator/core/config/principal_requirements.py,sha256=VCX7fBDgeDTJQyoz7_x7GI7Kf9O1Eu-sbihoHOrKv6o,15105
 iam_validator/core/config/sensitive_actions.py,sha256=uATDIp_TD3OQQlsYTZp79qd1mSK2Bf9hJ0JwcqLBr84,25344
 iam_validator/core/config/service_principals.py,sha256=8pys5H_yycVJ9KTyimAKFYBg83Aol2Iri53wiHjtnEM,3959
@@ -93,8 +93,8 @@ iam_validator/utils/__init__.py,sha256=NveA2F3G1E6-ANZzFr7J6Q6u5mogvMp862iFokmYu
 iam_validator/utils/cache.py,sha256=wOQKOBeoG6QqC5f0oXcHz63Cjtu_-SsSS-0pTSwyAiM,3254
 iam_validator/utils/regex.py,sha256=xHoMECttb7qaMhts-c9b0GIxdhHNZTt-UBr7wNhWfzg,6219
 iam_validator/utils/terminal.py,sha256=FsRaRMH_JAyDgXWBCOgOEhbS89cs17HCmKYoughq5io,724
-iam_policy_validator-1.12.0.dist-info/METADATA,sha256=oRx7SWFfzvm7WejCfUXLfGDYYAe-lnIBf74cfwigqT8,34456
-iam_policy_validator-1.12.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-iam_policy_validator-1.12.0.dist-info/entry_points.txt,sha256=8HtWd8O7mvPiPdZR5YbzY8or_qcqLM4-pKaFdhtFT8M,62
-iam_policy_validator-1.12.0.dist-info/licenses/LICENSE,sha256=AMnbFTBDcK4_MITe2wiQBkj0vg-jjBBhsc43ydC7tt4,1098
-iam_policy_validator-1.12.0.dist-info/RECORD,,
+iam_policy_validator-1.13.0.dist-info/METADATA,sha256=DHdEaa1wjR4XRrkk0F_oTFI1v9AbeeQsheg2QS3ojKw,34456
+iam_policy_validator-1.13.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+iam_policy_validator-1.13.0.dist-info/entry_points.txt,sha256=8HtWd8O7mvPiPdZR5YbzY8or_qcqLM4-pKaFdhtFT8M,62
+iam_policy_validator-1.13.0.dist-info/licenses/LICENSE,sha256=AMnbFTBDcK4_MITe2wiQBkj0vg-jjBBhsc43ydC7tt4,1098
+iam_policy_validator-1.13.0.dist-info/RECORD,,

{iam_policy_validator-1.12.0.dist-info → iam_policy_validator-1.13.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

iam_validator/__version__.py

@@ -3,7 +3,7 @@
 This file is the single source of truth for the package version.
 """
 
-__version__ = "1.12.0"
+__version__ = "1.13.0"
 # Parse version, handling pre-release suffixes like -rc, -alpha, -beta
 _version_base = __version__.split("-", maxsplit=1)[0]  # Remove pre-release suffix if present
 __version_info__ = tuple(int(part) for part in _version_base.split("."))

iam_validator/checks/action_condition_enforcement.py

@@ -1,146 +1,21 @@
-"""
-Action-Specific Condition Enforcement Check
-
-This check ensures that specific actions have required conditions.
-Supports ALL types of conditions: MFA, IP, VPC, time, tags, encryption, etc.
-
-The entire policy is scanned once, checking all statements for matching actions.
-
-ACTION MATCHING MODES:
-- Simple list: Checks each statement for any of the specified actions
-  Example: actions: ["iam:PassRole", "iam:CreateUser"]
-
-- any_of: Finds statements that contain ANY of the specified actions
-  Example: actions: {any_of: ["iam:CreateUser", "iam:AttachUserPolicy"]}
-
-- all_of: Finds statements that contain ALL specified actions (overly permissive detection)
-  Example: actions: {all_of: ["iam:CreateAccessKey", "iam:UpdateAccessKey"]}
-
-- none_of: Flags statements that contain forbidden actions
-  Example: actions: {none_of: ["iam:DeleteUser", "s3:DeleteBucket"]}
-
-Common use cases:
-- iam:PassRole must have iam:PassedToService condition
-- Sensitive actions must have MFA conditions
-- Actions must have source IP restrictions
-- Resources must have required tags
-- Combine multiple conditions (MFA + IP + Tags)
-- Detect overly permissive statements (all_of)
-- Ensure privilege escalation combinations are protected
-
-Configuration in iam-validator.yaml:
-
-    checks:
-      action_condition_enforcement:
-        enabled: true
-        severity: high
-        description: "Enforce specific conditions for specific actions"
-
-        action_condition_requirements:
-          # BASIC: Simple action with required condition
-          - actions:
-              - "iam:PassRole"
-            required_conditions:
-              - condition_key: "iam:PassedToService"
-                description: "Specify which AWS services can use the passed role"
-
-          # MFA + IP restrictions
-          - actions:
-              - "iam:DeleteUser"
-            required_conditions:
-              all_of:
-                - condition_key: "aws:MultiFactorAuthPresent"
-                  expected_value: true
-                - condition_key: "aws:SourceIp"
-
-          # EC2 with TAGS + MFA + Region
-          - actions:
-              - "ec2:RunInstances"
-            required_conditions:
-              all_of:
-                - condition_key: "aws:MultiFactorAuthPresent"
-                  expected_value: true
-                - condition_key: "aws:RequestTag/Environment"
-                  operator: "StringEquals"
-                  expected_value: ["Production", "Staging", "Development"]
-                - condition_key: "aws:RequestTag/Owner"
-                - condition_key: "aws:RequestedRegion"
-                  expected_value: ["us-east-1", "us-west-2"]
-
-          # Principal-to-resource tag matching
-          - actions:
-              - "ec2:RunInstances"
-            required_conditions:
-              - condition_key: "aws:ResourceTag/owner"
-                operator: "StringEquals"
-                expected_value: "${aws:PrincipalTag/owner}"
-                description: "Resource owner must match principal's owner tag"
-
-          # Complex: all_of + any_of for actions and conditions
-          - actions:
-              any_of:
-                - "cloudformation:CreateStack"
-                - "cloudformation:UpdateStack"
-            required_conditions:
-              all_of:
-                - condition_key: "aws:MultiFactorAuthPresent"
-                  expected_value: true
-                - condition_key: "aws:RequestTag/Environment"
-              any_of:
-                - condition_key: "aws:SourceIp"
-                - condition_key: "aws:SourceVpce"
-
-          # none_of for conditions: Ensure certain conditions are NOT present
-          - actions:
-              - "s3:GetObject"
-            required_conditions:
-              none_of:
-                - condition_key: "aws:SecureTransport"
-                  expected_value: false
-                  description: "Ensure insecure transport is never allowed"
-
-          # any_of for actions: If ANY statement grants privilege escalation actions, require MFA
-          - actions:
-              any_of:
-                - "iam:CreateUser"
-                - "iam:AttachUserPolicy"
-                - "iam:PutUserPolicy"
-            required_conditions:
-              - condition_key: "aws:MultiFactorAuthPresent"
-                expected_value: true
-            description: "Privilege escalation actions require MFA"
-            severity: "critical"
-
-          # all_of for actions: Flag statements that contain BOTH dangerous actions (overly permissive)
-          - actions:
-              all_of:
-                - "iam:CreateAccessKey"
-                - "iam:UpdateAccessKey"
-            severity: "critical"
-            description: "Statement grants both CreateAccessKey and UpdateAccessKey - too permissive"
-
-          # none_of for actions: Flag if forbidden actions are present
-          - actions:
-              none_of:
-                - "iam:DeleteUser"
-                - "s3:DeleteBucket"
-            description: "These dangerous actions should never be used"
-
-          # Per-requirement ignore_patterns: Skip specific requirements for certain files/actions
-          - actions:
-              - "iam:CreateRole"
-              - "iam:PutRolePolicy"
-              - "iam:AttachRolePolicy"
-            required_conditions:
-              - condition_key: "iam:PermissionsBoundary"
-                description: "Require permissions boundary for IAM operations"
-            ignore_patterns:
-              # Ignore this requirement for iam-openid modules (they enforce boundary by default)
-              - filepath_regex: ".*modules//?iam-openid.*"
-
-Note: ignore_patterns can be specified at TWO levels:
-  1. Check-level (applies to ALL requirements): Useful for broad exclusions
-  2. Requirement-level (applies to ONE requirement): Useful for fine-grained control
+"""Action-Specific Condition Enforcement Check.
+
+Ensures specific actions have required IAM conditions (MFA, IP, tags, etc.).
+
+Action Matching Modes:
+- Simple list: actions: ["iam:PassRole"]
+- any_of: Require conditions if ANY action matches
+- all_of: Require conditions if ALL actions present (overly permissive detection)
+- none_of: Flag forbidden actions
+
+Merge Strategies (merge_strategy setting):
+- append (default): User + defaults both apply
+- user_only: Disable ALL defaults, use only user requirements
+- per_action_override: User replaces defaults for matching actions
+- replace_all: User replaces all if provided
+- defaults_only: Ignore user, use only defaults
+
+For full documentation, see: docs/condition-requirements.md
 """
 
 import re
@@ -201,18 +76,8 @@ class ActionConditionEnforcementCheck(PolicyCheck):
         del kwargs  # Not used in current implementation
         issues = []
 
-        # Get action condition requirements from config
-        # Support legacy keys for backward compatibility:
-        #  - "requirements" (current/preferred)
-        #  - "action_condition_requirements" (legacy)
-        #  - "policy_level_requirements" (legacy)
-        requirements = config.config.get(
-            "requirements",
-            config.config.get(
-                "action_condition_requirements",
-                config.config.get("policy_level_requirements", []),
-            ),
-        )
+        # Get action condition requirements using configurable merge strategy
+        requirements = self._get_merged_requirements(config, policy_file)
 
         if not requirements:
             return issues
@@ -246,6 +111,207 @@ class ActionConditionEnforcementCheck(PolicyCheck):
 
         return issues
 
+    def _get_merged_requirements(
+        self,
+        config: CheckConfig,
+        policy_file: str,
+    ) -> list[dict[str, Any]]:
+        """
+        Get merged requirements based on configured merge strategy.
+
+        Supports multiple merge strategies to control how user requirements
+        interact with default requirements:
+        - "per_action_override": User requirements replace defaults for matching actions (default)
+        - "append": User requirements added to defaults (both apply)
+        - "replace_all": User requirements completely replace ALL defaults
+        - "defaults_only": Ignore user requirements, use only defaults
+        - "user_only": Ignore defaults, use only user requirements
+
+        Args:
+            config: Check configuration containing requirements and merge strategy
+            policy_file: Path to the policy file being checked (for ignore_patterns)
+
+        Returns:
+            Merged list of requirements based on strategy
+        """
+        # Get default and user requirements
+        default_requirements = config.config.get(
+            "requirements",
+            config.config.get("policy_level_requirements", []),
+        )
+        user_requirements = config.config.get("action_condition_requirements")
+
+        # Get merge strategy (default: append - both defaults and user requirements apply)
+        merge_strategy = config.config.get("merge_strategy", "append")
+
+        # For user_only, replace_all, and per_action_override:
+        # Filter user requirements by ignore_patterns BEFORE merging
+        # For append and defaults_only: ignore_patterns on user requirements still apply
+        if user_requirements:
+            active_user_requirements = self._filter_requirements_by_filepath(
+                user_requirements, policy_file
+            )
+        else:
+            active_user_requirements = []
+
+        # Apply merge strategy
+        if merge_strategy == "user_only":
+            # Use ONLY user requirements - no defaults at all
+            # If a user requirement is filtered by ignore_patterns, it's simply not checked
+            return active_user_requirements
+
+        elif merge_strategy == "defaults_only":
+            # Use ONLY defaults - ignore all user requirements
+            return default_requirements
+
+        elif merge_strategy == "replace_all":
+            # User requirements completely replace ALL defaults (if user provided any)
+            # If no user requirements provided, fall back to defaults
+            if user_requirements:  # Check original, not filtered
+                return active_user_requirements
+            return default_requirements
+
+        elif merge_strategy == "per_action_override":
+            # User requirements replace defaults for MATCHING actions only
+            # Non-matching defaults are kept
+            # Note: We use the ORIGINAL user_requirements to determine which actions
+            # are "user-defined" (even if filtered out by ignore_patterns)
+            return self._merge_per_action_override(
+                default_requirements, user_requirements or [], active_user_requirements
+            )
+
+        else:  # "append" (default)
+            # Both defaults AND user requirements apply
+            # User requirements are added on top of defaults
+            return default_requirements + active_user_requirements
+
+    def _filter_requirements_by_filepath(
+        self,
+        requirements: list[dict[str, Any]],
+        policy_file: str,
+    ) -> list[dict[str, Any]]:
+        """
+        Filter out requirements that should be ignored for this file.
+
+        This handles ignore_patterns at the requirement level BEFORE merging,
+        allowing defaults to apply when user requirements are ignored.
+
+        Args:
+            requirements: List of requirements to filter
+            policy_file: Path to the policy file being checked
+
+        Returns:
+            Filtered list of requirements (excluding ignored ones)
+
+        Example:
+            User defines: iam:CreateRole with ignore_patterns: [".*test/.*"]
+            When checking test/policy.json:
+            - User requirement is filtered out
+            - Default iam:CreateRole requirement can apply instead
+        """
+        active_reqs = []
+
+        for req in requirements:
+            ignore_patterns = req.get("ignore_patterns", [])
+
+            if not ignore_patterns:
+                # No ignore patterns - include this requirement
+                active_reqs.append(req)
+                continue
+
+            # Check if any ignore pattern matches this file
+            should_ignore = self._should_ignore_filepath(policy_file, ignore_patterns)
+
+            if not should_ignore:
+                active_reqs.append(req)
+
+        return active_reqs
+
+    def _should_ignore_filepath(
+        self,
+        filepath: str,
+        ignore_patterns: list[dict[str, Any]],
+    ) -> bool:
+        """
+        Check if filepath matches any of the ignore patterns.
+
+        Only checks filepath-based patterns (filepath, filepath_regex).
+        This is used for filtering requirements before merging.
+
+        Args:
+            filepath: Path to the policy file
+            ignore_patterns: List of ignore pattern dictionaries
+
+        Returns:
+            True if filepath matches any pattern
+        """
+        for pattern in ignore_patterns:
+            # Only check filepath-based patterns
+            if "filepath" in pattern or "filepath_regex" in pattern:
+                regex_pattern = pattern.get("filepath") or pattern.get("filepath_regex")
+                if regex_pattern:
+                    compiled = compile_and_cache(regex_pattern)
+                    if compiled and compiled.search(filepath):
+                        return True
+        return False
+
+    def _merge_per_action_override(
+        self,
+        default_requirements: list[dict[str, Any]],
+        all_user_requirements: list[dict[str, Any]],
+        active_user_requirements: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """
+        Merge user requirements with defaults on a per-action basis.
+
+        User requirements override defaults for matching actions.
+        Defaults are kept for actions not specified by user.
+
+        Key behavior with ignore_patterns:
+        - If user defines a requirement for action X with ignore_patterns
+        - And the current file matches the ignore_patterns
+        - Then: The user requirement is SKIPPED (not applied)
+        - AND: The default for action X is ALSO skipped (user "owns" this action)
+        - Result: No check for action X on this file
+
+        Args:
+            default_requirements: Default requirements from system config
+            all_user_requirements: ALL user requirements (before ignore_patterns filtering)
+            active_user_requirements: User requirements after ignore_patterns filtering
+
+        Returns:
+            Merged list of requirements
+        """
+        # Build a set of actions that user has customized (from ALL user requirements)
+        # This determines which defaults to exclude
+        user_actions = set()
+        for req in all_user_requirements:
+            actions = req.get("actions", [])
+            # Handle both single action and list of actions
+            if isinstance(actions, str):
+                user_actions.add(actions)
+            else:
+                user_actions.update(actions)
+
+        # Start with ACTIVE user requirements (filtered by ignore_patterns)
+        merged = list(active_user_requirements)
+
+        # Add defaults that don't conflict with user requirements
+        for default_req in default_requirements:
+            default_actions = default_req.get("actions", [])
+            # Handle both single action and list of actions
+            if isinstance(default_actions, str):
+                default_actions = [default_actions]
+
+            # Check if any of the default actions are customized by user
+            has_overlap = any(action in user_actions for action in default_actions)
+
+            if not has_overlap:
+                # No overlap - keep this default requirement
+                merged.append(default_req)
+
+        return merged
+
     def _filter_requirement_issues(
         self,
         issues: list[ValidationIssue],
@@ -1016,33 +1082,52 @@ class ActionConditionEnforcementCheck(PolicyCheck):
                 )
 
                 if not any_present:
-                    # Create a combined error for any_of
-                    # Handle both simple conditions and nested all_of
-                    condition_keys = []
-                    for cond in any_of:
-                        if "all_of" in cond:
-                            # Nested all_of - collect all condition keys
-                            nested_keys = [
-                                c.get("condition_key", "unknown") for c in cond["all_of"]
-                            ]
-                            condition_keys.append(f"({' + '.join(f'`{k}`' for k in nested_keys)})")
-                        else:
-                            # Simple condition
-                            condition_keys.append(f"`{cond.get('condition_key', 'unknown')}`")
-                    condition_keys_formatted = " OR ".join(condition_keys)
-                    matching_actions_formatted = ", ".join(f"`{a}`" for a in matching_actions)
+                    # Check if requirement has custom message/suggestion/example
+                    custom_message = requirement.get("message") if requirement else None
+                    custom_suggestion = requirement.get("suggestion") if requirement else None
+                    custom_example = requirement.get("example") if requirement else None
+
+                    if custom_message:
+                        # Use fully custom message/suggestion/example from requirement
+                        message = custom_message
+                        suggestion = custom_suggestion or ""
+                        example = custom_example or ""
+                    else:
+                        # Generate default message and build suggestion from conditions
+                        condition_keys = []
+                        for cond in any_of:
+                            if "all_of" in cond:
+                                # Nested all_of - collect all condition keys
+                                nested_keys = [
+                                    c.get("condition_key", "unknown") for c in cond["all_of"]
+                                ]
+                                condition_keys.append(
+                                    f"({' + '.join(f'`{k}`' for k in nested_keys)})"
+                                )
+                            else:
+                                # Simple condition
+                                condition_keys.append(f"`{cond.get('condition_key', 'unknown')}`")
+                        condition_keys_formatted = " OR ".join(condition_keys)
+                        matching_actions_formatted = ", ".join(f"`{a}`" for a in matching_actions)
+
+                        message = (
+                            f"Actions {matching_actions_formatted} require at least ONE of these conditions: "
+                            f"{condition_keys_formatted}"
+                        )
+
+                        # Build suggestion and examples from conditions
+                        suggestion, example = self._build_any_of_suggestion(any_of)
+
                     issues.append(
                         ValidationIssue(
                             severity=self.get_severity(config),
                             statement_sid=statement.sid,
                             statement_index=statement_idx,
                             issue_type="missing_required_condition_any_of",
-                            message=(
-                                f"Actions {matching_actions_formatted} require at least ONE of these conditions: "
-                                f"{condition_keys_formatted}"
-                            ),
+                            message=message,
                             action=", ".join(matching_actions),
-                            suggestion=self._build_any_of_suggestion(any_of),
+                            suggestion=suggestion,
+                            example=example if example else None,
                             line_number=statement.line_number,
                         )
                     )
@@ -1241,12 +1326,24 @@ class ActionConditionEnforcementCheck(PolicyCheck):
 
         return suggestion, example_code
 
-    def _build_any_of_suggestion(self, any_of_conditions: list[dict[str, Any]]) -> str:
-        """Build suggestion for any_of conditions."""
+    def _build_any_of_suggestion(self, any_of_conditions: list[dict[str, Any]]) -> tuple[str, str]:
+        """Build suggestion and combined examples for any_of conditions.
+
+        Always uses clean formatting without "Option X" prefixes.
+        Uses either:
+        - 'message' field if provided (custom message)
+        - 'description' field if provided (displays as: `condition_key` - description)
+        - Just 'condition_key' if neither message nor description provided
+
+        Returns:
+            Tuple of (suggestion_text, combined_examples)
+        """
         suggestions = []
+        examples = []
+
         suggestions.append("Add at least ONE of these conditions:")
 
-        for i, cond in enumerate(any_of_conditions, 1):
+        for cond in any_of_conditions:
             # Handle nested all_of blocks
             if "all_of" in cond:
                 # Nested all_of - show all required conditions together
@@ -1254,35 +1351,55 @@ class ActionConditionEnforcementCheck(PolicyCheck):
                 condition_keys = [c.get("condition_key", "unknown") for c in all_of_list]
                 condition_keys_formatted = " + ".join(f"`{k}`" for k in condition_keys)
 
-                option = f"\n- **Option {i}**: {condition_keys_formatted} (both required)"
-
-                # Use description from first condition or combine them
-                descriptions = [
-                    c.get("description", "") for c in all_of_list if c.get("description")
-                ]
-                if descriptions:
-                    option += f" - {descriptions[0]}"
-
-                # Show example from first condition that has one
+                # Check for custom message first
+                custom_message = cond.get("message")
+                if custom_message:
+                    suggestions.append(f"\n- {custom_message}")
+                else:
+                    # Use description from first condition or combine them
+                    descriptions = [
+                        c.get("description", "") for c in all_of_list if c.get("description")
+                    ]
+                    if descriptions:
+                        suggestions.append(f"\n- {condition_keys_formatted} - {descriptions[0]}")
+                    else:
+                        suggestions.append(f"\n- {condition_keys_formatted} (both required)")
+
+                # Collect example from first condition that has one
                 for c in all_of_list:
                     if c.get("example"):
-                        # Example will be shown separately, just note it's available
+                        examples.append(c["example"])
                         break
             else:
-                # Simple condition (original behavior)
-                condition_key = cond.get("condition_key", "unknown")
-                description = cond.get("description", "")
-                expected_value = cond.get("expected_value")
-
-                option = f"\n- **Option {i}**: `{condition_key}`"
-                if description:
-                    option += f" - {description}"
-                if expected_value is not None:
-                    option += f" (value: `{expected_value}`)"
-
-            suggestions.append(option)
-
-        return "".join(suggestions)
+                # Simple condition - check for message, description, or just condition_key
+                custom_message = cond.get("message")
+                if custom_message:
+                    # Use custom message directly
+                    suggestions.append(f"\n- {custom_message}")
+                else:
+                    # Use description if available
+                    condition_key = cond.get("condition_key", "unknown")
+                    description = cond.get("description", "")
+                    expected_value = cond.get("expected_value")
+
+                    if description:
+                        # Format: - `condition_key` - description
+                        suggestions.append(f"\n- `{condition_key}` - {description}")
+                    else:
+                        # Format: - `condition_key` (with expected value if present)
+                        suggestion_line = f"\n- `{condition_key}`"
+                        if expected_value is not None:
+                            suggestion_line += f" (value: `{expected_value}`)"
+                        suggestions.append(suggestion_line)
+
+                # Collect example if present (no prefix)
+                if cond.get("example"):
+                    examples.append(cond["example"])
+
+        suggestion_text = "".join(suggestions)
+        combined_examples = "\n\n".join(examples) if examples else ""
+
+        return suggestion_text, combined_examples
 
     def _create_none_of_issue(
         self,

iam_validator/checks/sensitive_action.py

@@ -271,6 +271,50 @@ class SensitiveActionCheck(PolicyCheck):
 
         return issues
 
+    def _apply_merge_strategy(
+        self,
+        merge_strategy: str,
+        user_config: list[dict] | None,
+        default_config: list[dict] | None,
+    ) -> list[dict] | None:
+        """
+        Apply merge strategy to combine user and default sensitive action patterns.
+
+        Args:
+            merge_strategy: One of "per_action_override", "user_only", "append",
+                          "replace_all", or "defaults_only"
+            user_config: User-provided sensitive action patterns (or None)
+            default_config: Default sensitive action patterns (or None)
+
+        Returns:
+            Merged list of patterns based on strategy, or None if no patterns
+        """
+        if merge_strategy == "user_only":
+            # Use ONLY user patterns, completely ignore defaults
+            return user_config
+
+        elif merge_strategy == "defaults_only":
+            # Use ONLY defaults, ignore user patterns
+            return default_config
+
+        elif merge_strategy == "append":
+            # Combine both (defaults first, then user)
+            result = []
+            if default_config:
+                result.extend(default_config)
+            if user_config:
+                result.extend(user_config)
+            return result if result else None
+
+        elif merge_strategy == "replace_all":
+            # User replaces all if provided, otherwise use defaults
+            return user_config if user_config else default_config
+
+        else:  # "per_action_override" (default)
+            # If user provides patterns, use them; otherwise use defaults
+            # This is the legacy behavior
+            return user_config if user_config else default_config
+
     async def execute_policy(
         self,
         policy: "IAMPolicy",
@@ -319,9 +363,45 @@ class SensitiveActionCheck(PolicyCheck):
                         statement_map[action] = []
                     statement_map[action].append((idx, statement.sid))
 
-        # Get configuration for sensitive actions
-        sensitive_actions_config = config.config.get("sensitive_actions")
-        sensitive_patterns_config = config.config.get("sensitive_action_patterns")
+        # Get configuration for sensitive actions with merge_strategy support
+        # merge_strategy options:
+        # - "append": Add user patterns ON TOP OF defaults (both apply) - DEFAULT
+        # - "user_only": Use ONLY user patterns, disable ALL default privilege escalation patterns
+        # - "defaults_only": Ignore user patterns, use only defaults
+        # - "replace_all": User patterns completely replace ALL defaults (if provided)
+        # - "per_action_override": User patterns replace defaults for matching action combos
+        merge_strategy = config.config.get("merge_strategy", "append")
+
+        # Determine which sensitive_actions patterns to use based on merge_strategy
+        # Note: The config.config already contains deep-merged values from defaults + user config
+        # For lists like sensitive_actions, user config REPLACES defaults (not merges)
+        # So if user provided sensitive_actions, it's already the only value in config.config
+        sensitive_actions_config: list[dict] | None = None
+        sensitive_patterns_config: list[dict] | None = None
+
+        if merge_strategy == "user_only":
+            # user_only: Disable ALL default patterns
+            # If user set merge_strategy: "user_only", they want NO defaults
+            # They must explicitly provide sensitive_actions if they want any checks
+            # Since we can't distinguish user-provided from defaults after merge,
+            # we assume user_only means "no patterns" unless user explicitly provided them
+            # (which would have replaced defaults anyway)
+            sensitive_actions_config = None
+            sensitive_patterns_config = None
+
+        elif merge_strategy == "defaults_only":
+            # Use only defaults - but since config is merged, we use what's there
+            # (user would need to NOT provide sensitive_actions to get defaults)
+            sensitive_actions_config = config.config.get("sensitive_actions")
+            sensitive_patterns_config = config.config.get("sensitive_action_patterns")
+
+        else:
+            # append, replace_all, per_action_override all use the merged config
+            # The deep_merge already handled the merging:
+            # - If user provided sensitive_actions, it replaced defaults
+            # - If user didn't provide it, defaults are in config
+            sensitive_actions_config = config.config.get("sensitive_actions")
+            sensitive_patterns_config = config.config.get("sensitive_action_patterns")
 
         # Check for privilege escalation patterns using all_of logic
         # We need to check both exact actions and patterns

iam_validator/checks/utils/policy_level_checks.py

@@ -98,15 +98,21 @@ def _check_all_of_pattern(
     Returns:
         ValidationIssue if privilege escalation detected, None otherwise
     """
+    # Filter out actions that match ignore_patterns BEFORE checking for privilege escalation
+    # This allows users to exclude specific actions from privilege escalation detection
+    # by adding them to ignore_patterns in sensitive_action config
+    filtered_actions = check_config.filter_actions(frozenset(all_actions))
+    all_actions_filtered = list(filtered_actions)
+
     matched_actions = []
 
     if check_type == "actions":
         # Exact matching
-        matched_actions = [a for a in all_actions if a in required_actions]
+        matched_actions = [a for a in all_actions_filtered if a in required_actions]
     else:
         # Pattern matching - for each pattern, find actions that match
         for pattern in required_actions:
-            for action in all_actions:
+            for action in all_actions_filtered:
                 try:
                     if re.match(pattern, action):
                         matched_actions.append(action)
@@ -167,6 +173,9 @@ def _check_all_of_pattern(
             f"Actions found in:\n  - {stmt_details}",
         )
 
+        # Use custom example if provided in item_config
+        example = item_config.get("example")
+
         return ValidationIssue(
             severity=severity,
             statement_sid=None,  # Policy-level issue
@@ -174,6 +183,7 @@ def _check_all_of_pattern(
             issue_type="privilege_escalation",
             message=message,
             suggestion=suggestion,
+            example=example,
             line_number=1,  # Policy-level issues point to line 1 (top of policy)
         )
 

iam_validator/core/config/defaults.py

@@ -519,7 +519,7 @@ DEFAULT_CONFIG = {
         # Useful when you have specific condition enforcement for certain actions
         # Example: Ignore iam:PassRole since it's checked by action_condition_enforcement
         "ignore_patterns": [
-            {"action_matches": "^iam:PassRole$"},
+            {"action": "^iam:PassRole$"},
         ],
         # Cross-statement privilege escalation patterns (policy-wide detection)
         # These patterns detect dangerous action combinations across ANY statements in the policy
@@ -537,7 +537,19 @@ DEFAULT_CONFIG = {
                     "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"
+                    "• Add strict IAM conditions (IP restrictions, tags, force a specific policy with `iam:PolicyARN` condition)\n"
+                ),
+                "example": (
+                    "{\n"
+                    '  "Condition": {\n'
+                    '    "StringEquals": {\n'
+                    '      "iam:PolicyARN": "arn:aws:iam::*:policy/ReadOnlyAccess"\n'
+                    "    },\n"
+                    '    "IpAddress": {\n'
+                    '      "aws:SourceIp": ["10.0.0.0/8"]\n'
+                    "    }\n"
+                    "  }\n"
+                    "}\n"
                 ),
             },
             # Role privilege escalation: Create role + attach admin policy
@@ -551,6 +563,23 @@ DEFAULT_CONFIG = {
                     "• 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"
                 ),
+                "example": (
+                    "{\n"
+                    '  "Condition": {\n'
+                    '    "StringEquals": {\n'
+                    '      "iam:PermissionsBoundary": "arn:aws:iam::*:policy/MaxPermissions"\n'
+                    "    }\n"
+                    "  }\n"
+                    "}\n"
+                    "OR\n"
+                    "{\n"
+                    '  "Condition": {\n'
+                    '    "StringEquals": {\n'
+                    '      "iam:PolicyARN": "arn:aws:iam::*:policy/MaxPermissions"\n'
+                    "    }\n"
+                    "  }\n"
+                    "}\n"
+                ),
             },
             # Lambda backdoor: Create/update function + invoke
             {
@@ -567,6 +596,18 @@ DEFAULT_CONFIG = {
                     "• Require MFA for Lambda function creation\n"
                     "• Use separate policies for creation vs invocation"
                 ),
+                "example": (
+                    "{\n"
+                    '  "Condition": {\n'
+                    '    "StringEquals": {\n'
+                    '      "aws:PrincipalTag/team": "${aws:ResourceTag/team}"\n'
+                    "    },\n"
+                    '    "SourceIp": {\n'
+                    '      "aws:SourceIp": ["10.0.0.0/8"]\n'
+                    "    }\n"
+                    "  }\n"
+                    "}\n"
+                ),
             },
             # Lambda code modification backdoor
             {
@@ -581,6 +622,15 @@ DEFAULT_CONFIG = {
                     "• Use separate policies for code updates vs invocation\n"
                     "• Implement code signing for Lambda functions"
                 ),
+                "example": (
+                    "{\n"
+                    '  "Condition": {\n'
+                    '    "StringEquals": {\n'
+                    '      "aws:ResourceAccount": "${aws:PrincipalAccount}"\n'
+                    "    }\n"
+                    "  }\n"
+                    "}\n"
+                ),
             },
             # EC2 instance privilege escalation
             {
@@ -595,6 +645,18 @@ DEFAULT_CONFIG = {
                     "• Limit PassRole to specific low-privilege roles\n"
                     "• Require tagging and ABAC controls"
                 ),
+                "example": (
+                    "{\n"
+                    '  "Condition": {\n'
+                    '    "StringEquals": {\n'
+                    '      "iam:PassedToService": "ec2.amazonaws.com"\n'
+                    "    },\n"
+                    '    "ArnLike": {\n'
+                    '      "iam:AssociatedResourceArn": "arn:aws:ec2:*:*:instance/*"\n'
+                    "    }\n"
+                    "  }\n"
+                    "}\n"
+                ),
             },
         ],
     },

iam_validator/core/report.py

@@ -882,6 +882,17 @@ class ReportGenerator:
                 parts.append(f"> 💡 **Suggestion:** {issue.suggestion}")
                 parts.append("")
 
+        # Handle separate example field (if not already in suggestion)
+        if issue.example and "\nExample:\n" not in (issue.suggestion or ""):
+            parts.append("<details>")
+            parts.append("<summary>📖 View Example</summary>")
+            parts.append("")
+            parts.append("```json")
+            parts.append(issue.example)
+            parts.append("```")
+            parts.append("</details>")
+            parts.append("")
+
         return "\n".join(parts)
 
     def save_json_report(self, report: ValidationReport, file_path: str) -> None: