mirror of
https://github.com/prowler-cloud/prowler.git
synced 2026-10-21 10:54:20 +00:00
Merge remote-tracking branch 'origin/master' into mintlify/cb114598
This commit is contained in:
mintlify[bot] committed
commit
270490e93e
360 files changed
+26723
-2091
No files matched your search
@@ -15,26 +15,24 @@ Attack Paths analyzes relationships between cloud resources, permissions, and se
|
||||
By mapping these relationships as a graph, Attack Paths reveals risks that individual security checks cannot detect on their own, such as an IAM role that can escalate its own permissions, or a chain of policies that grants unintended access to sensitive resources.
|
||||
|
||||
<Note>
|
||||
Attack Paths is currently available for **AWS** providers. Support for
|
||||
additional providers is planned.
|
||||
Attack Paths is currently available for **AWS** providers. Support for additional providers is planned.
|
||||
</Note>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The following prerequisites are required for Attack Paths:
|
||||
|
||||
- **An AWS provider is configured** with valid credentials in Prowler Cloud. For setup instructions, see [Getting Started with AWS](/user-guide/providers/aws/getting-started-aws).
|
||||
- **An AWS provider is configured** with valid credentials. For setup instructions, see [Getting Started with AWS](/user-guide/providers/aws/getting-started-aws).
|
||||
- **At least one scan has completed** on the configured AWS provider and produced graph data. Attack Paths scans run automatically alongside regular security scans, no separate configuration is required.
|
||||
|
||||
## How Attack Paths Scans Work
|
||||
|
||||
Attack Paths scans are generated automatically when a security scan runs on an AWS provider. Each completed scan produces graph data that maps relationships between IAM principals, policies, trust configurations, and other resources.
|
||||
Attack Paths scans are generated automatically when a security scan runs on an AWS provider. When a scan produces graph data, it maps relationships between IAM principals, policies, trust configurations, and other resources. A scan can complete without producing graph data.
|
||||
|
||||
Once the scan finishes and graph data is ready, the scan appears in the Attack Paths scan table with a **Completed** status and a check in the **Graph** column. Scans that are still queued or running remain visible, but they cannot be selected until graph data is ready.
|
||||
When graph data is ready, the scan appears in the Attack Paths scan table with a check in the **Graph** column and can be selected regardless of its current status. Scans without graph data remain visible but cannot be selected. If a new scan cycle starts after graph data is available, the previous cycle remains available while the new scan runs.
|
||||
|
||||
<Note>
|
||||
Since Prowler scans all configured providers every **24 hours** by default,
|
||||
Attack Paths data stays up to date automatically.
|
||||
Prowler Cloud and Prowler Private Cloud scan configured providers every **24 hours** by default, so Attack Paths data stays up to date automatically.
|
||||
</Note>
|
||||
|
||||
## Accessing Attack Paths
|
||||
@@ -65,7 +63,7 @@ The scans table displays all Attack Paths scans with the following columns:
|
||||
- **Graph:** Whether Attack Paths graph data is available for the scan.
|
||||
- **Duration:** Total scan time.
|
||||
|
||||
To select a scan for analysis, click the radio button on any row with a **Completed** status and available graph data.
|
||||
To select a scan for analysis, click any row with a check in the **Graph** column. A row can remain selectable while a new scan cycle runs because Attack Paths keeps the graph from the previous completed cycle available.
|
||||
|
||||
<img
|
||||
src="/images/prowler-app/attack-paths/scan-list-table.png"
|
||||
@@ -74,8 +72,7 @@ To select a scan for analysis, click the radio button on any row with a **Comple
|
||||
/>
|
||||
|
||||
<Note>
|
||||
Only scans with graph data can be selected. Disabled rows include a tooltip
|
||||
that explains why the graph is not available yet.
|
||||
Only scans with graph data can be selected. Disabled rows include a tooltip that explains why the graph is not available yet.
|
||||
</Note>
|
||||
|
||||
## Choosing a Query
|
||||
@@ -96,9 +93,7 @@ To choose a query, click the dropdown and select from the available options. Eac
|
||||
Once selected, a description panel appears below the dropdown with more context about the query.
|
||||
|
||||
<Note>
|
||||
In Prowler Cloud and Prowler Private Cloud, the query selector hides queries
|
||||
confirmed empty for the selected scan, so only queries that return data remain
|
||||
visible. See [Active Queries](/user-guide/tutorials/prowler-app-attack-paths-active-queries).
|
||||
In Prowler Cloud and Prowler Private Cloud, the query selector hides built-in queries confirmed empty for the selected scan. Built-in queries without a confirmed empty result and the **Custom openCypher query** remain visible. See [Active Queries](/user-guide/tutorials/prowler-app-attack-paths-active-queries).
|
||||
</Note>
|
||||
|
||||
## Configuring Query Parameters
|
||||
@@ -119,7 +114,7 @@ For example, **Internet-Exposed EC2 with Sensitive S3 Access** uses **Tag key**
|
||||
|
||||
## Writing Custom openCypher Queries
|
||||
|
||||
In addition to the built-in queries, Attack Paths supports custom read-only [openCypher](https://opencypher.org/) queries. Custom queries provide direct access to the underlying graph so security teams can answer ad-hoc questions, prototype detections, or extend coverage beyond the built-in catalogue.
|
||||
In addition to the built-in queries, Attack Paths supports custom read-only [openCypher](https://opencypher.org/) queries. Custom queries provide direct access to the underlying graph so security teams can answer ad-hoc questions, prototype detections, or extend coverage beyond the built-in catalog.
|
||||
|
||||
To write a custom query, select **Custom openCypher query** from the query dropdown. A code editor with syntax highlighting and line numbers appears, ready to receive the query.
|
||||
|
||||
@@ -191,11 +186,7 @@ Custom queries traverse the same Cartography graph the built-in queries use. Nod
|
||||
For the complete reference, including the graph model, list-typed and JSON-encoded properties, performance guidance, and openCypher compatibility rules, see [Attack Paths Queries](/developer-guide/attack-paths-queries) in the Developer Guide.
|
||||
|
||||
<Note>
|
||||
AI assistants connected through Prowler MCP Server can fetch the exact
|
||||
Cartography schema for the active scan via the
|
||||
`prowler_get_attack_paths_cartography_schema` tool. This guarantees that
|
||||
generated queries match the schema version pinned by the running Prowler
|
||||
release.
|
||||
AI assistants connected through Prowler MCP Server can fetch the exact Cartography schema for the active scan via the `prowler_get_attack_paths_cartography_schema` tool. This guarantees that generated queries match the schema version pinned by the running Prowler release.
|
||||
</Note>
|
||||
|
||||
## Executing a Query
|
||||
@@ -220,12 +211,22 @@ If the query returns no results, an informational message appears. Common reason
|
||||
|
||||
After a successful execution, the graph visualization renders below the query builder. The graph maps relationships between cloud resources, IAM entities, public exposure, and security findings.
|
||||
|
||||
### Grouped Graphs and Query Outcomes
|
||||
|
||||
<VersionBadge version="5.39.0" />
|
||||
|
||||
Prowler Cloud and Prowler Private Cloud group resources of the same class and graph level into expandable nodes. Built-in query graphs also end with a query outcome, which states the result that the path can lead to.
|
||||
|
||||
Prowler Local Server keeps the flat graph view, including the provider root. Custom openCypher queries do not have a catalog outcome, so their graphs do not include an outcome node.
|
||||
|
||||
### Node Types
|
||||
|
||||
- **Provider root nodes:** Represent the AWS account or provider root for the selected scan.
|
||||
- **Resource nodes:** Represent cloud resources such as IAM roles, policies, EC2 instances, security groups, and S3 buckets.
|
||||
- **Grouped resource nodes:** Represent multiple resources of the same class in Prowler Cloud and Prowler Private Cloud. A number in the upper-right corner shows how many resources the node contains. A red outline indicates that one or more resources in the group have findings.
|
||||
- **Resource nodes:** Represent individual cloud resources such as IAM roles, policies, EC2 instances, security groups, and S3 buckets. A class with one resource remains an individual node.
|
||||
- **Internet nodes:** Represent exposure from the public internet.
|
||||
- **Finding nodes:** Represent Prowler findings linked to resources. Finding colors indicate risk level, such as critical, high, medium, or low.
|
||||
- **Outcome nodes:** Mark the terminal result of a built-in query in Prowler Cloud and Prowler Private Cloud. The orange node displays outcomes such as **Code execution**, **Privilege escalation**, **Public exposure**, or **Resource inventory**. A dashed ring and the label **Latent outcome** indicate an inventory or another partial outcome.
|
||||
- **Provider root nodes:** Represent the AWS account or provider root in the Prowler Local Server flat graph.
|
||||
|
||||
### Edge Types
|
||||
|
||||
@@ -233,7 +234,7 @@ After a successful execution, the graph visualization renders below the query bu
|
||||
- **Finding edges:** Dashed relationships between resources and their associated findings.
|
||||
- **Highlighted paths:** Green edges that show the active path when you hover a node or focus a finding.
|
||||
|
||||
The standard graph view includes a minimap and a legend below the canvas. The legend shows the provider roots, visible node types, finding risk levels, node states, and edge types present in the current view.
|
||||
The standard graph view includes a minimap and a legend below the canvas. The legend shows the visible node types, finding risk levels, node states, and edge types present in the current view. Prowler Local Server also displays the provider root in the legend.
|
||||
|
||||
<img
|
||||
src="/images/prowler-app/attack-paths/graph-visualization.png"
|
||||
@@ -243,17 +244,32 @@ The standard graph view includes a minimap and a legend below the canvas. The le
|
||||
|
||||
## Interacting with the Graph
|
||||
|
||||
The graph banner describes the main interactions:
|
||||
The graph supports these interactions:
|
||||
|
||||
- Click a node with a number in the upper-right corner to expand its resource group.
|
||||
- Click a finding to focus its connected path.
|
||||
- Click a resource with findings to show or hide its related findings.
|
||||
- Hover a node to highlight its connected path.
|
||||
|
||||
### Expanding Resource Groups
|
||||
|
||||
In Prowler Cloud and Prowler Private Cloud, a node with a number in its upper-right corner represents a resource group. The number is the total number of resources in the group.
|
||||
|
||||
- Click the group node to display its resources. Multiple groups can remain expanded, and the graph automatically fits the visible nodes to the canvas.
|
||||
- Double-click any resource revealed from a group to collapse that group.
|
||||
- Click **Collapse all groups** in the graph toolbar to close every expanded group. This control appears only while at least one group is expanded.
|
||||
|
||||
<img
|
||||
src="/images/prowler-app/attack-paths/graph-visualization-expanded.png"
|
||||
alt="Attack Paths graph showing an expanded AWS Role group and remaining numbered resource groups"
|
||||
width="700"
|
||||
/>
|
||||
|
||||
### Showing Related Findings
|
||||
|
||||
Resource nodes with related findings are clickable. Click one of these resources to show its finding nodes. Click the resource again to hide them.
|
||||
|
||||
The graph automatically fits the selected resource and its related findings when the findings are shown.
|
||||
The selected resource is highlighted in green while its findings are visible. The graph automatically fits the selected resource and its related findings when the findings are shown.
|
||||
|
||||
### Focusing a Finding Path
|
||||
|
||||
@@ -278,12 +294,12 @@ The toolbar in the top-right corner of the graph provides:
|
||||
|
||||
- **Zoom in / Zoom out:** Adjust the zoom level
|
||||
- **Fit graph to view:** Reset the view to fit the visible graph
|
||||
- **Export graph:** Download the current graph as a PNG file
|
||||
- **Collapse all groups:** Close every expanded resource group. This control appears only when a group is expanded
|
||||
- **Export graph:** Download the current graph, including its grouped or expanded state and outcome, as a PNG file
|
||||
- **Fullscreen:** Open the graph in a full-size modal
|
||||
|
||||
<Note>
|
||||
Use **Ctrl + Scroll** (or **Cmd + Scroll** on macOS) to zoom directly within
|
||||
the graph area.
|
||||
Use **Ctrl + Scroll** (or **Cmd + Scroll** on macOS) to zoom directly within the graph area.
|
||||
</Note>
|
||||
|
||||
## Viewing Finding Details
|
||||
|
||||
@@ -41,12 +41,12 @@ The status selector includes manual statuses. Prowler also sets automatic status
|
||||
| **Remediating** | Manual | Work is in progress to fix the finding. |
|
||||
| **Risk Accepted** | Manual | The team accepts the risk and wants to mute the finding. |
|
||||
| **False Positive** | Manual | The finding does not apply and should be muted. |
|
||||
| **Resolved** | Automatic | A finding changed from `FAIL` to `PASS` in a later scan. A passed finding with no saved triage state also appears as **Resolved**. |
|
||||
| **Resolved** | Automatic / Manual | A finding changed from `FAIL` to `PASS` in a later scan. A passed finding with no saved triage state also appears as **Resolved**. On `MANUAL` findings, select it to verify the finding as passing (see [Verify a MANUAL Finding as Pass](#verify-a-manual-finding-as-pass)). |
|
||||
| **Reopened** | Automatic | A finding changed from `PASS` to `FAIL` in a later scan. |
|
||||
|
||||
|
||||
|
||||
Resolved and Reopened are not manual selector options.
|
||||
**Reopened** is never a manual selector option. **Resolved** appears in the selector only on `MANUAL` findings, where it starts the [Manual Pass verification](#verify-a-manual-finding-as-pass).
|
||||
|
||||
These automatic states keep triage tied to the finding UID across scans, even when each scan creates a new finding snapshot.
|
||||
|
||||
@@ -92,6 +92,39 @@ Triage notes are visible only to the team in the current organization. Each note
|
||||
|
||||
To remove an existing note, clear the note text and save the change.
|
||||
|
||||
## Verify a MANUAL Finding as Pass
|
||||
|
||||
<VersionBadge version="5.39.0" />
|
||||
|
||||
Checks that Prowler cannot judge automatically report `MANUAL` findings. When a team verifies such a control outside Prowler, the triage selector on that finding offers **Resolved**: choosing it records a Manual Pass attestation, and the finding reports an effective `PASS` while keeping the raw `MANUAL` scan result.
|
||||
|
||||
|
||||
|
||||
<Steps>
|
||||
<Step title="Filter MANUAL findings">
|
||||
Go to **Findings** and filter by status **Manual**.
|
||||
</Step>
|
||||
<Step title="Open the triage selector">
|
||||
Expand a Finding Group and click the current status in the **Triage** column of an individual finding.
|
||||
</Step>
|
||||
<Step title="Choose Resolved">
|
||||
Select **Resolved**. Prowler opens the triage note modal with a required **Manual pass evidence** field.
|
||||
</Step>
|
||||
<Step title="Record the evidence">
|
||||
Describe how the control was verified, then click **Save**. The evidence supports up to 500 characters.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
|
||||
|
||||
After saving, the finding reports `PASS` in finding tables, finding groups, compliance reports, and scans. While the attestation is active, the triage status is managed automatically and cannot be changed. **View Manual Pass details** shows who verified the finding, the evidence, the attestation time, and its expiration.
|
||||
|
||||
|
||||
|
||||
### Attestation Expiration
|
||||
|
||||
A Manual Pass attestation is valid for 90 days. It also ends early when a later scan reports a real failure for the finding. In both cases the finding returns to its raw `MANUAL` status for a new review.
|
||||
|
||||
## Mutelist Behavior
|
||||
|
||||
Findings Triage uses Mutelist when a status means the finding should be muted:
|
||||
@@ -117,7 +150,7 @@ Confirm that the user role has **Manage Scans** permission. Prowler Local Server
|
||||
|
||||
### Resolved or Reopened is missing from the selector
|
||||
|
||||
This is expected. Prowler sets **Resolved** and **Reopened** automatically from scan result changes.
|
||||
**Reopened** is always automatic. **Resolved** is set automatically from scan result changes and appears as a selector option only on `MANUAL` findings, where it records a [Manual Pass](#verify-a-manual-finding-as-pass). On findings with any other status, this is expected.
|
||||
|
||||
### Risk Accepted or False Positive muted a finding
|
||||
|
||||
|
||||
@@ -66,7 +66,7 @@ The Prowler wizard walks you through the entire flow: deploying both roles from
|
||||
<Frame>
|
||||
<img src="/images/organizations/aws-console-org-id.png" alt="AWS Organizations Console showing the Organization ID in the left sidebar" />
|
||||
</Frame>
|
||||
- **Name** (optional): A display name for the organization. If left blank, Prowler uses the name stored in AWS.
|
||||
- **Name** (optional): A display name for the organization. If left blank, Prowler uses the AWS organization ID.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/organization-details-form.png" alt="Organization Details form with Organization ID and Name fields" />
|
||||
@@ -280,7 +280,7 @@ Open the row actions menu on the organization row on the **Providers** page.
|
||||
|
||||
| Action | What it does |
|
||||
|--------|--------------|
|
||||
| **Edit Organization Name** | Renames the organization in Prowler. Leave it blank to fall back to the name stored in AWS. |
|
||||
| **Edit Organization Name** | Renames the organization in Prowler. Leave it blank to fall back to the AWS organization ID. |
|
||||
| **Update Credentials** | Reopens the Authentication Details step to store a new Role ARN. |
|
||||
| **Edit Scan Schedule** | Applies one schedule to every connected account in the organization. |
|
||||
| **Test Connections (N)** | Re-tests every account in the organization. |
|
||||
|
||||
@@ -1,11 +1,467 @@
|
||||
---
|
||||
title: 'Azure Management Groups'
|
||||
description: 'Onboard all Azure subscriptions in your management groups through a single guided wizard'
|
||||
tag: "Coming Soon"
|
||||
description: 'Discover the Azure subscriptions in your management groups and onboard the ones you select through a single guided wizard'
|
||||
---
|
||||
|
||||
Onboarding Azure management groups through a single guided wizard is coming soon to Prowler Cloud.
|
||||
import { VersionBadge } from "/snippets/version-badge.mdx"
|
||||
import { SubscriptionBanner } from "/snippets/subscription-banner.mdx"
|
||||
|
||||
Today, Azure subscriptions are onboarded individually. See [Getting Started with Azure](/user-guide/providers/azure/getting-started-azure) and [Bulk Provider Provisioning](/user-guide/tutorials/bulk-provider-provisioning) to automate onboarding multiple subscriptions.
|
||||
<VersionBadge version="5.39.0" />
|
||||
|
||||
Keep an eye on the [changelog](https://github.com/prowler-cloud/prowler/releases) for updates.
|
||||
Prowler Cloud discovers every Azure subscription in your Microsoft Entra tenant and onboards the eligible ones you select, through a single guided wizard. Instead of connecting subscriptions one by one, you can discover every Management Group and subscription under the tenant root Management Group, select the ones you want to monitor, test connectivity, and launch scans — all from the Prowler Cloud UI.
|
||||
|
||||
<SubscriptionBanner>
|
||||
For Command-Line Interface (CLI) scanning of several subscriptions, see [Configuring Specific Subscription Scans in Prowler](/user-guide/providers/azure/subscriptions).
|
||||
</SubscriptionBanner>
|
||||
|
||||
To follow this guide you need an active [Prowler Cloud](https://cloud.prowler.com) account and an Azure service principal with read access granted **at the tenant root Management Group**.
|
||||
|
||||
## Overview
|
||||
|
||||
### Individual Subscriptions vs Azure Management Groups
|
||||
|
||||
| Approach | Best for | How it works |
|
||||
|----------|----------|--------------|
|
||||
| **Individual subscriptions** | A few Azure subscriptions | Connect each subscription one by one with its own service principal credential. |
|
||||
| **Azure Management Groups** | 10+ subscriptions, or any tenant organized into Management Groups | Connect once with a tenant-wide credential, discover every Management Group and subscription automatically, and scan them in bulk. |
|
||||
|
||||
### How It Works
|
||||
|
||||
Onboarding runs in four stages:
|
||||
|
||||
1. **Grant read access** to one service principal at the tenant root Management Group.
|
||||
2. **Discover** — Prowler walks the Management Group hierarchy and returns every Management Group and subscription under the tenant root.
|
||||
3. **Select and connect** — choose the subscriptions to monitor. Prowler creates one provider per subscription and tests every connection.
|
||||
4. **Launch scans** — apply a scan schedule across the connected subscriptions.
|
||||
|
||||
<Note>
|
||||
**Nothing is deployed into your tenant.** Unlike AWS Organizations onboarding, Azure onboarding creates no resources in Azure. Prowler reuses the service principal credential you provide as the credential of every subscription it onboards, so one credential covers discovery and scanning once all the required permissions are granted.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
**Onboarding always covers the whole tenant.** Prowler scopes the organization to the tenant root Management Group, which it derives from the Microsoft Entra tenant ID. The wizard therefore asks for the tenant, never for a Management Group — there is no partial onboarding from a Management Group further down the hierarchy.
|
||||
</Note>
|
||||
|
||||
## Before You Start
|
||||
|
||||
### Create a Service Principal
|
||||
|
||||
Prowler Cloud authenticates against Azure with a service principal application. To create one, follow [Creating a Prowler Service Principal Application](/user-guide/providers/azure/create-prowler-service-principal). Keep the **client ID** and the **client secret** — the wizard asks for both.
|
||||
|
||||
### Grant Read Access at the Tenant Root Management Group
|
||||
|
||||
Discovery reads the Management Group hierarchy and the subscriptions inside it. Assign the built-in **Reader** role to the service principal **on the tenant root Management Group**, so the grant covers every Management Group and subscription beneath it:
|
||||
|
||||
```bash
|
||||
TENANT_ID=<microsoft-entra-tenant-id>
|
||||
CLIENT_ID=<prowler-service-principal-client-id>
|
||||
|
||||
# Resolve the exact service principal from its client ID. A display-name search
|
||||
# is a prefix match, so it can return a different principal than intended.
|
||||
SP_OBJECT_ID=$(az ad sp show --id "$CLIENT_ID" --query id -o tsv)
|
||||
|
||||
az role assignment create \
|
||||
--role "Reader" \
|
||||
--assignee-object-id "$SP_OBJECT_ID" \
|
||||
--assignee-principal-type ServicePrincipal \
|
||||
--scope "/providers/Microsoft.Management/managementGroups/$TENANT_ID"
|
||||
```
|
||||
|
||||
<Note>
|
||||
The tenant root Management Group is named after the tenant ID, so its resource identifier is always `/providers/Microsoft.Management/managementGroups/<tenant-id>`. Creating a role assignment there requires **Owner** or **User Access Administrator** at that scope; a Global Administrator who holds neither can grant themselves access through the elevated-access toggle in Microsoft Entra ID.
|
||||
</Note>
|
||||
|
||||
### Grant the Scanning Permissions
|
||||
|
||||
Scanning each subscription additionally needs the permissions described in [Azure Authentication in Prowler](/user-guide/providers/azure/authentication#required-permissions):
|
||||
|
||||
| Permission | Scope | Used for |
|
||||
|------------|-------|----------|
|
||||
| **Reader** | Subscription, or inherited from the Management Group | Reading Azure resources during a scan. |
|
||||
| **ProwlerRole** | Subscription, or inherited from the Management Group | The read-only actions the Reader role does not cover. |
|
||||
| `AuditLog.Read.All`, `Directory.Read.All`, `Policy.Read.All` | Microsoft Entra ID (Microsoft Graph) | The Microsoft Entra ID checks. |
|
||||
|
||||
Role assignments made at the tenant root Management Group are inherited by every subscription beneath it, so assigning **Reader** and **ProwlerRole** there means every subscription you onboard is scannable without a per-subscription grant. To create the custom role, see [Assigning "ProwlerRole" Permissions at the Subscription Level](/user-guide/providers/azure/authentication#assigning-prowlerrole-permissions-at-the-subscription-level) — and set its `assignableScopes` to the Management Group, `/providers/Microsoft.Management/managementGroups/<tenant-id>`, rather than to a single subscription, so it can be assigned once for the whole tenant.
|
||||
|
||||
### Find Your Microsoft Entra Tenant ID
|
||||
|
||||
Prowler identifies the organization by the Microsoft Entra tenant ID, a Universally Unique Identifier (UUID):
|
||||
|
||||
```bash
|
||||
az account show --query tenantId -o tsv
|
||||
```
|
||||
|
||||
In the Azure portal, the same value sits on your service principal's **App registrations** > **Overview** blade as **Directory (tenant) ID**, next to the **Application (client) ID** the wizard also asks for. [Adding Azure credentials to Prowler Cloud](/user-guide/providers/azure/getting-started-azure#step-3-add-credentials-to-prowler-cloud) shows both on the annotated blade.
|
||||
|
||||
## Step 1: Start the Organization Wizard
|
||||
|
||||
### Open the Wizard
|
||||
|
||||
1. Navigate to **Providers** and click **Add Provider**.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/cloud-providers-add.png" alt="Providers page showing the Add Provider button" />
|
||||
</Frame>
|
||||
|
||||
2. Select **Microsoft Azure** as the provider.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/select-azure-provider.png" alt="Provider selection modal with Microsoft Azure highlighted" />
|
||||
</Frame>
|
||||
|
||||
3. Choose **Add Multiple Subscriptions With Azure Management Group**.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/select-azure-management-groups-method.png" alt="Method selector showing the Add Multiple Subscriptions With Azure Management Group option highlighted" />
|
||||
</Frame>
|
||||
|
||||
<Note>
|
||||
In Prowler Local Server the Management Group option is marked **Cloud** and opens an upgrade panel instead of the wizard. Management Group onboarding is a Prowler Cloud feature; the single-subscription method remains available.
|
||||
</Note>
|
||||
|
||||
### Enter Organization Details
|
||||
|
||||
- **Tenant ID**: the Microsoft Entra tenant ID (for example, `8b3c9a41-5f27-4d6e-9c18-7ae204f5b6d2`). Values that are not valid UUIDs are rejected before submission.
|
||||
- **Name** (optional): a display name for the organization in Prowler. If left blank, Prowler uses the tenant ID.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/azure-organization-details-form.png" alt="Organization Details form with the Microsoft Entra tenant ID and Name fields" />
|
||||
</Frame>
|
||||
|
||||
Click **Next** to proceed to the authentication phase. Prowler matches the organization by tenant ID, so submitting a tenant that is already onboarded reuses it instead of creating a duplicate.
|
||||
|
||||
## Step 2: Authenticate With Azure
|
||||
|
||||
The **Authentication Details** step collects the service principal Prowler uses to read the Management Group hierarchy and, later, to scan each subscription:
|
||||
|
||||
- **Client ID**: the application (client) ID of the service principal, a UUID.
|
||||
- **Client Secret**: a client secret of that service principal.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/azure-authentication-details.png" alt="Authentication Details step showing the Client ID and Client Secret fields" />
|
||||
</Frame>
|
||||
|
||||
The tenant is not repeated here: Prowler takes it from the organization created in the previous step.
|
||||
|
||||
<Warning>
|
||||
Every subscription you onboard inherits this credential. Revoking it, rotating the client secret, or deleting the service principal stops the scans of every subscription in the organization.
|
||||
</Warning>
|
||||
|
||||
### Authenticate and Discover
|
||||
|
||||
Click **Authenticate**. Prowler then:
|
||||
|
||||
- Creates the organization and stores the credential securely.
|
||||
- Triggers an asynchronous discovery that walks the Management Group hierarchy.
|
||||
- Shows a **"Gathering Azure Subscriptions..."** spinner while it waits.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/azure-gathering-subscriptions.png" alt="Gathering Azure Subscriptions spinner shown while discovery runs" />
|
||||
</Frame>
|
||||
|
||||
Discovery usually takes seconds to a couple of minutes, depending on how many Management Groups and subscriptions the tenant holds.
|
||||
|
||||
#### When Discovery Takes Too Long
|
||||
|
||||
Prowler waits up to **3 minutes** for a result. Past that, the wizard stops waiting — but the discovery keeps running in Azure — and offers two actions:
|
||||
|
||||
- **Keep waiting** — resume the same discovery. Nothing is re-read from Azure.
|
||||
- **Retry** — start a fresh discovery, which reads the hierarchy again.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/azure-discovery-timeout.png" alt="Discovery timeout notice offering Keep waiting and Retry" />
|
||||
</Frame>
|
||||
|
||||
If discovery fails outright, the wizard explains why and offers **Retry discovery**. See [Troubleshooting](#troubleshooting) for each message.
|
||||
|
||||
## Step 3: Select Subscriptions to Scan
|
||||
|
||||
### Understanding the Tree View
|
||||
|
||||
Once discovery completes, the wizard renders the tenant as a hierarchical tree:
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/azure-tree-view-subscriptions.png" alt="Hierarchical tree view showing Management Groups and subscriptions with selection checkboxes" />
|
||||
</Frame>
|
||||
|
||||
- **Management Groups** nest under the tenant root; subscriptions that sit directly under the tenant root appear at the top level. The tenant root itself is not shown as a row — the whole tree is its content.
|
||||
- Each Management Group row shows its Management Group name, with the Azure display name beside it. Hover the name to read the full Azure Resource Manager (ARM) resource identifier.
|
||||
- **Selecting a Management Group** selects every selectable subscription beneath it. A Management Group whose subscriptions are only partly selected renders in an indeterminate state.
|
||||
- **Individual overrides**: deselect single subscriptions even when the parent Management Group is selected.
|
||||
- The header tracks the selection as **"X of Y subscriptions selected"**.
|
||||
- Management Group hierarchies are read up to **six levels** below the tenant root Management Group, which is Azure's own platform limit. Deeper tenants report an error at discovery — see [Troubleshooting](#troubleshooting).
|
||||
|
||||
### Blocked Subscriptions
|
||||
|
||||
A subscription is shown grayed out and cannot be selected when Azure reports it as inactive, or when onboarding it would conflict with something Prowler already stores. Hover the subscription to see the reason:
|
||||
|
||||
| Reason | What it means |
|
||||
|--------|---------------|
|
||||
| `subscription_not_enabled` | The subscription is not in the **Enabled** state in Azure — it is disabled, expired, or otherwise inactive. Nothing in Prowler conflicts with it: resolve whatever Azure reports against the subscription, billing included, then run discovery again. |
|
||||
| `organization_conflict` | The subscription is already connected under a **different** Prowler organization. |
|
||||
| `organization_node_conflict` | The subscription is already grouped under a different Management Group in Prowler — for example, it moved in Azure after it was onboarded. |
|
||||
| `provider_type_conflict` | A provider with the same identifier exists in Prowler for another cloud provider. |
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/azure-blocked-subscription.png" alt="Blocked subscription row with the reason shown in a tooltip" />
|
||||
</Frame>
|
||||
|
||||
### Management Groups With Nothing to Select
|
||||
|
||||
A Management Group that holds no subscriptions, or whose subscriptions are all blocked, is shown disabled with the note *"No subscriptions available to select in this management group."* The Management Group still expands, so you can see the blocked subscriptions it holds and why they are blocked.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/azure-inert-group.png" alt="Disabled Management Group row noting that no subscriptions are available to select" />
|
||||
</Frame>
|
||||
|
||||
### Custom Aliases
|
||||
|
||||
Each subscription row carries an editable name, prefilled with the subscription's display name. The alias is used only inside Prowler — it does not rename anything in Azure. Management Group names are read-only: Prowler stores the display name from Azure.
|
||||
|
||||
### Subscriptions That Already Have Credentials
|
||||
|
||||
Applying your selection stores the organization credential on every selected subscription. When a selected subscription is already connected to Prowler with its own credential, that credential is **overwritten** — so the wizard asks first, naming the affected subscriptions:
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/azure-replace-credentials-apply.png" alt="Replace existing credentials modal listing the subscriptions whose credentials will be replaced" />
|
||||
</Frame>
|
||||
|
||||
Click **Replace and continue** to proceed, or **Cancel** to adjust your selection.
|
||||
|
||||
<Note>
|
||||
**Your existing data is safe.** A subscription already connected as an individual provider is **linked** to the organization, never duplicated: its historical scans and findings are preserved, and it does not count twice toward your subscription.
|
||||
</Note>
|
||||
|
||||
## Step 4: Test Connections
|
||||
|
||||
Click **Test Connections** to verify that Prowler can authenticate against each selected subscription. Prowler creates one provider per subscription — identified by its Azure subscription ID — and then tests every connection.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/azure-test-connections.png" alt="Connection testing in progress with status icons on each subscription" />
|
||||
</Frame>
|
||||
|
||||
Each subscription shows a real-time status indicator:
|
||||
|
||||
- **Spinner** — test in progress
|
||||
- **Green checkmark (✓)** — connection successful
|
||||
- **Red icon (✗)** — connection failed (hover to see the error)
|
||||
|
||||
If every subscription connects successfully, you advance to the next step automatically.
|
||||
|
||||
### When Some Tests Fail
|
||||
|
||||
An error banner appears: **"There was a problem connecting to some subscriptions. Hover each subscription to check the error."** You have two options:
|
||||
|
||||
**a) Fix and retry:**
|
||||
|
||||
1. Confirm the service principal holds **Reader** and **ProwlerRole** on the failing subscriptions, or on a Management Group above them.
|
||||
2. Confirm the Microsoft Graph permissions have been granted admin consent, as described in [Azure Authentication in Prowler](/user-guide/providers/azure/authentication#assigning-required-api-permissions).
|
||||
3. Click **Test Connections** again — only the **failed subscriptions are re-tested**. Subscriptions that already passed are not tested again.
|
||||
|
||||
**b) Skip and continue:**
|
||||
|
||||
Click **Skip Connection Validation** to proceed with the subscriptions that connected successfully. Failed subscriptions stay onboarded and visible on the Providers page, but they are not scanned. This option appears only when at least one subscription connected.
|
||||
|
||||
If **no subscription** connects, the banner instead reads *"No subscriptions connected successfully. Fix the connection errors and retry before launching scans."* and you cannot proceed. Fix the underlying problem — see [Troubleshooting](#troubleshooting) — and retry.
|
||||
|
||||
## Step 5: Launch Scans
|
||||
|
||||
The Organizations wizard uses the same schedule controls described in [Scan Scheduling](/user-guide/tutorials/prowler-scan-scheduling#schedule-options).
|
||||
|
||||
Click **Save**, **Save and launch scan**, or **Launch scan**, depending on the selected schedule option. A toast notification confirms whether the schedule was saved, scans were launched, or both, and links to the **Scans** page. Prowler then redirects to the **Providers** page. Scans launch only for subscriptions that passed connection testing.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/azure-launch-scan.png" alt="Launch Scan step showing the Subscriptions Connected confirmation and the scan schedule selector" />
|
||||
</Frame>
|
||||
|
||||
After launching:
|
||||
|
||||
- Scans appear on the **Scans** page as they start and complete.
|
||||
- Results populate the **Overview** and **Findings** pages.
|
||||
- On the **Providers** page, your subscriptions are grouped under the organization and, when they live in a Management Group, under that Management Group.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/azure-providers-grouping.png" alt="Providers page showing subscriptions grouped under Azure Management Groups and the organization" />
|
||||
</Frame>
|
||||
|
||||
## Manage Your Organization After Onboarding
|
||||
|
||||
Open the row actions menu on the organization row on the **Providers** page.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/azure-organization-row-actions.png" alt="Row actions menu on an Azure organization row" />
|
||||
</Frame>
|
||||
|
||||
| Action | What it does |
|
||||
|--------|--------------|
|
||||
| **Edit Organization Name** | Renames the organization in Prowler. Leave it blank to fall back to the tenant ID. |
|
||||
| **Update Credentials** | Reopens the Authentication Details step to store a new service principal credential. |
|
||||
| **Edit Scan Schedule** | Applies one schedule to every connected subscription in the organization. |
|
||||
| **Test Connections (N)** | Re-tests every subscription in the organization. |
|
||||
| **Delete Organization** | Deletes the organization and cascades to its providers. |
|
||||
|
||||
### Onboard Subscriptions Created Later
|
||||
|
||||
Subscriptions added to the tenant after onboarding are not picked up automatically. Run the wizard again with the same tenant ID: discovery returns the current hierarchy, already-connected subscriptions come back preselected, and the new ones are ready to select.
|
||||
|
||||
### Update Organization Credentials
|
||||
|
||||
Choosing **Update Credentials** re-enters the Authentication Details step. Because the organization already holds a credential, Prowler warns before overwriting it and names how many providers re-authenticate with the new one:
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/azure-replace-credentials-setup.png" alt="Replace existing credentials modal showing how many providers re-authenticate" />
|
||||
</Frame>
|
||||
|
||||
Storing a new credential runs a fresh discovery, so any discovery already in progress is discarded — discovery authenticates with the credential it started from.
|
||||
|
||||
### Delete an Organization or Management Group
|
||||
|
||||
Deleting an organization or a Management Group **cascades to every provider grouped under it**, along with their scans and findings. Both dialogs state how many providers are affected before you confirm.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/azure/azure-delete-organization.png" alt="Delete organization dialog showing how many providers are deleted with it" />
|
||||
</Frame>
|
||||
|
||||
Deletion runs in the background. Prowler confirms with a **"Deletion started"** notification; if any part of it fails, the affected rows reappear on a later refresh.
|
||||
|
||||
<Danger>
|
||||
Deleting an organization **permanently deletes every subscription provider grouped under it**, including their historical scans and findings. This action cannot be undone.
|
||||
</Danger>
|
||||
|
||||
### When Grouping Is Unavailable
|
||||
|
||||
If Prowler cannot read the hierarchy while loading the Providers page, a notice reads *"Organization grouping is incomplete. Some providers may appear ungrouped."* Your providers are still listed, just flat. Reload the page to try again.
|
||||
|
||||
## Billing Impact
|
||||
|
||||
Each Azure subscription you connect through the Organizations wizard counts as one **provider** in your Prowler Cloud subscription.
|
||||
|
||||
- **Already-connected subscriptions**: linking an existing provider to the organization does **not** add billing. The existing provider is reused.
|
||||
- **Large tenants**: connecting a 500-subscription tenant results in up to 500 providers on your subscription. Review your plan limits before proceeding.
|
||||
- **Deleted providers**: a subscription you later remove no longer counts toward your subscription.
|
||||
|
||||
For pricing details, see [Prowler Cloud Pricing](https://prowler.com/pricing).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Those Service Principal Credentials Were Rejected
|
||||
|
||||
*"Those service principal credentials were rejected. Check the client ID and client secret, then try again."*
|
||||
|
||||
Azure refused the sign-in. Confirm the client ID belongs to the service principal you granted access to, and that the client secret is current — secrets expire, and a rotated one invalidates the old value immediately.
|
||||
|
||||
```bash
|
||||
az ad app credential list --id <client-id> --query "[].{name:displayName, expires:endDateTime}" -o table
|
||||
```
|
||||
|
||||
### The Service Principal Cannot Read the Complete Management Group Hierarchy
|
||||
|
||||
*"The service principal cannot read the complete Management Group hierarchy. Grant it the Reader role at the Management Group level, then try again."*
|
||||
|
||||
The credential authenticated but lacks read access to part of the hierarchy. Grant **Reader** at the tenant root Management Group, as described in [Grant Read Access at the Tenant Root Management Group](#grant-read-access-at-the-tenant-root-management-group), and confirm the assignment landed on the Management Group and not on a single subscription:
|
||||
|
||||
```bash
|
||||
az role assignment list \
|
||||
--assignee <client-id> \
|
||||
--scope "/providers/Microsoft.Management/managementGroups/<tenant-id>" \
|
||||
--query "[].{role:roleDefinitionName, scope:scope}" -o table
|
||||
```
|
||||
|
||||
### Azure Returned an Incomplete Management Group Hierarchy
|
||||
|
||||
*"Azure returned an incomplete Management Group hierarchy. This usually clears on a retry; if it does not, check that the service principal can read every Management Group in the tenant."*
|
||||
|
||||
Azure answered, but the hierarchy it returned was missing Management Groups that Prowler expected to find. This is usually a transient inconsistency in Azure Resource Manager, so click **Retry discovery** first.
|
||||
|
||||
If it repeats, treat it as a permissions problem. Unlike the error above, Azure did not refuse the read — a partial grant can surface as missing data rather than as an outright denial. Confirm that the **Reader** assignment sits on the tenant root Management Group and not on individual Management Groups beneath it, using the command in [The Service Principal Cannot Read the Complete Management Group Hierarchy](#the-service-principal-cannot-read-the-complete-management-group-hierarchy).
|
||||
|
||||
### The Tenant Root Management Group Could Not Be Found
|
||||
|
||||
*"The tenant root Management Group could not be found. Check the tenant ID, and that the service principal has been granted access at the tenant root."*
|
||||
|
||||
Prowler derives the tenant root Management Group from the tenant ID you entered, and could not read it. Either the tenant ID is wrong, or the service principal cannot see the root. Confirm the tenant ID and list what the credential can reach:
|
||||
|
||||
```bash
|
||||
az account management-group list --query "[].{name:name, displayName:displayName}" -o table
|
||||
```
|
||||
|
||||
### Those Credentials Belong to a Different Microsoft Entra Tenant
|
||||
|
||||
*"Those credentials belong to a different Microsoft Entra tenant. Use a service principal from the tenant you entered."*
|
||||
|
||||
The service principal is registered in another tenant. Register the application in the tenant being onboarded, or correct the tenant ID in the first step of the wizard.
|
||||
|
||||
### Azure Did Not Respond
|
||||
|
||||
*"Azure did not respond while reading the Management Group hierarchy. Nothing is wrong with your credentials — try again in a few minutes."*
|
||||
|
||||
A transient Azure Resource Manager error. Click **Retry discovery**.
|
||||
|
||||
### Azure Rate Limited the Hierarchy Read
|
||||
|
||||
*"Azure rate limited the hierarchy read. Nothing is wrong with your credentials — try again in a few minutes."*
|
||||
|
||||
Azure Resource Manager throttled Prowler's requests while it walked the hierarchy. Large tenants and back-to-back discoveries are the common causes. Wait a few minutes, then click **Retry discovery**.
|
||||
|
||||
### The Hierarchy Is Too Deep
|
||||
|
||||
*"This tenant's Management Group hierarchy is deeper than Prowler can read. Contact support so we can help you onboard it."*
|
||||
|
||||
The tenant nests Management Groups deeper than Prowler reads in one pass. Contact [Prowler Support](mailto:support@prowler.com).
|
||||
|
||||
### Authentication Failed
|
||||
|
||||
*"Authentication failed. Please verify the service principal permissions or credentials, then try again."*
|
||||
|
||||
The generic authentication failure, shown when Azure reports no more specific reason. Confirm that the service principal still exists, that its client secret has not expired, and that the Reader role assignment at the tenant root Management Group is still in place.
|
||||
|
||||
### Azure Rejected the Hierarchy Read
|
||||
|
||||
*"Azure rejected the hierarchy read. Try again, and contact support if it keeps failing."*
|
||||
|
||||
Azure refused the request for a reason Prowler could not narrow down to credentials, permissions, or throttling. Click **Retry discovery**, and contact [Prowler Support](mailto:support@prowler.com) if the failure repeats. This message names Azure as the source of the failure; the one below is shown when the failure cannot be attributed to Azure at all.
|
||||
|
||||
### Discovery Could Not Be Completed
|
||||
|
||||
*"Discovery could not be completed. Try again, and contact support if it keeps failing."*
|
||||
|
||||
Discovery failed for a reason Prowler cannot attribute to the credential or to Azure. Click **Retry discovery**, and contact [Prowler Support](mailto:support@prowler.com) if the failure repeats.
|
||||
|
||||
### Discovery Never Finishes
|
||||
|
||||
The wizard stops waiting after 3 minutes, but the discovery keeps running in Azure. Click **Keep waiting** to resume the same discovery rather than **Retry**, which starts over and re-reads the whole hierarchy.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### How Subscriptions Map to Prowler Providers
|
||||
|
||||
Each selected subscription becomes one Prowler provider:
|
||||
|
||||
| Prowler field | Comes from |
|
||||
|---------------|------------|
|
||||
| Provider identifier | The Azure subscription ID (for example, `22222222-2222-4222-8222-222222222222`). |
|
||||
| Alias | The name you typed in the tree, or the subscription's display name. |
|
||||
| Credential | A copy of the organization credential. |
|
||||
|
||||
Management Groups that hold selected subscriptions become grouping rows on the Providers page. You select subscriptions only — Prowler derives the Management Group ancestors itself.
|
||||
|
||||
### Organization Credential vs Subscription Credential
|
||||
|
||||
One credential, stored twice: on the organization, where discovery reads it, and on each subscription provider, where scans read it. That is why replacing the organization credential re-authenticates every subscription under it, and why the wizard asks before overwriting a subscription's own credential.
|
||||
|
||||
## What's Next
|
||||
|
||||
<Columns cols={2}>
|
||||
<Card title="Prowler Cloud" icon="cloud" href="/user-guide/tutorials/prowler-app">
|
||||
Full guide to using Prowler Cloud features.
|
||||
</Card>
|
||||
<Card title="Azure Subscriptions (CLI)" icon="terminal" href="/user-guide/providers/azure/subscriptions">
|
||||
CLI-based scanning of specific Azure subscriptions.
|
||||
</Card>
|
||||
<Card title="Azure Authentication" icon="key" href="/user-guide/providers/azure/authentication">
|
||||
Credential types and the permissions Prowler needs in Azure.
|
||||
</Card>
|
||||
<Card title="Bulk Provider Provisioning" icon="upload" href="/user-guide/tutorials/bulk-provider-provisioning">
|
||||
Script-based bulk provisioning for advanced automation.
|
||||
</Card>
|
||||
</Columns>
|
||||
@@ -120,7 +120,7 @@ In Prowler Local Server the organization option is marked **Cloud** and opens an
|
||||
### Enter Organization Details
|
||||
|
||||
- **Organization ID**: the numeric ID of your Google Cloud organization (for example, `123456789012`). Non-numeric values are rejected before submission.
|
||||
- **Name** (optional): a display name for the organization in Prowler. If left blank, Prowler uses the name stored in Google Cloud.
|
||||
- **Name** (optional): a display name for the organization in Prowler. If left blank, Prowler uses the organization ID.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/gcp/gcp-organization-details-form.png" alt="Organization Details form with the Google Cloud organization ID and Name fields" />
|
||||
@@ -307,7 +307,7 @@ Open the row actions menu on the organization row on the **Providers** page.
|
||||
|
||||
| Action | What it does |
|
||||
|--------|--------------|
|
||||
| **Edit Organization Name** | Renames the organization in Prowler. Leave it blank to fall back to the name stored in Google Cloud. |
|
||||
| **Edit Organization Name** | Renames the organization in Prowler. Leave it blank to fall back to the organization ID. |
|
||||
| **Update Credentials** | Reopens the Authentication Details step to store a new credential. |
|
||||
| **Edit Scan Schedule** | Applies one schedule to every connected project in the organization. |
|
||||
| **Test Connections (N)** | Re-tests every project in the organization. |
|
||||
|
||||
Reference in new issue
Block a user