Quick Setup - Azure Management Group Continuous Scanning

The Mondoo Azure integration lets you continuously scan Azure resources, such as compute instances and databases, in an Azure management group.

You can also limit scanning one or more Azure subscriptions. For instructions, read Continuously Scan an Azure Subscription.

Prerequisites

Before you integrate Microsoft Azure with Mondoo, be sure you have:

A Mondoo account with Editor or Owner permissions for the space in which you want to add the integration.
An Azure account with an active subscription and permission to manage applications in Microsoft Entra ID (formerly Active Directory). Any of these Entra built-in roles include the required permissions:
In the Azure portal you can see what roles your user account has: Go to Microsoft Entra ID > Users > (your user account) > Assigned roles.
Command-line access to Azure using either:
- Azure Cloud Shell
- The Azure CLI in either the Linux shell or the macOS shell
  Install the Azure CLI.
  Log into the Azure CLI from PowerShell or a Linux/macOS CLI by entering:
  
  az login
  Azure opens your web browser and prompts you to log in. After you do so, you can return to the CLI.

Register and grant permissions to an Azure app

Like any service that integrates with Azure, Mondoo must have Microsoft Entra ID app registration in your Azure tenant. To learn more about creating a new app registration and service principal, read App registration, app objects, and service principals in the Azure documentation.

Registering Mondoo with Entra establishes a trust relationship between Mondoo and the Microsoft identity platform. The trust is unidirectional: Mondoo trusts the Microsoft identity platform, and not the other way around. The Entra app registration creates a service principal to represent Mondoo in any tenants and subscriptions.

The app registration you create gives Mondoo read-only access to Azure resources, web apps, key vault, and Graph API.

These instructions describe how to use Microsoft's "automatic" method of registering an Azure app. If you want to use your own certificates for authentication, if you use the key vault access policy permission model, or if your Azure environment is unusually large, follow the instructions in Manually Set up an Azure Integration instead.

To configure your Azure resources, you must:

Step A. Retrieve your management group ID

Step B. Create the app registration and certificate and grant READ access

Step C. Grant web app and key vault READ permissions to the registered app

Step D. Grant permissions to access Microsoft Graph (API permissions)

Step A: Retrieve your management group ID

If you want Mondoo to continuously scan all the resources in a management group, retrieve the group's ID in the Azure CLI:

Run this command:
```
az account management-group list
```
Copy the ID of the group you want and paste it somewhere handy to use in later steps.

Step B: Create the app, service principal, and certificate and grant READ access

A single command in the Azure CLI performs these tasks:

Creates the application registration and service principal in Microsoft Entra ID
Grants READ access (using RBAC) to the new application
Creates a certificate and assigns it to the newly created app

In the Azure CLI, enter:

az ad sp create-for-rbac --name mondoo-security --role Reader --scopes /providers/Microsoft.Management/managementGroups/YOUR-GROUP-ID --create-cert

For YOUR-GROUP-ID, substitute the management group ID value you copied in the step above. For example, this command creates a service principal and an application named mondoo-security that provides access to a management group with the ID e4e2600a-2d3d-2600-aa70-b9d8c8ec2600:

az ad sp create-for-rbac --name mondoo-security --role Reader --scopes /providers/Microsoft.Management/managementGroups/e4e2600a-2d3d-2600-aa70-b9d8c8ec2600 --create-cert

When successful, the Azure CLI returns results like these:

"appId": "63c35483-c62f-2600-a097-a6e44d8dcdf6",
"displayName": "Mondoo",
"fileWithCertAndPrivateKey": "/Users/stella/tmpkqyme3rm.pem",
"password": null,
"tenant": "e4e2600a-2d3d-2600-aa70-b9d8c8ec2600"

Copy your results and paste them somewhere handy; you'll need them in later steps.
Copy the created PEM file (in the example above, it's named tmpkqyme3rm.pem) and save it; you'll need it in later steps.

tip
In the Azure portal, you can make sure that the created application has the required READ access at the subscription level: Go to Azure portal > [your subscription] > Access control (IAM) > Roles (choose Reader and View) > Assessments. If you see the mondoo-security application, you've succeeded.

Step C: Grant web app and key vault READ permissions to the registered app

note

The Key Vault permissions below are based on Microsoft's "Key Vault Reader" role. The Microsoft documentation describes this role:

Read metadata of key vaults and its certificates, keys, and secrets. Cannot read sensitive values such as secret contents or key material. This role is only functional for key vaults that utilize the 'Azure role-based access control' permission model (RBAC).

To assign this role across all subscriptions under a management group, follow these steps, replacing YOUR-GROUP-ID with your actual management group ID:

Create the custom role definition.

Save this JSON content into a file named mondoo-role.json:

{
  "Name": "mondoo-role",
  "IsCustom": true,
  "description": "Custom role for Mondoo integration",
  "assignableScopes": ["/"],
  "actions": [
    "Microsoft.Authorization/*/read",
    "Microsoft.ResourceHealth/availabilityStatuses/read",
    "Microsoft.Insights/alertRules/*",
    "Microsoft.Resources/deployments/*",
    "Microsoft.Resources/subscriptions/resourceGroups/read",
    "Microsoft.Support/*",
    "Microsoft.Web/listSitesAssignedToHostName/read",
    "Microsoft.Web/serverFarms/read",
    "Microsoft.Web/sites/config/read",
    "Microsoft.Web/sites/config/web/appsettings/read",
    "Microsoft.Web/sites/config/web/connectionstrings/read",
    "Microsoft.Web/sites/config/appsettings/read",
    "Microsoft.web/sites/config/snapshots/read",
    "Microsoft.Web/sites/config/list/action",
    "Microsoft.Web/sites/read",
    "Microsoft.KeyVault/checkNameAvailability/read",
    "Microsoft.KeyVault/deletedVaults/read",
    "Microsoft.KeyVault/locations/*/read",
    "Microsoft.KeyVault/vaults/*/read",
    "Microsoft.KeyVault/operations/read",
    "Microsoft.Compute/virtualMachines/runCommands/read",
    "Microsoft.Compute/virtualMachines/runCommands/write",
    "Microsoft.Compute/virtualMachines/runCommand/action"
  ],
  "notActions": [],
  "dataActions": [
    "Microsoft.KeyVault/vaults/*/read",
    "Microsoft.KeyVault/vaults/secrets/readMetadata/action"
  ],
  "notDataActions": []
}

Create a custom role:

az role definition create --role-definition mondoo-role.json

Make sure you successfully created the role:

az role definition list --output json --query '[].{roleName:roleName, description:description}' --name "mondoo-role"

Check your permissions:

Confirm that your account has the required permissions to list subscriptions within the management group:
```
az account management-group subscription show-sub-under-mg --name "YOUR-GROUP-ID"
```
If you encounter authorization issues, grant the necessary permissions:
```
az role assignment create --assignee "YourAccountName@Domain.name" --role "Management Group Reader" --scope "/providers/Microsoft.Management/managementGroups/YOUR-GROUP-ID"
```
Replace YOUR-GROUP-ID with the actual ID of your management group. Then, re-execute the command to list subscriptions and confirm access.

Assign the custom role using a script:

Create a new file named assign_role_to_subscriptions.sh and paste this script in the file:

#!/bin/bash

MGMT_GROUP_ID="Mang-Group-ID"
PRINCIPAL_ID="APP-ID"

# List all subscriptions under the management group and read them line by line
SUBSCRIPTIONS=$(az account management-group subscription show-sub-under-mg --name "$MGMT_GROUP_ID" --query "[].name" -o tsv)

for SUBSCRIPTION_ID in $SUBSCRIPTIONS; do
    echo "Assigning 'mondoo-role' to subscription $SUBSCRIPTION_ID"
    # Set the context to the current subscription
    az account set --subscription "$SUBSCRIPTION_ID"
    # Assign the role to the principal for the current subscription
    az role assignment create --role "mondoo-role" --assignee $PRINCIPAL_ID --scope "/subscriptions/$SUBSCRIPTION_ID"
done

Be sure to replace YOUR-GROUP-ID with your management group ID and APP-ID with the principal ID.

Make the script executable:

chmod +x assign_role_to_subscriptions.sh

Run the script to assign this custom role to your app across all subscriptions under the management group:

./assign_role_to_subscriptions.sh

These steps ensure that the custom role is systematically assigned to all subscriptions within your specified management group.

Step D: Grant permissions to access Microsoft Graph (API permissions)

Copy this content and paste it into a new file on your local system named app-manifest.json:

[
  {
    "resourceAppId": "00000003-0000-0000-c000-000000000000",
    "resourceAccess": [
      {
        "id": "246dd0d5-5bd0-4def-940b-0421030a5b68",
        "type": "Role"
      },
      {
        "id": "e321f0bb-e7f7-481e-bb28-e3b0b32d4bd0",
        "type": "Role"
      },
      {
        "id": "5e0edab9-c148-49d0-b423-ac253e121825",
        "type": "Role"
      },
      {
        "id": "bf394140-e372-4bf9-a898-299cfc7564e5",
        "type": "Role"
      },
      {
        "id": "6e472fd1-ad78-48da-a0f0-97ab2c6b769e",
        "type": "Role"
      },
      {
        "id": "dc5007c0-2d7d-4c42-879c-2dab87571379",
        "type": "Role"
      },
      {
        "id": "b0afded3-3588-46d8-8b3d-9842eff778da",
        "type": "Role"
      },
      {
        "id": "7ab1d382-f21e-4acd-a863-ba3e13f7da61",
        "type": "Role"
      },
      {
        "id": "197ee4e9-b993-4066-898f-d6aecc55125b",
        "type": "Role"
      },
      {
        "id": "9a5d68dd-52b0-4cc2-bd40-abcf44ac3a30",
        "type": "Role"
      },
      {
        "id": "f8f035bb-2cce-47fb-8bf5-7baf3ecbee48",
        "type": "Role"
      },
      {
        "id": "dbb9058a-0e50-45d7-ae91-66909b5d4664",
        "type": "Role"
      },
      {
        "id": "9e640839-a198-48fb-8b9a-013fd6f6cbcd",
        "type": "Role"
      },
      {
        "id": "37730810-e9ba-4e46-b07e-8ca78d182097",
        "type": "Role"
      },
      {
        "id": "c7fbd983-d9aa-4fa7-84b8-17382c103bc4",
        "type": "Role"
      }
    ]
  }
]

Execute these commands to grant the permissions in the JSON file and give administrator consent. For YOUR-APP-ID, substitute the appId value from the results you copied in Step B:
```
az ad app update --id YOUR-APP-ID --required-resource-accesses @app-manifest.json

az ad app permission admin-consent --id YOUR-APP-ID
```

Add a new Azure integration in the Mondoo Console

After you've created, granted permissions to, and tested a new app registration, you can create a Mondoo Azure integration. You need some values from the app registration you created in the instructions above.

Access the Integrations > Add > Azure page in one of two ways:
- New space setup: After creating a new Mondoo account or creating a new space, the initial setup guide welcomes you. Select BROWSE INTEGRATIONS and then select Azure.
- INTEGRATIONS page: In the side navigation bar, under INTEGRATIONS, select Add New Integration. Under Cloud Security, select Azure.
In the Choose an integration name box, enter a name for the integration. Make it a name that lets you easily recognize the Azure tenant.
In the Enter the application (client) ID box, enter the value from the appId value you copied in Step B.
In the Enter the directory (tenant) ID box, enter the tenantId value you copied in Step A.
Specify the subscriptions for Mondoo to continuously scan. You copied at least one subscription ID in step A.
- To continuously scan all subscriptions in the tenant, leave the Scan all subscriptions connected to the directory (tenant) ID toggle enabled.
- To choose the subscriptions to scan, disable the Scan all subscriptions connected to the directory (tenant) ID toggle, select Allow list and enter the subscription ID to scan.
- To scan all subscriptions except those you specify, disable the Scan all subscriptions connected to the directory (tenant) ID toggle, select Deny list and enter the names of the subscriptions you don't want Mondoo to scan.
To automatically scan all VMs in your subscription, enable Scan VMs.
Provide the certificate (a PEM (privacy-enhanced mail) file) for Mondoo to securely authenticate with the app (service principal) you created. You created this certificate in Step B.

The certificate file must have the .pem extension and must contain both the private key and the certificate in this order:
```
-----BEGIN PRIVATE KEY-----
key goes here
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
certificate goes here
-----END CERTIFICATE-----
```
Upload the certificate to Mondoo: In the Drag and drop your .pem file here box, select the cloud icon and choose the file to upload.
Select the START SCANNING button.
On the Recommended Policies page, enable the policies on which you want to base assessments of your Azure environment. To learn more, read Manage Policies.
Select FINALIZE SETUP.

Mondoo begins scanning your Azure resources. When it completes, you can see results on the INVENTORY page. To learn more, read Monitor Your Infrastructure Security.

If your integration is unsuccessful, read Troubleshoot an Azure Configuration.

Prerequisites​

Register and grant permissions to an Azure app​

Step A: Retrieve your management group ID​

Step B: Create the app, service principal, and certificate and grant READ access​

Step C: Grant web app and key vault READ permissions to the registered app​

Step D: Grant permissions to access Microsoft Graph (API permissions)​

Add a new Azure integration in the Mondoo Console​

Next steps​