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

2026-07-23 12:31:54 +00:00 · 2025-11-10 13:39:24 -05:00
parent be0b8bba0d
commit 7c339ed9e4
2 changed files with 118 additions and 17 deletions
@@ -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