Skip to main content

Manual Setup - Azure Continuous Scanning

Mondoo integration with Azure requires that you register and grant permissions to an Azure app. Follow this "manual" approach to app registration and configuration if:

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

      1. Install the Azure CLI.

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

To configure your Azure resources, you must:

Step A: Register an app with Microsoft Entra ID and create a service principal

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

Step C: Grant required READ permissions to the app

Step D: Grant web app READ permissions to the app

Step E: Grant permissions to access Azure key vault

Step F: Upload the application certificate

Step A: Register an app with Microsoft Entra ID and create a service principal​

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

  1. Log into the Azure portal as a global administrator, application administrator or cloud application administrator.

  2. Find and select Microsoft Entra ID.

  3. In the navigation sidebar, select App registrations.

    Azure app registrations

  4. Select + New registration.

    Create a new app registration in Azure

  5. Enter an application name (such as mondoo-security) and select Accounts in this organizational directory only as the supported account type. Mondoo does not require an application redirect URI.

  6. Select the Register button.

    Microsoft creates the application ID and displays it in the application registration overview.

    new app registration in Azure

    Keep the page open as you continue to the next step.

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

  1. In the navigation sidebar, select API permissions.

    API permissions

    By default, Microsoft grants your new application User.Read permission for Microsoft Graph. It's not required for Mondoo, so you can remove it.

  2. Select + Add a permission.

    Add permission in Entra

  3. From the list of Commonly used Microsoft APIs, select Microsoft Graph.

    API permissions

  4. Because Mondoo acts as a service, select Application permissions.

  5. Select expand all to see all permissions. Then select the required API permissions:

Show or hide required API permissions.
Microsoft GraphTypeDescription
Application.Read.AllApplicationRead all applications
AuditLog.Read.AllApplicationRead all audit log data
Directory.Read.AllApplicationRead directory data
Domain.Read.AllApplicationRead domains
IdentityProvider.Read.AllApplicationRead identity providers
IdentityRiskEvent.Read.AllApplicationRead all identity risk event information
IdentityRiskyUser.Read.AllApplicationRead all identity risky user information
Policy.Read.AllApplicationRead your organization's policies
Policy.Read.ConditionalAccessApplicationRead your organization's conditional access policies
Policy.Read.PermissionGrantApplicationRead consent and permission grant policies
RoleManagement.Read.AllApplicationRead role management data for all RBAC providers
SecurityActions.Read.AllApplicationRead your organization's security actions
SecurityEvents.Read.AllApplicationRead your organization's security events
ThreatAssessment.Read.AllApplicationRead threat assessment requests
ThreatIndicators.Read.AllApplicationRead all threat indicators

  1. Select the Add permissions button.

  2. To complete the process, select Grant admin consent for (your tenant name) and select the Yes button to confirm.

Step C: Grant required READ permissions to the app​

These steps guide you through setting the READ permissions and "Key Vault Reader" permissions for a single subscription. If you want to scan several subscriptions, you must repeat the same steps for each subscription.

If you want Mondoo to monitor an entire management group, you can perform these steps at the management group level: Search for "management groups" in the Azure portal and then select the management group you want to monitor. To monitor the entire directory, select the tenant root group.

Set subscription-level permissions for your new app registration:

  1. From the Azure portal home, select Subscriptions.

    Azure subscriptions

  2. Select the subscription you want to integrate with Mondoo.

    Azure subscription

  3. In the sidebar under the subscription name, select Access control (IAM).

  4. Select the Add role assignment button.

  5. Select the Reader role and then select the Members tab (or Next button).

    Azure Subscription Role Assignment

  6. Select + Select Members, find and select your Mondoo app registration, and select the Select button.

    Azure Subscription Role Member Assignment

  7. Select the Review + assign button (or Next button), check your work, and then select the Review + assign button again to assign the Reader role to your Mondoo app registration.

  8. Repeat steps 4-7 and this time choose the "Key Vault Reader" role in step 5.

    Keep the Access control (IAM) page open as you continue to Step D.

Step D: Grant web app READ permissions to the app​

Grant web app permissions by creating a custom RBAC role for Mondoo and assigning the custom role to your new app registration.

  1. In the sidebar under the subscription name, select Overview.

  2. Copy the subscription ID and save it somewhere handy.

  3. In the sidebar under the subscription name, select Access control (IAM).

  4. On the subscription's Access control (IAM) page toolbar, select + Add and select Add custom role.

    Azure Subscription Roles

  5. Name the new role mondoo-role, provide a description, and then select the JSON tab.

  6. On the JSON tab, select the Edit button and delete all existing content from the edit box.

  7. Copy this JSON content and paste it into the edit box on the JSON tab:

    {
       "Name": "mondoo-role",
        "IsCustom": true,
       "description": "Custom role for Mondoo integration",
       "assignableScopes": [
           "/subscriptions/YOUR-SUBSCRIPTION-ID"
           ],
       "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": []
    }

    To integrate with more than one subscription, list them:

    "assignableScopes": [

      "/subscriptions/YOUR-SUBSCRIPTION-ID-1"

      "/subscriptions/YOUR-SUBSCRIPTION-ID-2"

      "/subscriptions/YOUR-SUBSCRIPTION-ID-3"

    ]

    To integrate at the management group level, copy this JSON content and paste it into the edit box on the JSON tab:

    {
        "properties": {
            "roleName": "mondoo-role",
            "description": "Custom role for Mondoo integration",
            "assignableScopes": [
                "/providers/Microsoft.Management/managementGroups/YOUR-MANAGEMENT-GROUP-ID"
            ],
            "permissions": [
                {
                    "actions": [
                        "Microsoft.Authorization/*/read",
                        "Microsoft.ResourceHealth/availabilityStatuses/read",
                        "Microsoft.Resources/subscriptions/resourceGroups/read",
                        "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.Web/sites/*/read"
                    ],
                    "notActions": [],
                    "dataActions": [],
                    "notDataActions": []
                }
            ]
        }
    }

    For YOUR-MANAGEMENT-GROUP-ID, substitute the name of the management group you want to monitor. If you don't have management groups, you can use your tenant ID because your tenant is your root management group.

  8. Select the Save button.

  9. Select the Review + create button (or the Next button), check your work, and then select the Review + create button again.

  10. Assign the created Custom role to the app: On the subscription's Access control (IAM) page toolbar, select + Add and select Add role assignment.

  11. Search for and select the role you just created, mondoo-role.

  12. Select the Members tab and select User, group, or service principal.

  13. Select the + Select Members link, find and select your Mondoo app registration, and select the Select button.

    Azure Subscription Role Member Assignment

  14. Select the Review + assign button to check the assignment. Select the Review + assign button again to assign the mondoo-role role to your Mondoo app registration.

    Azure Subscription Role Member Assignment

  15. Make sure that you have two RBAC roles for the app you created: On the subscription's Access control (IAM) page toolbar, select Check Access.

  16. Keep "User, group, or service principal" selected and type name you gave the app, such as mondoo-security.

  17. Select the app. Verify that you see two roles: Reader and the custom role that you created.

    It can take a few minutes for the roles you assigned to take effect.

Step E: Grant permissions to access Azure key vault​

note

There are two permission models for key vaults: role-based access control (RBAC) and key vault access policy.

See what permission model your key vault uses: In the Azure portal, view the key vault's Access configuration settings. (You can easily change it to RBAC.)

If you are using the RBAC for the key vault, there is no need for further actions; the READ permissions on the key vault will be applied by the "Key Vault Reader" subscription permissions applied in Step C.

If you use key vault access policy, this step is required.

A key vault access policy determines whether a given security principal (a user, application or user group) can perform different operations on key vault secrets, keys, and certificates.

  1. From the Azure portal home, select Key vaults.

  2. Select a key vault from the list.

  3. In the sidebar under the key vault name, select Access policies.

    key vault access policies

  4. In the toolbar, select + Create.

  5. Configure the permissions:

    • Under Key permissions, select Get and List.

    • Under Secret permissions, select Get and List.

    • Under Certificate permissions, select Get and List.

  6. Select the Next button.

  7. From the list, select the app registration you created.

  8. Select the Next button and select the Next button again to skip the Application (optional) step.

  9. Review the access policy and then select the Create button.

Step F: Upload the application certificate.​

The app registration and your Mondoo integration must share a PEM (privacy-enhanced mail) certificate for secure authentication. The certificate must not be password protected.

Create a PEM certificate using the method approved by your organization's security team. You need two files:

  • The file you upload to Azure must have only the certificate, not the private key.

  • The file you upload to Mondoo Console (in the Add a new Azure integration in the Mondoo Console section below) must have both the private key and the certificate. It must have a .pem extension and must use this format and order of information:

    -----BEGIN PRIVATE KEY-----
    key goes here
    -----END PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    certificate goes here
    -----END CERTIFICATE-----
Generate a self-signed certificate for testing

For testing purposes only, you can use OpenSSL toolkit together with req to generate a certificate. Run this command in Linux shell, macOS shell, or Azure Cloud shell (bash):

openssl req -newkey rsa:4096  -x509  -sha512  -days 365 -nodes -out certificate.pem -keyout privatekey.key

Add the private key to the beginning of the PEM file:

cat privatekey.key certificate.pem > certificate.combo.pem

Upload the certificate to Azure:

  1. From the Azure portal home, select Microsoft Entra ID.

  2. In the navigation sidebar, select App registrations.

  3. Select the app you created.

  4. In the sidebar under the app name, select Certificate & secrets.

  5. Select Certificates and then select Upload certificate.

  6. Select the PEM certificate and enter a description, such as Mondoo certificate.

info

Be sure to choose the file containing only the certificate, not the private key.

  1. Select the Add button.

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.

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

      Welcome to Mondoo Page

    • INTEGRATIONS page: In the side navigation bar, under INTEGRATIONS, select Add New Integration. Under Cloud Security, select Azure.

      integration-create-image

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

  3. In the Enter Application (client) ID box, enter the value from the app registration's Application (client) ID box.

  4. In the Enter the Directory (tenant) ID box, enter the value from the app registration's Directory (tenant) ID box.

  5. Specify the subscriptions for Mondoo to continuously scan.

    • 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 Allowlist, 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 Denylist, and enter the names of the subscriptions you don't want Mondoo to scan.

  6. To automatically discover all Linux and Windows VMs in your subscription and scan them using Azure Run Command, select Scan Azure VMs using Run Command.

  7. Provide a certificate (a PEM (privacy-enhanced mail) file) for Mondoo to securely authenticate with the app (service principal) you created.

    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.

    integration-create-image

  8. To automatically scan all VMs in your subscription, enable Scan Azure VMs using RunCommand.

  9. Select the START SCANNING button.

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

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

Next steps​