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(azure): refactor getting started and auth (#8754)

Browse Source 
Co-authored-by: Rubén De la Torre Vico <ruben@prowler.com>
This commit is contained in:
Andoni Alonso
2025-09-26 15:02:57 +02:00
committed by GitHub
parent 48d3fb4fe3
commit 23e1cc281d
4 changed files with 360 additions and 352 deletions
Download Patch File Download Diff File Expand all files Collapse all files

290
docs/tutorials/azure/authentication.md
View File

@@ -1,70 +1,229 @@
# Azure Authentication in Prowler
Prowler for Azure supports multiple authentication types. To use a specific method, pass the appropriate flag during execution:
Prowler for Azure supports multiple authentication types. Authentication methods vary between Prowler App and Prowler CLI:
- [**Service Principal Application**](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals?tabs=browser#service-principal-object) (**Recommended**)
- Existing **AZ CLI credentials**
- **Interactive browser authentication**
- [**Managed Identity**](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview) authentication
**Prowler App:**
> ⚠️ **Important:** For Prowler App, only Service Principal authentication is supported.
- [**Service Principal Application**](#service-principal-application-authentication-recommended)
### Service Principal Application Authentication
**Prowler CLI:**
Enable Prowler authentication using a Service Principal Application by setting up the following environment variables:
- [**Service Principal Application**](#service-principal-application-authentication-recommended) (**Recommended**)
- [**AZ CLI credentials**](#az-cli-authentication)
- [**Interactive browser authentication**](#browser-authentication)
- [**Managed Identity Authentication**](#managed-identity-authentication)
```console
export AZURE_CLIENT_ID="XXXXXXXXX"
export AZURE_TENANT_ID="XXXXXXXXX"
export AZURE_CLIENT_SECRET="XXXXXXX"
```
Execution with the `--sp-env-auth` flag fails if these variables are not set or exported.
Refer to the [Create Prowler Service Principal](create-prowler-service-principal.md) guide for detailed setup instructions.
### Azure Authentication Methods
Prowler for Azure supports the following authentication methods:
- **AZ CLI Authentication (`--az-cli-auth`)** – Automated authentication using stored AZ CLI credentials.
- **Managed Identity Authentication (`--managed-identity-auth`)** – Automated authentication via Azure Managed Identity.
- **Browser Authentication (`--browser-auth`)** – Requires the user to authenticate using the default browser. The `tenant-id` parameter is mandatory for this method.
### Required Permissions
## Required Permissions
Prowler for Azure requires two types of permission scopes:
#### Microsoft Entra ID Permissions
### Microsoft Entra ID Permissions
These permissions allow Prowler to retrieve metadata from the assumed identity and perform specific Entra checks. While not mandatory for execution, they enhance functionality.
Required permissions:
#### Assigning Required API Permissions
Assign the following Microsoft Graph permissions:
- `Directory.Read.All`
- `Policy.Read.All`
- `UserAuthenticationMethod.Read.All` (used for Entra multifactor authentication checks)
- `UserAuthenticationMethod.Read.All` (optional, for multifactor authentication (MFA) checks)
???+ note
Replace `Directory.Read.All` with `Domain.Read.All` for more restrictive permissions. Note that Entra checks related to DirectoryRoles and GetUsers will not run with this permission.
???+ note
Replace `Directory.Read.All` with `Domain.Read.All` for more restrictive permissions. Note that Entra checks related to DirectoryRoles and GetUsers will not run with this permission.
=== "Azure Portal"
1. Go to your App Registration > "API permissions"
![API Permission Page](./img/api-permissions-page.png)
2. Click "+ Add a permission" > "Microsoft Graph" > "Application permissions"
![Add API Permission](./img/add-api-permission.png)
![Microsoft Graph Detail](./img/microsoft-graph-detail.png)
3. Search and select:
- `Directory.Read.All`
- `Policy.Read.All`
- `UserAuthenticationMethod.Read.All`
![Permission Screenshots](./img/domain-permission.png)
4. Click "Add permissions", then grant admin consent
![Grant Admin Consent](./img/grant-admin-consent.png)
=== "Azure CLI"
1. To grant permissions to a Service Principal, execute the following command in a terminal:
```console
az ad app permission add --id {appId} --api 00000003-0000-0000-c000-000000000000 --api-permissions 7ab1d382-f21e-4acd-a863-ba3e13f7da61=Role 246dd0d5-5bd0-4def-940b-0421030a5b68=Role 38d9df27-64da-44fd-b7c5-a6fbac20248f=Role
```
2. Once the permissions are assigned, admin consent is required to finalize the changes. An administrator should run:
```console
az ad app permission admin-consent --id {appId}
```
#### Subscription Scope Permissions
### Subscription Scope Permissions
These permissions are required to perform security checks against Azure resources. The following **RBAC roles** must be assigned per subscription to the entity used by Prowler:
- `Reader` – Grants read-only access to Azure resources.
- `ProwlerRole` – A custom role with minimal permissions, defined in the [prowler-azure-custom-role](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-azure-custom-role.json).
- `ProwlerRole` – A custom role with minimal permissions needed for some specific checks, defined in the [prowler-azure-custom-role](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-azure-custom-role.json).
???+ note
The `assignableScopes` field in the JSON custom role file must be updated to reflect the correct subscription or management group. Use one of the following formats: `/subscriptions/<subscription-id>` or `/providers/Microsoft.Management/managementGroups/<management-group-id>`.
### Assigning Permissions
#### Assigning "Reader" Role at the Subscription Level
By default, Prowler scans all accessible subscriptions. If you need to audit specific subscriptions, you must assign the necessary role `Reader` for each one. For streamlined and less repetitive role assignments in multi-subscription environments, refer to the [following section](subscriptions.md#recommendation-for-managing-multiple-subscriptions).
To properly configure permissions, follow these guides:
=== "Azure Portal"
1. To grant Prowler access to scan a specific Azure subscription, follow these steps in Azure Portal:
Navigate to the subscription you want to audit with Prowler.
1. In the left menu, select “Access control (IAM)”.
2. Click “+ Add” and select “Add role assignment”.
3. In the search bar, enter `Reader`, select it and click “Next”.
4. In the “Members” tab, click “+ Select members”, then add the accounts to assign this role.
5. Click “Review + assign” to finalize and apply the role assignment.
![Adding the Reader Role to a Subscription](../../img/add-reader-role.gif)
=== "Azure CLI"
1. Open a terminal and execute the following command to assign the `Reader` role to the identity that is going to be assumed by Prowler:
```console
az role assignment create --role "Reader" --assignee <user, group, or service principal> --scope /subscriptions/<subscription-id>
```
2. If the command is executed successfully, the output is going to be similar to the following:
```json
{
"condition": null,
"conditionVersion": null,
"createdBy": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"createdOn": "YYYY-MM-DDTHH:MM:SS.SSSSSS+00:00",
"delegatedManagedIdentityResourceId": null,
"description": null,
"id": "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/providers/Microsoft.Authorization/roleAssignments/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"name": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"principalId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"principalName": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"principalType": "ServicePrincipal",
"roleDefinitionId": "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/providers/Microsoft.Authorization/roleDefinitions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"roleDefinitionName": "Reader",
"scope": "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"type": "Microsoft.Authorization/roleAssignments",
"updatedBy": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"updatedOn": "YYYY-MM-DDTHH:MM:SS.SSSSSS+00:00"
}
```
#### Assigning "ProwlerRole" Permissions at the Subscription Level
Some read-only permissions required for specific security checks are not included in the built-in Reader role. To support these checks, Prowler utilizes a custom role, defined in [prowler-azure-custom-role](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-azure-custom-role.json). Once created, this role can be assigned following the same process as the `Reader` role.
The checks requiring this `ProwlerRole` can be found in this [section](../../tutorials/azure/authentication.md#checks-requiring-prowlerrole).
=== "Azure Portal"
1. Download the [Prowler Azure Custom Role](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-azure-custom-role.json)
![Azure Custom Role](./img/download-prowler-role.png)
2. Modify `assignableScopes` to match your Subscription ID (e.g. `/subscriptions/xxxx-xxxx-xxxx-xxxx`)
3. Go to your Azure Subscription > "Access control (IAM)"
![IAM Page](./img/iam-azure-page.png)
4. Click "+ Add" > "Add custom role", choose "Start from JSON" and upload the modified file
![Add custom role via JSON](./img/add-custom-role-json.png)
5. Click "Review + Create" to finish
![Select review and create](./img/review-and-create.png)
6. Return to "Access control (IAM)" > "+ Add" > "Add role assignment"
- Assign the `Reader` role to the Application created in the previous step
- Then repeat the same process assigning the custom `ProwlerRole`
![Role Assignment](./img/add-role-assigment.png)
???+ note
The `assignableScopes` field in the JSON custom role file must be updated to reflect the correct subscription or management group. Use one of the following formats: `/subscriptions/<subscription-id>` or `/providers/Microsoft.Management/managementGroups/<management-group-id>`.
=== "Azure CLI"
1. To create a new custom role, open a terminal and execute the following command:
```console
az role definition create --role-definition '{ 640ms  lun 16 dic 17:04:17 2024
"Name": "ProwlerRole",
"IsCustom": true,
"Description": "Role used for checks that require read-only access to Azure resources and are not covered by the Reader role.",
"AssignableScopes": [
"/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" // USE YOUR SUBSCRIPTION ID
],
"Actions": [
"Microsoft.Web/sites/host/listkeys/action",
"Microsoft.Web/sites/config/list/Action"
]
}'
```
2. If the command is executed successfully, the output is going to be similar to the following:
```json
{
"assignableScopes": [
"/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
],
"createdBy": null,
"createdOn": "YYYY-MM-DDTHH:MM:SS.SSSSSS+00:00",
"description": "Role used for checks that require read-only access to Azure resources and are not covered by the Reader role.",
"id": "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/providers/Microsoft.Authorization/roleDefinitions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"name": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"permissions": [
{
"actions": [
"Microsoft.Web/sites/host/listkeys/action",
"Microsoft.Web/sites/config/list/Action"
],
"condition": null,
"conditionVersion": null,
"dataActions": [],
"notActions": [],
"notDataActions": []
}
],
"roleName": "ProwlerRole",
"roleType": "CustomRole",
"type": "Microsoft.Authorization/roleDefinitions",
"updatedBy": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"updatedOn": "YYYY-MM-DDTHH:MM:SS.SSSSSS+00:00"
}
```
### Additional Resources
For more detailed guidance on subscription management and permissions:
- [Microsoft Entra ID permissions](create-prowler-service-principal.md#assigning-proper-permissions)
- [Azure subscription permissions](subscriptions.md)
- [Create Prowler Service Principal](create-prowler-service-principal.md)
???+ warning
Some permissions in `ProwlerRole` involve **write access**. If a `ReadOnly` lock is attached to certain resources, you may encounter errors, and findings for those checks will not be available.
@@ -75,3 +234,56 @@ The following security checks require the `ProwlerRole` permissions for executio
- `app_function_access_keys_configured`
- `app_function_ftps_deployment_disabled`
---
## Service Principal Application Authentication (Recommended)
This method is required for Prowler App and recommended for Prowler CLI.
### Creating the Service Principal
For more information, see [Creating Prowler Service Principal](create-prowler-service-principal.md).
### Environment Variables (CLI)
For Prowler CLI, set up the following environment variables:
```console
export AZURE_CLIENT_ID="XXXXXXXXX"
export AZURE_TENANT_ID="XXXXXXXXX"
export AZURE_CLIENT_SECRET="XXXXXXX"
```
Execution with the `--sp-env-auth` flag fails if these variables are not set or exported.
## AZ CLI Authentication
*Available only for Prowler CLI*
Use stored Azure CLI credentials:
```console
prowler azure --az-cli-auth
```
## Managed Identity Authentication
*Available only for Prowler CLI*
Authenticate via Azure Managed Identity (when running on Azure resources):
```console
prowler azure --managed-identity-auth
```
## Browser Authentication
*Available only for Prowler CLI*
Authenticate using the default browser:
```console
prowler azure --browser-auth --tenant-id <tenant-id>
```
> **Note:** The `tenant-id` parameter is mandatory for browser authentication.

96
docs/tutorials/azure/create-prowler-service-principal.md
View File

@@ -2,26 +2,39 @@
To enable Prowler to assume an identity for scanning with the required privileges, a Service Principal must be created. This Service Principal authenticates against Azure and retrieves necessary metadata for checks.
### Methods for Creating a Service Principal
Service Principal Applications can be created using either the Azure Portal or the Azure CLI.
## Creating a Service Principal via Azure Portal / Entra Admin Center
1. Access Microsoft Entra ID.
2. In the left menu bar, navigate to **"App registrations"**.
3. Click **"+ New registration"** in the menu bar to register a new application
4. Fill the **"Name"**, select the **"Supported account types"** and click **"Register"**. You will be redirected to the applications page.
5. In the left menu bar, select **"Certificates & secrets"**.
6. Under the **"Certificates & secrets"** view, click **"+ New client secret"**.
7. Fill the **"Description"** and **"Expires"** fields, then click **"Add"**.
8. Copy the secret value, as it will be used as `AZURE_CLIENT_SECRET` environment variable.
![Registering an Application in Azure CLI for Prowler](../img/create-sp.gif)
## From Azure CLI
## Creating a Service Principal via Azure Portal / Entra Admin Center
### Creating a Service Principal
1. Access **Microsoft Entra ID** in the [Azure Portal](https://portal.azure.com)
![Search Microsoft Entra ID](./img/search-microsoft-entra-id.png)
2. Navigate to "Manage" > "App registrations"
![App Registration nav](./img/app-registration-menu.png)
3. Click "+ New registration", complete the form, and click "Register"
![New Registration](./img/new-registration.png)
4. Go to "Certificates & secrets" > "+ New client secret"
![Certificate & Secrets nav](./img/certificates-and-secrets.png)
![New Client Secret](./img/new-client-secret.png)
5. Fill in the required fields and click "Add", then copy the generated value
| Value | Description |
|-------|-----------|
| Client ID | Application ID |
| Client Secret | Secret to Connect to the App |
| Tenant ID | Microsoft Entra Tenant ID |
## Creating a Service Principal from Azure CLI
To create a Service Principal using the Azure CLI, follow these steps:
@@ -46,55 +59,4 @@ To create a Service Principal using the Azure CLI, follow these steps:
## Assigning Proper Permissions
To allow Prowler to retrieve metadata from the assumed identity and run Entra checks, assign the following permissions:
- `Directory.Read.All`
- `Policy.Read.All`
- `UserAuthenticationMethod.Read.All` (used only for the Entra checks related with multifactor authentication)
Permissions can be assigned via the Azure Portal or the Azure CLI.
???+ note
After creating and assigning the necessary Entra permissions, follow this [tutorial](../azure/subscriptions.md) to add subscription permissions to the application and start scanning your resources.
### Assigning the Reader Role in Azure Portal
1. Access Microsoft Entra ID.
2. In the left menu bar, navigate to “App registrations”.
3. Select the created application.
4. In the left menu bar, select “API permissions”.
5. Click “+ Add a permission” and select “Microsoft Graph”.
6. In the “Microsoft Graph” view, select “Application permissions”.
7. Finally, search for "Directory", "Policy" and "UserAuthenticationMethod" select the following permissions:
- `Directory.Read.All`
- `Policy.Read.All`
- `UserAuthenticationMethod.Read.All`
8. Click “Add permissions” to apply the new permissions.
9. Finally, an admin must click “Grant admin consent for \[your tenant]” to apply the permissions.
![Entra ID Permissions in Prowler](../../img/AAD-permissions.png)
### From Azure CLI
1. To grant permissions to a Service Principal, execute the following command in a terminal:
```console
az ad app permission add --id {appId} --api 00000003-0000-0000-c000-000000000000 --api-permissions 7ab1d382-f21e-4acd-a863-ba3e13f7da61=Role 246dd0d5-5bd0-4def-940b-0421030a5b68=Role 38d9df27-64da-44fd-b7c5-a6fbac20248f=Role
```
2. Once the permissions are assigned, admin consent is required to finalize the changes. An administrator should run:
```console
az ad app permission admin-consent --id {appId}
```
Go to [Assigning Proper Permissions](./authentication.md#required-permissions) to learn how to assign the necessary permissions to the Service Principal.

200
docs/tutorials/azure/getting-started-azure.md
View File

@@ -1,31 +1,23 @@
# Getting Started with Azure on Prowler Cloud/App
# Getting Started With Azure on Prowler
## Prowler App
<iframe width="560" height="380" src="https://www.youtube-nocookie.com/embed/v1as8vTFlMg" title="Prowler Cloud Onboarding Azure" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen="1"></iframe>
> Walkthrough video onboarding an Azure Subscription using Service Principal.
Set up your Azure subscription to enable security scanning using Prowler Cloud/App.
???+ note "Government Cloud Support"
Government cloud subscriptions (Azure Government) are not currently supported, but we expect to add support for them in the near future.
## Requirements
### Prerequisites
To configure your Azure subscription, you’ll need:
Before setting up Azure in Prowler App, you need to create a Service Principal with proper permissions.
1. Get the `Subscription ID`
2. Access to Prowler Cloud/App
3. Configure authentication in Azure:
3.1 Create a Service Principal
3.2 Assign required permissions
3.3 Assign permissions at the subscription level
4. Add the credentials to Prowler Cloud/App
For detailed instructions on how to create the Service Principal and configure permissions, see [Authentication > Service Principal](./authentication.md#service-principal-application-authentication-recommended).
---
## Step 1: Get the Subscription ID
### Step 1: Get the Subscription ID
1. Go to the [Azure Portal](https://portal.azure.com/#home) and search for `Subscriptions`
2. Locate and copy your Subscription ID
@@ -35,9 +27,9 @@ To configure your Azure subscription, you’ll need:
---
## Step 2: Access Prowler Cloud/App
### Step 2: Access Prowler App
1. Go to [Prowler Cloud](https://cloud.prowler.com/) or launch [Prowler App](../prowler-app.md)
1. Navigate to [Prowler Cloud](https://cloud.prowler.com/) or launch [Prowler App](../prowler-app.md)
2. Navigate to `Configuration` > `Cloud Providers`
![Cloud Providers Page](../img/cloud-providers-page.png)
@@ -54,117 +46,19 @@ To configure your Azure subscription, you’ll need:
![Add Subscription ID](./img/add-subscription-id.png)
---
### Step 3: Add Credentials to Prowler App
## Step 3: Configure the Azure Subscription
### Create the Service Principal
A Service Principal is required to grant Prowler the necessary privileges.
1. Access **Microsoft Entra ID**
![Search Microsoft Entra ID](./img/search-microsoft-entra-id.png)
2. Navigate to `Manage` > `App registrations`
![App Registration nav](./img/app-registration-menu.png)
3. Click `+ New registration`, complete the form, and click `Register`
![New Registration](./img/new-registration.png)
4. Go to `Certificates & secrets` > `+ New client secret`
![Certificate & Secrets nav](./img/certificates-and-secrets.png)
![New Client Secret](./img/new-client-secret.png)
5. Fill in the required fields and click `Add`, then copy the generated value
| Value | Description |
|-------|-------------|
| Client ID | Application ID |
| Client Secret | AZURE_CLIENT_SECRET |
| Tenant ID | Azure Active Directory tenant ID |
---
### Assign Required API Permissions
Assign the following Microsoft Graph permissions:
- Directory.Read.All
- Policy.Read.All
- UserAuthenticationMethod.Read.All (optional, for MFA checks)
???+ note
You can replace `Directory.Read.All` with `Domain.Read.All` that is a more restrictive permission but you won't be able to run the Entra checks related with DirectoryRoles and GetUsers.
1. Go to your App Registration > `API permissions`
![API Permission Page](./img/api-permissions-page.png)
2. Click `+ Add a permission` > `Microsoft Graph` > `Application permissions`
![Add API Permission](./img/add-api-permission.png)
![Microsoft Graph Detail](./img/microsoft-graph-detail.png)
3. Search and select:
- `Directory.Read.All`
- `Policy.Read.All`
- `UserAuthenticationMethod.Read.All`
![Permission Screenshots](./img/domain-permission.png)
4. Click `Add permissions`, then grant admin consent
![Grant Admin Consent](./img/grant-admin-consent.png)
---
### Assign Permissions at the Subscription Level
1. Download the [Prowler Azure Custom Role](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-azure-custom-role.json)
![Azure Custom Role](./img/download-prowler-role.png)
2. Modify `assignableScopes` to match your Subscription ID (e.g. `/subscriptions/xxxx-xxxx-xxxx-xxxx`)
3. Go to your Azure Subscription > `Access control (IAM)`
![IAM Page](./img/iam-azure-page.png)
4. Click `+ Add` > `Add custom role`, choose "Start from JSON" and upload the modified file
![Add custom role via JSON](./img/add-custom-role-json.png)
5. Click `Review + Create` to finish
![Select review and create](./img/review-and-create.png)
6. Return to `Access control (IAM)` > `+ Add` > `Add role assignment`
- Assign the `Reader` role to the Application created in the previous step
- Then repeat the same process assigning the custom `ProwlerRole`
![Role Assignment](./img/add-role-assigment.png)
---
## Step 4: Add Credentials to Prowler Cloud/App
Having completed the [Service Principal setup from the Authentication guide](./authentication.md#service-principal-application-authentication-recommended):
1. Go to your App Registration overview and copy the `Client ID` and `Tenant ID`
![App Overview](./img/app-overview.png)
2. Go to Prowler Cloud/App and paste:
2. Go to Prowler App and paste:
- `Client ID`
- `Tenant ID`
- `AZURE_CLIENT_SECRET` from earlier
- `Client Secret` from [earlier](./authentication.md#service-principal-application-authentication-recommended)
![Prowler Cloud Azure Credentials](./img/add-credentials-azure-prowler-cloud.png)
@@ -172,6 +66,70 @@ Assign the following Microsoft Graph permissions:
![Next Detail](./img/click-next-azure.png)
4. Click `Launch Scan`
4. Click "Launch Scan"
![Launch Scan Azure](./img/launch-scan.png)
---
## Prowler CLI
### Configure Azure Credentials
To authenticate with Azure, Prowler CLI supports multiple authentication methods. Choose the method that best suits your environment.
For detailed authentication setup instructions, see [Authentication](./authentication.md).
**Service Principal (Recommended)**
Set up environment variables:
```console
export AZURE_CLIENT_ID="XXXXXXXXX"
export AZURE_TENANT_ID="XXXXXXXXX"
export AZURE_CLIENT_SECRET="XXXXXXX"
```
Then run:
```console
prowler azure --sp-env-auth
```
**Azure CLI Credentials**
Use stored Azure CLI credentials:
```console
prowler azure --az-cli-auth
```
**Browser Authentication**
Authenticate using your default browser:
```console
prowler azure --browser-auth --tenant-id <tenant-id>
```
**Managed Identity**
When running on Azure resources:
```console
prowler azure --managed-identity-auth
```
### Subscription Selection
To scan a specific Azure subscription:
```console
prowler azure --subscription-ids <subscription-id>
```
To scan multiple Azure subscriptions:
```console
prowler azure --subscription-ids <subscription-id1> <subscription-id2> <subscription-id3>
```

126
docs/tutorials/azure/subscriptions.md
View File

@@ -18,131 +18,7 @@ Prowler allows you to specify one or more subscriptions for scanning (up to N),
The multi-subscription feature is available only in the CLI. In Prowler App, each scan is limited to a single subscription.
## Assigning Permissions for Subscription Scans
To perform scans, ensure that the identity assumed by Prowler has the appropriate permissions.
By default, Prowler scans all accessible subscriptions. If you need to audit specific subscriptions, you must assign the necessary role `Reader` for each one. For streamlined and less repetitive role assignments in multi-subscription environments, refer to the [following section](#recommendation-for-managing-multiple-subscriptions).
### Assigning the Reader Role in Azure Portal
1. To grant Prowler access to scan a specific Azure subscription, follow these steps in Azure Portal:
Navigate to the subscription you want to audit with Prowler.
2. In the left menu, select “Access control (IAM)”.
3. Click “+ Add” and select “Add role assignment”.
4. In the search bar, enter `Reader`, select it and click “Next”.
5. In the “Members” tab, click “+ Select members”, then add the accounts to assign this role.
6. Click “Review + assign” to finalize and apply the role assignment.
![Adding the Reader Role to a Subscription](../../img/add-reader-role.gif)
### From Azure CLI
1. Open a terminal and execute the following command to assign the `Reader` role to the identity that is going to be assumed by Prowler:
```console
az role assignment create --role "Reader" --assignee <user, group, or service principal> --scope /subscriptions/<subscription-id>
```
2. If the command is executed successfully, the output is going to be similar to the following:
```json
{
"condition": null,
"conditionVersion": null,
"createdBy": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"createdOn": "YYYY-MM-DDTHH:MM:SS.SSSSSS+00:00",
"delegatedManagedIdentityResourceId": null,
"description": null,
"id": "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/providers/Microsoft.Authorization/roleAssignments/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"name": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"principalId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"principalName": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"principalType": "ServicePrincipal",
"roleDefinitionId": "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/providers/Microsoft.Authorization/roleDefinitions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"roleDefinitionName": "Reader",
"scope": "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"type": "Microsoft.Authorization/roleAssignments",
"updatedBy": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"updatedOn": "YYYY-MM-DDTHH:MM:SS.SSSSSS+00:00"
}
```
### Prowler Custom Role
Some read-only permissions required for specific security checks are not included in the built-in Reader role. To support these checks, Prowler utilizes a custom role, defined in [prowler-azure-custom-role](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-azure-custom-role.json). Once created, this role can be assigned following the same process as the `Reader` role.
The checks requiring this `ProwlerRole` can be found in this [section](../../tutorials/azure/authentication.md#checks-requiring-prowlerrole).
#### Create ProwlerRole via Azure Portal
1. Download the [prowler-azure-custom-role](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-azure-custom-role.json) file and modify the `assignableScopes` field to match the target subscription. Example format: `/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`.
2. Access your Azure subscription.
3. Select “Access control (IAM)”.
4. Click “+ Add” and select “Add custom role”.
5. Under “Baseline permissions”, select “Start from JSON” and upload the modified role file.
6. Click “Review + create” to finalize the role creation.
#### Create ProwlerRole via Azure CLI
1. To create a new custom role, open a terminal and execute the following command:
```console
az role definition create --role-definition '{ 640ms  lun 16 dic 17:04:17 2024
"Name": "ProwlerRole",
"IsCustom": true,
"Description": "Role used for checks that require read-only access to Azure resources and are not covered by the Reader role.",
"AssignableScopes": [
"/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" // USE YOUR SUBSCRIPTION ID
],
"Actions": [
"Microsoft.Web/sites/host/listkeys/action",
"Microsoft.Web/sites/config/list/Action"
]
}'
```
2. If the command is executed successfully, the output is going to be similar to the following:
```json
{
"assignableScopes": [
"/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
],
"createdBy": null,
"createdOn": "YYYY-MM-DDTHH:MM:SS.SSSSSS+00:00",
"description": "Role used for checks that require read-only access to Azure resources and are not covered by the Reader role.",
"id": "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/providers/Microsoft.Authorization/roleDefinitions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"name": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"permissions": [
{
"actions": [
"Microsoft.Web/sites/host/listkeys/action",
"Microsoft.Web/sites/config/list/Action"
],
"condition": null,
"conditionVersion": null,
"dataActions": [],
"notActions": [],
"notDataActions": []
}
],
"roleName": "ProwlerRole",
"roleType": "CustomRole",
"type": "Microsoft.Authorization/roleDefinitions",
"updatedBy": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"updatedOn": "YYYY-MM-DDTHH:MM:SS.SSSSSS+00:00"
}
```
Check the [Authentication > Subscription Scope Permissions](authentication.md#subscription-scope-permissions) guide for more information on how to assign permissions for subscription scans.
## Recommendation for Managing Multiple Subscriptions