docs(mutelist): fix misleading docstrings about tag and exception logic (#9205)

Author: MrCloudSec

docs/user-guide/cli/tutorials/mutelist.mdx

@@ -19,9 +19,39 @@ The Mutelist option works in combination with other filtering mechanisms and mod
 
 ## How the Mutelist Works
 
-The **Mutelist** uses both "AND" and "OR" logic to determine which resources, checks, regions, and tags should be muted. For each check, the Mutelist evaluates whether the account, region, and resource match the specified criteria using "AND" logic. If tags are specified, the Mutelist can apply either "AND" or "OR" logic.
+The **Mutelist** uses **AND logic** to evaluate whether a finding should be muted. For a finding to be muted, **ALL** of the following conditions must match:
 
-If any of the criteria do not match, the check is not muted.
+- **Account** matches (exact match or `*`)
+- **Check** matches (exact match, regex pattern, or `*`)
+- **Region** matches (exact match, regex pattern, or `*`)
+- **Resource** matches (exact match, regex pattern, or `*`)
+- **Tags** match (if specified)
+
+If **any** of these criteria do not match, the finding is **not muted**.
+
+### Tag Matching Logic
+
+Tags have special matching behavior:
+
+- **Multiple tags in the list = AND logic**: ALL tags must be present on the resource
+  ```yaml
+  Tags:
+    - "environment=dev"
+    - "team=backend"  # BOTH tags required
+  ```
+
+- **Regex alternation within a single tag = OR logic**: Use the pipe operator `|` for OR
+  ```yaml
+  Tags:
+    - "environment=dev|environment=stg"  # Matches EITHER dev OR stg
+  ```
+
+- **Complex tag patterns**: Combine AND and OR using regex
+  ```yaml
+  Tags:
+    - "team=backend"  # Required
+    - "environment=dev|environment=stg"  # AND (dev OR stg)
+  ```
 
 <Note>
 Remember that mutelist can be used with regular expressions.
@@ -40,9 +70,10 @@ The Mutelist file uses the [YAML](https://en.wikipedia.org/wiki/YAML) format wit
 ```yaml
 ### Account, Check and/or Region can be * to apply for all the cases.
 ### Resources and tags are lists that can have either Regex or Keywords.
-### Tags is an optional list that matches on tuples of 'key=value' and are "ANDed" together.
-### Use an alternation Regex to match one of multiple tags with "ORed" logic.
-### For each check you can except Accounts, Regions, Resources and/or Tags.
+### Multiple tags in the list are "ANDed" together (ALL must match).
+### Use regex alternation (|) within a single tag for "OR" logic (e.g., "env=dev|env=stg").
+### For each check you can use Exceptions to unmute specific Accounts, Regions, Resources and/or Tags.
+### All conditions (Account, Check, Region, Resource, Tags) are ANDed together.
 ###########################  MUTELIST EXAMPLE  ###########################
 Mutelist:
   Accounts:
@@ -148,11 +179,11 @@ Mutelist:
 
 | Field| Description| Logic
 |----------|----------|----------
-| `account_id`| Use `*` to apply the mutelist to all accounts.| `ANDed`
-| `check_name`| The name of the Prowler check. Use `*` to apply the mutelist to all checks, or `service_*` to apply it to all service's checks.| `ANDed`
-| `region`| The region identifier. Use `*` to apply the mutelist to all regions.| `ANDed`
-| `resource`| The resource identifier. Use `*` to apply the mutelist to all resources.| `ANDed`
-| `tag`| The tag value.| `ORed`
+| `account_id`| Use `*` to apply the mutelist to all accounts. Supports exact match or wildcard.| `AND` (with other fields)
+| `check_name`| The name of the Prowler check. Use `*` to apply the mutelist to all checks, or `service_*` to apply it to all service's checks. Supports regex patterns.| `AND` (with other fields)
+| `region`| The region identifier. Use `*` to apply the mutelist to all regions. Supports regex patterns.| `AND` (with other fields)
+| `resource`| The resource identifier. Use `*` to apply the mutelist to all resources. Supports regex patterns.| `AND` (with other fields)
+| `tags`| List of tag patterns in `key=value` format. **Multiple tags = AND** (all must match). **Regex alternation within single tag = OR** (use `tag1\|tag2`).| `AND` between tags, `OR` within regex
 
 ### Description
 
@@ -173,6 +204,68 @@ Replace `<provider>` with the appropriate provider name.
 - The Mutelist can be used in combination with other Prowler options, such as the `--service` or `--checks` option, to further customize the scanning process.
 - Make sure to review and update the Mutelist regularly to ensure it reflects the desired exclusions and remains up to date with your infrastructure.
 
+## Current Limitations and Workarounds
+
+### Limitation: No OR Logic Between Different Rule Sets
+
+The current Mutelist schema **does not support OR logic** between different condition sets. Each check can have only **one rule object**, and all conditions are **ANDed** together.
+
+**Example of unsupported scenario:**
+```yaml
+# ❌ INVALID: Cannot have multiple rule blocks for the same check
+Accounts:
+  "*":
+    Checks:
+      "*":  # Rule 1
+        Regions: ["eu-west-1", "us-west-2"]
+        Resources: ["*"]
+      "*":  # Rule 2 - This will OVERWRITE Rule 1 (YAML duplicate key)
+        Regions: ["us-east-1"]
+        Tags: ["environment=dev"]
+```
+
+**Workaround: Use multiple scans with different mutelists**
+
+For complex scenarios requiring OR logic, run separate scans:
+
+```bash
+# Scan 1: Mute findings in non-critical regions
+prowler aws --mutelist-file mutelist_noncritical.yaml
+
+# Scan 2: Mute dev/stg in critical regions
+prowler aws --mutelist-file mutelist_critical.yaml --regions us-east-1,sa-east-1
+```
+
+Then merge the outputs in your reporting pipeline.
+
+### Limitation: Cannot Negate Regions
+
+You cannot express "all regions **except** X and Y". You must explicitly list all regions you want to mute.
+
+**Workaround:**
+```yaml
+# Must enumerate all unwanted regions
+Accounts:
+  "*":
+    Checks:
+      "*":
+        Regions:
+          - "af-south-1"
+          - "ap-east-1"
+          # ... list all regions EXCEPT the ones you want to monitor
+        Resources: ["*"]
+```
+
+### Best Practices
+
+1. **Use regex patterns for flexibility**: Instead of listing multiple resources, use regex patterns like `"dev-.*"` or `"test-instance-[0-9]+"`
+
+2. **Combine tag OR logic with regex**: Use `"environment=dev|environment=stg|environment=test"` instead of multiple tag entries
+
+3. **Be specific with exceptions**: Use the `Exceptions` field to unmute specific resources within a broader muting rule
+
+4. **Test your mutelist**: Run Prowler with `--output-modes json` and verify that the expected findings are muted
+
 ## AWS Mutelist
 
 ### Muting specific AWS regions

prowler/lib/mutelist/mutelist.py

@@ -153,8 +153,10 @@ def is_muted(
         Check if the provided finding is muted for the audited account, check, region, resource and tags.
 
         The Mutelist works in a way that each field is ANDed, so if a check is muted for an account, region, resource and tags, it will be muted.
-        The exceptions are ORed, so if a check is excepted for an account, region, resource or tags, it will not be muted.
-        The only particularity is the tags, which are ORed.
+
+        Exceptions use AND logic across specified fields, with unspecified fields treated as wildcards (matching all values).
+
+        Tag matching uses AND logic when multiple tags are listed (all must match). OR logic is achieved using regex alternation (|) within a single tag pattern.
 
         So, for the following Mutelist:
         ```
@@ -167,11 +169,16 @@ def is_muted(
                         Resources:
                             - 'i-123456789'
                         Tags:
-                            - 'Name=AdminInstance | Environment=Prod'
+                            - 'Name=AdminInstance|Environment=Prod'
                         Description: 'Field to describe why the findings associated with these values are muted'
         ```
         The check `ec2_instance_detailed_monitoring_enabled` will be muted for all accounts and regions and for the resource_id 'i-123456789' with at least one of the tags 'Name=AdminInstance' or 'Environment=Prod'.
 
+        Note: The pipe (|) in the tag pattern provides OR logic via regex alternation. To require BOTH tags, use two separate tag entries:
+        Tags:
+            - 'Name=AdminInstance'
+            - 'Environment=Prod'
+
         Args:
             mutelist (dict): Dictionary containing information about muted checks for different accounts.
             audited_account (str): The account being audited.
@@ -408,12 +415,13 @@ def is_item_matched(matched_items, finding_items, tag=False) -> bool:
         Args:
             matched_items (list): List of items to be matched.
             finding_items (str): String to search for matched items.
-            tag (bool): If True the search will have a different logic due to the tags being ANDed or ORed:
-                - Check of AND logic -> True if all the tags are present in the finding.
-                - Check of OR logic -> True if any of the tags is present in the finding.
+            tag (bool): If True, uses AND logic across multiple tags in the list.
+                - Multiple tags: ALL tags in matched_items must be present in finding_items (AND logic).
+                - Single tag with regex alternation (|): Matches if pattern is found (enables OR within pattern).
+                - For non-tags: Uses OR logic - returns True if ANY item matches.
 
         Returns:
-            bool: True if any of the matched_items are present in finding_items, otherwise False.
+            bool: For tags - True if ALL patterns match. For non-tags - True if ANY pattern matches.
         """
         try:
             is_item_matched = False