> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prowler.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Scan Configuration
export const SubscriptionBanner = ({children}) => {
return
This feature is available exclusively in Prowler Cloud and Prowler Enterprise with a subscription.
{children}
;
};
export const VersionBadge = ({version}) => {
return
Added in:
{version}
;
};
Scan Configuration lets you override, per provider, specific values in the default configuration Prowler's checks use during a scan. Each configuration modifies how specific checks behave, e.g.: thresholds, allowed values, retention windows, and you attach it to the providers that you want to use it on their next scan.
## What Is a Scan Configuration?
A Scan Configuration lets you **override specific values, per provider**, on top of Prowler's defaults. It's merged with those defaults, not a full replacement:
* A provider type you don't add a section for keeps using `config.yaml` untouched.
* **A provider type you do add a section for has its keys merged over `config.yaml` for that provider.** Only the keys you set are overridden; every key you leave out keeps its default from `config.yaml`, because each check falls back to the default configuration when a value isn't provided. See [How It's Applied](#how-its-applied) for details.
* It is stored per organization and applied to the **providers you attach** to it.
* **Attaching a provider is optional at creation time.** You can save a Scan Configuration with no providers attached and associate them later, either from the configuration's editor or from the **Providers** page (see [Attaching Providers](#attaching-providers)). It has no effect on any scan until at least one provider is attached.
* A provider can be attached to **at most one** Scan Configuration at a time.
* Changes take effect on the provider's **next scan** and do not re-run past scans.
The full set of configurable values and their defaults lives in [`prowler/config/config.yaml`](https://github.com/prowler-cloud/prowler/blob/master/prowler/config/config.yaml). For what each key means and which checks read it, see the [Configuration File tutorial](/user-guide/cli/tutorials/configuration_file).
## Required Permissions
Scan Configuration access is governed by Role-Based Access Control (RBAC). See [RBAC Administrative Permissions](/user-guide/tutorials/prowler-app-rbac#rbac-administrative-permissions) for details on each permission.
* **Viewing** a Scan Configuration doesn't require any specific permission.
* **Creating, editing, and deleting** a Scan Configuration requires the **Manage Scans** permission.
* **Attaching or detaching providers** requires the **Manage Providers** permission as well, in addition to Manage Scans. This applies to explicit changes to the attached providers, and to deleting a Scan Configuration that still has providers attached (deleting it detaches them too).
* Attaching or detaching a provider also requires that provider to be **visible to your role**. Visibility comes from the [Provider Groups](/user-guide/tutorials/prowler-app-rbac#provider-groups) assigned to your role, or from **Unlimited Visibility**. You can't attach a provider you can't see, and you can't detach one either, whether by removing it from the list or by deleting the Scan Configuration it's attached to.
## Config Schema
The YAML follows the structure of `config.yaml`: a mapping keyed by provider, with each provider section holding the keys you want to change. You only list the keys you want to override; they're merged over that provider's `config.yaml` defaults.
```yaml theme={null}
aws:
max_unused_access_keys_days: 30
max_console_access_days: 30
max_security_group_rules: 25
azure:
defender_attack_path_minimal_risk_level: "Critical"
gcp:
storage_min_retention_days: 30
```
## Creating a Scan Configuration
On the **Scan** page (under **Configuration**), click **New Scan Configuration**.
Give the configuration a descriptive **Name** (3–100 characters), e.g. `stricter-iam-aws`.
In the **Configuration (YAML)** field, add the keys you want to change, grouped by provider. Only the keys you set are overridden; every other key keeps its `config.yaml` default. The editor is pre-filled with a representative default placeholder you can use as a starting point.
Under **Attach to providers**, pick the providers that should use this configuration. This is optional, you can save without any provider and attach them later, either by editing this configuration or from the **Providers** page (see [Attaching Providers](#attaching-providers)).
Click **Save**. The server validates the configuration values and, if everything is valid, stores it and attaches the selected providers.
You don't need to fill in every provider. A section you don't include leaves that provider's `config.yaml` untouched. Within a section you do include, only add the keys you want to change; the rest keep their `config.yaml` defaults. The placeholder shown in the editor is just an example; if you leave the field with only the placeholder (greyed-out) text, nothing is saved.
## How Validation Works
Prowler checks your configuration in two stages, the same way the Advanced Mutelist editor does:
1. **As you type: is it well-formed?** The editor checks that what you've written is valid YAML. If something is off, you'll see an `Invalid YAML format` message and **Save** stays disabled until you fix it. Once it's clean, it shows **Valid YAML format**.
2. **When you save: are the values allowed?** Saving checks that each value is one Prowler accepts, the right type, within range, and one of the allowed options where a key only takes a fixed set of choices. If a value isn't allowed, the editor points to the exact key and explains why, right beneath the field, so you can correct it and save again.
For example, `azure.defender_attack_path_minimal_risk_level` only accepts `Low`, `Medium`, `High`, or `Critical`. Saving any other value returns an inline error like:
```
azure.defender_attack_path_minimal_risk_level: Input should be 'Low', 'Medium', 'High' or 'Critical'
```
**Valid YAML format** only means the text is well-formed; it doesn't mean your values are accepted. Those are checked when you save.
Be careful with indentation. A line like `azure: defender_attack_path_minimal_risk_level: Critical` (no line break and indent after `azure:`) is still valid YAML, but Prowler reads it as one long key name instead of a setting inside the `azure` section, so the value is silently ignored. Always nest provider keys:
```yaml theme={null}
azure:
defender_attack_path_minimal_risk_level: "Critical"
```
Prowler won't flag a section or key it doesn't recognize. It accepts them without error, so custom checks and plugins can add their own settings. The trade-off: a typo in a key or section name isn't rejected either, and that misspelled setting simply won't apply. Double-check your spelling against `config.yaml`.
## Attaching Providers
A Scan Configuration only has an effect once it's attached to one or more providers. There are two ways to manage attachments.
### From the Scan Config Editor
In the **Attach to providers** field, select the providers that should use this configuration. Providers already attached to **another** configuration are hidden from the selector, since each provider can belong to only one configuration at a time.
### From the Provider's Row Menu
You can also manage a provider's configuration from **Providers**:
On the **Providers** page, open the **⋮** menu on a provider row.
In the dialog, pick a configuration from the dropdown to apply it (picking a different one moves the provider), or pick **Default** to detach it and go back to the built-in `config.yaml` defaults. Then click **Save**.
This dialog only **associates or disassociates** an existing configuration. To create or edit the configuration's YAML, use the **Scan Config** view (a link is provided in the dialog).
Because a provider can belong to only one configuration, associating a provider that is already attached elsewhere **moves** it to the new configuration automatically; it is removed from the previous one.
## Editing and Deleting
On the **Scan Config** page, open the **⋮** menu on a configuration row:
* **Edit:** Choose **Edit** to open the editor, change its name, YAML, or attached providers, and click **Update**. Editing the YAML always happens here, never from the provider row.
* **Delete:** Choose **Delete** (in the danger zone) and confirm. Providers that were attached fall back to the built-in defaults from `config.yaml` on their next scan.
## How It's Applied
When a scan runs for a provider:
1. If the provider is attached to a Scan Configuration **and that configuration has a section for the provider's type** (e.g. `aws` for an AWS provider), Prowler merges that section over `config.yaml` for that provider's scan: the keys you set win, and every key you didn't set keeps its `config.yaml` default.
2. If the provider is attached to a Scan Configuration, but that configuration **has no section for the provider's type** (for example, a configuration that only defines an `aws` section, attached to a GCP provider), the scan uses the built-in defaults from `config.yaml` for that provider, exactly as if no Scan Configuration were attached at all.
3. If the provider isn't attached to any Scan Configuration, the built-in defaults from `config.yaml` are used.
The merge is per key. A key you don't set keeps its `config.yaml` default, because each check falls back to the default configuration when a value isn't provided. You only need to list the keys you want to change.
A single Scan Configuration can hold sections for several provider types at once (see [Config Schema](#config-schema)) and be attached to providers of different types. Each provider only ever picks up the section matching its own type; the rest of the YAML is ignored for that provider.
## Effect on Compliance Results
Some compliance requirements only hold if the checks they map to ran with a strict-enough configuration. For example, a requirement expecting unused access keys to be disabled within 45 days loses its meaning if a Scan Configuration raises `max_unused_access_keys_days` to 120: the check would still PASS, but the requirement wouldn't really be met.
When a scan's applied configuration doesn't meet a requirement's expectations, Prowler marks that requirement as **FAIL** on the Compliance page, even if every individual finding passed. The requirement shows an info icon (and, when expanded, an inline alert) with:
> Marked as FAIL because the applied scan configuration does not meet this requirement, even though all findings passed.
This only affects requirements built around a configurable check that declares this kind of expectation; requirements without one are never affected by an attached Scan Configuration.
## Common Examples
Each example below shows only the keys being changed for that provider.
Only the keys shown are overridden. Every other key for that provider keeps its `config.yaml` default (see [How It's Applied](#how-its-applied)).
**Stricter IAM (Identity and Access Management) hygiene for AWS:**
```yaml theme={null}
aws:
max_unused_access_keys_days: 30
max_console_access_days: 30
max_unused_sagemaker_access_days: 45
```
**Raise Azure Defender attack-path sensitivity:**
```yaml theme={null}
azure:
defender_attack_path_minimal_risk_level: "Critical"
```
**Tighten GCP storage retention and key rotation:**
```yaml theme={null}
gcp:
storage_min_retention_days: 30
secretmanager_max_rotation_days: 30
```
## Troubleshooting
### A Provider Doesn't Appear in the Selector
The provider is already attached to another Scan Configuration. Detach it there first, or use the provider row menu to move it.
### You Can't Attach or Detach Providers
If you can edit the configuration but not change its providers, or an error mentions a provider ID that "wasn't found", you're missing the **Manage Providers** permission or the provider isn't visible to your role. A provider outside your visibility is reported the same way as one that doesn't exist, so it isn't revealed to roles that shouldn't see it. See [Required Permissions](#required-permissions).