Microsoft Graph Device Management

Microsoft Intune is a Microsoft cloud-based management solution that provides for mobile device and operating system management

Authentication

For more details about the authentication used in this integration, see Microsoft Integrations - Authentication.

Required Permissions

• DeviceManagementApps.ReadWrite.All - Application
• DeviceManagementConfiguration.ReadWrite.All - Application
• DeviceManagementManagedDevices.PrivilegedOperations.All - Application
• DeviceManagementManagedDevices.ReadWrite.All - Application
• DeviceManagementRBAC.ReadWrite.All - Application
• DeviceManagementServiceConfig.ReadWrite.All - Application

Configure Microsoft Endpoint Manager on Cortex XSOAR

1. Navigate to Settings > Integrations > Servers & Services.
2. Search for Microsoft Endpoint Manager.
3. Click Add instance to create and configure a new integration instance.

1. Azure cloud options

   Azure Cloud	Description
   Worldwide	The publicly accessible Azure Cloud.
   US GCC	Azure cloud for the USA Government Cloud Community (GCC).
   US GCC-High	Azure cloud for the USA Government Cloud Community High (GCC-High).
   DoD	Azure cloud for the USA Department of Defense (DoD).
   Germany	Azure cloud for the German Government.
   China	Azure cloud for the Chinese Government.

2. Click Test to validate the URLs, token, and connection.

Commands

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.

msgraph-get-managed-device-by-id

Get managed devices
Note: physicalMemoryInBytes will return 0 by default since Microsoft hasn’t updated the v1.0 schema with that information yet

Required Permissions

DeviceManagementManagedDevices.ReadWrite.All, DeviceManagementManagedDevices.Read.All

Base Command

msgraph-get-managed-device-by-id

Input

Context Output

Command Example

!msgraph-get-managed-device-by-id device_id=DEVICE_ID_VALUE

Context Example

{
    "MSGraphDeviceManagement": {
        "Device": {
            "AzureADDeviceID": "AZURE_AD_DEVICE_ID",
            "ComplianceState": "compliant",
            "EASActivationDateTime": "0001-01-01T00:00:00Z",
            "EmailAddress": "EMAIL_ADDRESS",
            "EnrolledDateTime": "2020-03-03T11:32:54.6467627Z",
            "ExchangeAccessState": "none",
            "ExchangeAccessStateReason": "none",
            "FreeStorageSpaceInBytes": -1247805440,
            "ID": "ID_VALUE",
            "IsEncrypted": false,
            "IsSupervised": false,
            "JailBroken": "Unknown",
            "LastSyncDateTime": "2020-05-05T10:34:20.9574056Z",
            "ManagedDeviceName": "MANAGED_DEVICE_NAME",
            "ManagedDeviceOwnerType": "company",
            "ManagementAgent": "MANAGEMENT_AGENT",
            "Manufacturer": "MANUFACTURER_VALUE",
            "Model": "MODEL_VALUE",
            "Name": "NAME_VALUE",
            "OSVersion": "10.0.18363.778",
            "OperatingSystem": "Windows",
            "PartnerReportedThreatState": "highSeverity",
            "SerialNumber": "SERIAL_NUMBER_VALUE",
            "TotalStorageSpaceInBytes": -2097152,
            "UserID": "USER_ID_VALUE",
            "UserPrincipalName": "USER_PRINCIPAL_VALUE_NAME"
        }
    }
}

Human Readable Output

Managed device DESKTOP-S2455R8

ID	User ID	Device Name	Operating System	OS Version	Email Address	Manufacturer	Model
DEVICE_ID_VALUE	2827c1e7-edb6-4529-b50d-25984e968637	DESKTOP-S2455R8	Windows	10.0.18363.778	dev@demistodev.onmicrosoft.com	VMware, Inc.	VMware7,1

msgraph-sync-device

Check the device with Intune, immediately receive pending actions and policies

Required Permissions

DeviceManagementManagedDevices.PrivilegedOperations.All

Base Command

msgraph-sync-device

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-sync-device device_id=DEVICE_ID_VALUE

Human Readable Output

Sync device action activated successfully.

msgraph-device-disable-lost-mode

Disable the lost mode of the device

Required Permissions

DeviceManagementManagedDevices.PriviligedOperation.All

Base Command

msgraph-device-disable-lost-mode

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-windows-device-defender-scan device_id=DEVICE_ID_VALUE

Human Readable Output

Windows device defender scan action activated successfully.

msgraph-locate-device

Gets the GPS location of a device (iOS only)

Required Permissions

DeviceManagementManagedDevices.PriviligedOperation.All

Base Command

msgraph-locate-device

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-locate-device device_id=DEVICE_ID_VALUE

Human Readable Output

Locate device action activated successfully.

msgraph-device-reboot-now

Immediately reboots the device

Required Permissions

DeviceManagementManagedDevices.PrivilegedOperations.All

Base Command

msgraph-device-reboot-now

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-device-reboot-now device_id=DEVICE_ID_VALUE

Human Readable Output

Device reboot now action activated successfully..

msgraph-device-shutdown

Immideately shuts down the device

Required Permissions

DeviceManagementManagedDevices.PriviligedOperation.All

Base Command

msgraph-device-shutdown

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-device-shutdown device_id=DEVICE_ID_VALUE

Human Readable Output

Device shutdown action activated successfully.

msgraph-device-bypass-activation-lock

Removes the activation lock (iOS devices only)

Required Permissions

DeviceManagementManagedDevices.PriviligedOperation.All

Base Command

msgraph-device-bypass-activation-lock

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-device-bypass-activation-lock device_id=DEVICE_ID_VALUE

Human Readable Output

Device bypass activation lock action activated successfully.

msgraph-device-retire

Remove the device from intune management

Required Permissions

DeviceManagementManagedDevices.PriviligedOperation.All

Base Command

msgraph-device-retire

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-device-retire device_id=DEVICE_ID_VALUE

Human Readable Output

Retire device action activated successfully.

msgraph-device-reset-passcode

Resets the passcode for the device

Required Permissions

DeviceManagementManagedDevices.PriviligedOperation.All

Base Command

msgraph-device-reset-passcode

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-device-reset-passcode device_id=DEVICE_ID_VALUE

Human Readable Output

Device reset passcode action activated successfully.

msgraph-device-remote-lock

Lock the device, to unlock the user will have to use the passcode

Required Permissions

DeviceManagementManagedDevices.PriviligedOperation.All

Base Command

msgraph-device-remote-lock

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-device-remote-lock device_id=DEVICE_ID_VALUE

Human Readable Output

Device remote lock action activated successfully.

msgraph-device-request-remote-assistance

Request a remote access via TeamViewer

Required Permissions

DeviceManagementManagedDevices.ReadWrite.All

Base Command

msgraph-device-request-remote-assistance

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-device-request-remote-assistance device_id=DEVICE_ID_VALUE

Human Readable Output

Device request remote assistance action activated successfully.

msgraph-device-recover-passcode

Recovers the passcode from the device

Required Permissions

DeviceManagementManagedDevices.PriviligedOperation.All

Base Command

msgraph-device-recover-passcode

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-device-recover-passcode device_id=DEVICE_ID_VALUE

Human Readable Output

Device recover passcode action activated successfully.

msgraph-logout-shared-apple-device-active-user

logs out the current user on a shared iPad device

Required Permissions

DeviceManagementManagedDevices.PriviligedOperation.All

Base Command

msgraph-logout-shared-apple-device-active-user

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-logout-shared-apple-device-active-user device_id=DEVICE_ID_VALUE

Human Readable Output

Logout shard apple device active user action activated successfully.

msgraph-delete-user-from-shared-apple-device

deletes a user that you select from the local cache on a shared iPad device

Required Permissions

DeviceManagementManagedDevices.PriviligedOperation.All

Base Command

msgraph-delete-user-from-shared-apple-device

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-delete-user-from-shared-apple-device device_id=DEVICE_ID_VALUE user_principal_name=USER_PRINCIPAL_NAME_VALUE

Human Readable Output

Delete user from shared apple device action activated successfully.

msgraph-windows-device-defender-update-signatures

Forece update windows defender signatures

Required Permissions

DeviceManagementManagedDevices.PriviligedOperation.All

Base Command

msgraph-windows-device-defender-update-signatures

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-windows-device-defender-update-signatures device_id=DEVICE_ID_VALUE

Human Readable Output

Windows device defender update signatures action activated successfully.

msgraph-clean-windows-device

removes any apps that are installed on a PC running Windows 10. it helps remove pre-installed (OEM) apps that are typically installed with a new PC

Required Permissions

DeviceManagementManagedDevices.PriviligedOperation.All

Base Command

msgraph-clean-windows-device

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-clean-windows-device device_id=DEVICE_ID_VALUE keep_user_data=false

Human Readable Output

Clean windows device action activated successfully.

msgraph-windows-device-defender-scan

Scans the device with windows defender (windows devices only)

Required Permissions

DeviceManagementManagedDevices.PriviligedOperation.All

Base Command

msgraph-windows-device-defender-scan

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-windows-device-defender-scan device_id=DEVICE_ID_VALUE quick_scan=false

Human Readable Output

Windows device defender scan action activated successfully.

msgraph-wipe-device

restores a device to its factory default settings

Required Permissions

DeviceManagementManagedDevices.PriviligedOperation.All, DeviceManagementManagedDevices.ReadWrite.All

Base Command

msgraph-wipe-device

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-wipe-device device_id=DEVICE_ID_VALUE keep_enrollment_data=false keep_user_data=true

Human Readable Output

Wipe device action activated successfully.

msgraph-update-windows-device-account

Updates the windows account of the device

Required Permissions

DeviceManagementManagedDevices.PriviligedOperation.All

Base Command

msgraph-update-windows-device-account

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-update-windows-device-account device_id=DEVICE_ID_VALUE session_initiation_protocal_address=PA_VALUE device_account_password=PW_VALUE device_account_email=MAIL_VALUE

Human Readable Output

Update windows device account action activated successfully.

msgraph-list-managed-devices

List of managed devices

Required Permissions

DeviceManagementManagedDevices.ReadWrite.All, DeviceManagementManagedDevices.Read.All

Base Command

msgraph-list-managed-devices

Input

Context Output

Command example

!msgraph-list-managed-devices page_size=1

Context Example

{
    "MSGraphDeviceManagement": {
        "Device": {
            "AzureADDeviceID": "AZURE_AD_DEVICE_ID",
            "ComplianceState": "compliant",
            "EASActivationDateTime": "0001-01-01T00:00:00Z",
            "EmailAddress": "EMAIL_ADDRESS",
            "EnrolledDateTime": "2020-03-03T11:32:54.6467627Z",
            "ExchangeAccessState": "none",
            "ExchangeAccessStateReason": "none",
            "FreeStorageSpaceInBytes": -1247805440,
            "ID": "ID_VALUE",
            "IsEncrypted": false,
            "IsSupervised": false,
            "JailBroken": "Unknown",
            "LastSyncDateTime": "2020-05-05T10:34:20.9574056Z",
            "ManagedDeviceName": "MANAGED_DEVICE_NAME",
            "ManagedDeviceOwnerType": "company",
            "ManagementAgent": "MANAGEMENT_AGENT",
            "Manufacturer": "MANUFACTURER_VALUE",
            "Model": "MODEL_VALUE",
            "Name": "NAME_VALUE",
            "OSVersion": "10.0.18363.778",
            "OperatingSystem": "Windows",
            "PartnerReportedThreatState": "highSeverity",
            "SerialNumber": "SERIAL_NUMBER_VALUE",
            "TotalStorageSpaceInBytes": -2097152,
            "UserID": "USER_ID_VALUE",
            "UserPrincipalName": "USER_PRINCIPAL_VALUE_NAME"},
            "DeviceNextLink": {
            "NextLink": "https://graph.microsoft.com/v1.0/deviceManagement/managedDevices"
        }
    }
}

Human Readable Output

Managed device DESKTOP-S2455R8

ID	User ID	Device Name	Operating System	OS Version	Email Address	Manufacturer	Model
DEVICE_ID_VALUE	2827c1e7-edb6-4529-b50d-25984e968637	DESKTOP-S2455R8	Windows	10.0.18363.778	dev@demistodev.onmicrosoft.com	VMware, Inc.	VMware7,1

There are more results than shown. For more data please enter the next_link argument:
next_link=https://graph.microsoft.com/v1.0/deviceManagement/managedDevices

msgraph-find-managed-devices-by-name

Search of managed devices by name

Required Permissions

DeviceManagementManagedDevices.ReadWrite.All, DeviceManagementManagedDevices.Read.All

Base Command

msgraph-find-managed-devices-by-name

Input

Context Output

Command Example

!msgraph-find-managed-devices-by-name device_name=NAME_VALUE

Context Example

{
    "MSGraphDeviceManagement": {
        "Device": {
            "AzureADDeviceID": "AZURE_AD_DEVICE_ID",
            "ComplianceState": "compliant",
            "EASActivationDateTime": "0001-01-01T00:00:00Z",
            "EmailAddress": "EMAIL_ADDRESS",
            "EnrolledDateTime": "2020-03-03T11:32:54.6467627Z",
            "ExchangeAccessState": "none",
            "ExchangeAccessStateReason": "none",
            "FreeStorageSpaceInBytes": -1247805440,
            "ID": "ID_VALUE",
            "IsEncrypted": false,
            "IsSupervised": false,
            "JailBroken": "Unknown",
            "LastSyncDateTime": "2020-05-05T10:34:20.9574056Z",
            "ManagedDeviceName": "MANAGED_DEVICE_NAME",
            "ManagedDeviceOwnerType": "company",
            "ManagementAgent": "MANAGEMENT_AGENT",
            "Manufacturer": "MANUFACTURER_VALUE",
            "Model": "MODEL_VALUE",
            "Name": "NAME_VALUE",
            "OSVersion": "10.0.18363.778",
            "OperatingSystem": "Windows",
            "PartnerReportedThreatState": "highSeverity",
            "SerialNumber": "SERIAL_NUMBER_VALUE",
            "TotalStorageSpaceInBytes": -2097152,
            "UserID": "USER_ID_VALUE",
            "UserPrincipalName": "USER_PRINCIPAL_VALUE_NAME"
        }
    }
}

Human Readable Output

Managed device DESKTOP-S2455R8

ID	User ID	Device Name	Operating System	OS Version	Email Address	Manufacturer	Model
DEVICE_ID_VALUE	2827c1e7-edb6-4529-b50d-25984e968637	DESKTOP-S2455R8	Windows	10.0.18363.778	dev@demistodev.onmicrosoft.com	VMware, Inc.	VMware7,1

msgraph-device-auth-reset

Run this command if for some reason you need to rerun the authentication process.

Base Command

msgraph-device-auth-reset

Input

There are no input arguments for this command.

Context Output

There is no context output for this command.

msgraph-get-managed-device-physical-memory-by-id

Get the managed device physical memory bytes.

Base Command

msgraph-get-managed-device-physical-memory-by-id

Input

Context Output

Command example

!msgraph-get-managed-device-physical-memory-by-id device_id=111111-1111-1111-1111-1111111

Context Example

{
    "MSGraphDeviceManagement": {
        "DeviceMemory": {
            "ID": "111111-1111-1111-1111-1111111",
            "Name": "Test",
            "physicalMemoryInBytes": 4294967296
        }
    }
}

Human Readable Output

Managed device

physicalMemoryInBytes	id
4294967296	111111-1111-1111-1111-1111111