ben.carrasco/prowler
1
0
Fork 0
mirror of https://github.com/prowler-cloud/prowler.git synced 2025-12-19 05:17:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Sergio Garcia
2025-11-10 13:39:24 -05:00
committed by GitHub
parent be0b8bba0d
commit 7c339ed9e4
2 changed files with 118 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
docs/user-guide/cli/tutorials/mutelist.mdx
View File

@@ -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

22
prowler/lib/mutelist/mutelist.py
View File

@@ -153,8 +153,10 @@ class Mutelist(ABC):
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 @@ class Mutelist(ABC):
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 @@ class Mutelist(ABC):
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