Skip to main content

Query Microsoft 365

cnquery can provide answers about your Microsoft 365 environment. It can query any aspect of your Microsoft 365 configuration. For a list of Microsoft 365 resources you can query, read Mondoo Microsoft 365 (MS365) Resource Pack Reference and Mondoo Core Resource Pack Reference.

Connect cnquery with your Microsoft 365 environment

Requirements

To test your Microsoft 365 environment with cnquery, you must have:

Give cnquery access through the Microsoft 365 API

To remotely scan your Microsoft 365 environment, cnquery must have API credentials with access to the subscription. Follow these steps to give cnquery access:

  1. Log into the Azure CLI:
az login --allow-no-subscriptions
  1. Create a new service principal and certificate:
az ad sp create-for-rbac --name "mondoo-ms365" --create-cert
  1. Record the appId and tenant values to use later. Copy the newly created certificate file to a safe location.

  2. Log into the Azure portal, navigate to App Registrations, and select the application you just created.

  3. In the sidebar, select API Permissions.

    Azure Admin Center App Registrations

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

  4. Select Add a permission.

    Azure Admin Center App Registrations

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

    Azure Admin Center App Registrations

  6. Because Mondoo acts as a service, select Application permissions. Then select the API permissions:

    Show or hide required API permissions.
    Microsoft GraphTypeDescription
    Application.Read.AllApplicationRead all applications
    AuditLog.Read.AllApplicationRead all audit log data
    Calendars.ReadApplicationRead calendars in all mailboxes
    Device.Read.AllApplicationRead all devices
    DeviceManagementApps.Read.AllApplicationRead Microsoft Intune apps
    DeviceManagementConfiguration.Read.AllApplicationRead Microsoft Intune device configuration and policies
    DeviceManagementManagedDevices.Read.AllApplicationRead Microsoft Intune devices
    DeviceManagementRBAC.Read.AllApplicationRead Microsoft Intune RBAC settings
    DeviceManagementServiceConfig.Read.AllApplicationRead Microsoft Intune configuration
    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
    InformationProtectionPolicy.Read.AllApplicationRead all published labels and label policies for an organization.
    MailboxSettings.ReadApplicationRead all user mailbox settings
    Organization.Read.AllApplicationRead organization information
    OrgContact.Read.AllApplicationRead organizational contacts
    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
    TeamsAppInstallation.ReadForUser.AllApplicationRead all users' installed Teams apps
    TeamSettings.Read.AllApplicationRead all teams' settings
    ThreatAssessment.Read.AllApplicationRead threat assessment requests
    ThreatIndicators.Read.AllApplicationRead all threat indicators
  7. Grant Mondoo read permissions for Office 365 Management API.

    Azure Admin Center App Registrations - API permissions

    Office 365 Management APIsTypeDescription
    ActivityFeed.ReadApplicationRead activity data for your organization
    ActivityFeed.ReadDlpApplicationRead DLP policy events including detected sensitive data
    ServiceHealth.ReadApplicationRead service health information for your organization

    Confirm the selected permissions by selecting Add permissions.

    Azure Admin Center App Registrations

  8. To complete the process, select Grant admin consent for tenant.

Azure Admin Center App Registrations

Verify with a quick Microsoft 365 query

To quickly confirm that cnquery has access to your Microsoft 365 environment, run this check from your terminal:

cnquery run ms365 -c 'microsoft.organizations { id }'

cnquery lists your Microsoft organizations' IDs.

You've successfully used cnquery to query your Microsoft 365 environment. Now you're ready to explore. The method you choose depends on your goals:

Query Microsoft 365

To answer any question about your environment, use cnquery's interactive shell. It has auto-complete to guide you, which is especially helpful when you're new to cnquery and learning MQL.

To launch a shell into your Azure environment, enter:

cnquery shell ms365

Discover capabilities with the help command

Once inside the shell, use the help command to learn what Microsoft 365 resources you can query. This command lists all the Microsoft 365 resources:

help ms365

From the resulting list, you can drill down further. For example, enter this command to list all the Microsoft domain resources you can query:

help microsoft.domain

From the resulting list, you can drill down even further. You can also learn about available Azure resources in the Mondoo Microsoft 365 (MS365) Resource Pack Reference.

Query storage accounts

Now that you know how to discover what's possible with cnquery, let's run some actual queries in the shell.

This query lists all the current domains:

microsoft.domains

Request full details in results

For a more detailed report, you can specify that you want all fields:

microsoft.domains { * }

For each domain, cnquery lists type, availability, supported services, and more.

Specify fields to include in results

If you're interested in only some details, specify the fields you want in braces. For example, this query asks for each domain's ID, password validity period, and whether the domain is admin managed:

microsoft.domains { id passwordValidityPeriodInDays isAdminManaged }

Filter results

You can filter results based on any fields. Specify the criteria using the where function and standard boolean operators.

For example, this filters results to show only domains that have passwords that expire:

microsoft.domains.where(passwordValidityPeriodInDays != 2147483647) { id availabilityStatus }

cnquery returns all domains with passwords that can expire. It includes the ID and availability status for each one.

Exit the cnquery shell

To exit the cnquery shell, either press Ctrl + D or type exit.

Learn more about querying Microsoft 365