---
title: 'Scan Configuration'
sidebarTitle: 'Configuration'
---

import { VersionBadge } from "/snippets/version-badge.mdx"
import { SubscriptionBanner } from "/snippets/subscription-banner.mdx"

<VersionBadge version="5.32.0" />

Scan Configuration lets you override, per provider, specific values in the default configuration Prowler's checks use during a scan. Each configuration can modify how specific checks behave, such as thresholds, allowed values, and retention windows, or exclude checks and services from the scan scope. Attach it to the providers that should use it on their next scan.

<SubscriptionBanner />

## 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.


<Note>
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).
</Note>

## 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
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
```

### Limiting the Scan Scope

<VersionBadge version="5.35.0" />

Use `excluded_checks` to skip individual checks and `excluded_services` to skip every check in a service for the matching provider type:

```yaml
aws:
  excluded_checks:
    - s3_bucket_public_access
  excluded_services:
    - ec2
```

<Warning>
When a Scan Configuration excludes checks or services, Prowler calculates overviews, aggregations, and other result-based information from the reduced scan scope. The displayed information reflects only the checks and services that ran, not a complete assessment of the provider. Consider the applied Scan Configuration when interpreting totals and security posture.
</Warning>

## Creating a Scan Configuration

<Steps>
  <Step title="Open the editor">
    On the **Scan** page (under **Configuration**), click **New Scan Configuration**.
  </Step>
  <Step title="Name it">
    Give the configuration a descriptive **Name** (3–100 characters), e.g. `stricter-iam-aws`.
  </Step>
  <Step title="Write the configuration file">
    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.
  </Step>
  <Step title="Attach providers (optional)">
    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)).
  </Step>
  <Step title="Save">
    Click **Save**. The server validates the configuration values and, if everything is valid, stores it and attaches the selected providers.
  </Step>
</Steps>

<Tip>
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.
</Tip>

## 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'
```

<Warning>
**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
azure:
  defender_attack_path_minimal_risk_level: "Critical"
```
</Warning>

<Info>
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`.
</Info>

## 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**:

<Steps>
  <Step title="Open the provider menu">
    On the **Providers** page, open the **⋮** menu on a provider row.
  </Step>
  <Step title="Click **Edit Scan Configuration**.">
  </Step>
  <Step title="Pick a configuration">
    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**.
  </Step>
</Steps>

<Note>
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).
</Note>

<Info>
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.
</Info>

## 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.

<Note>
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.
</Note>

<Tip>
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.
</Tip>

## 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.

<Note>
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)).
</Note>

**Stricter IAM (Identity and Access Management) hygiene for AWS:**

```yaml
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
azure:
  defender_attack_path_minimal_risk_level: "Critical"
```

**Tighten GCP storage retention and key rotation:**

```yaml
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).
