⭐️ add support for reading microsoft 365 devices (#5406)

* ⭐️ add support for reading microsoft 365 devices
* 🧹 update device implementation
* 🧹 add documentation

Author: chris-rock

providers/ms365/resources/applications.go

@@ -387,7 +387,7 @@ func (a *mqlMicrosoftApplication) owners() ([]interface{}, error) {
 		if err != nil {
 			return nil, err
 		}
-		mqlMicrsoftResource.index(newUserResource.(*mqlMicrosoftUser))
+		mqlMicrsoftResource.indexUser(newUserResource.(*mqlMicrosoftUser))
 		res = append(res, newUserResource)
 	}
 	return res, nil

providers/ms365/resources/devices.go

@@ -0,0 +1,252 @@
+// Copyright (c) Mondoo, Inc.
+// SPDX-License-Identifier: BUSL-1.1
+
+package resources
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	abstractions "github.com/microsoft/kiota-abstractions-go"
+	betamodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
+	"github.com/microsoftgraph/msgraph-beta-sdk-go/reports"
+	"github.com/microsoftgraph/msgraph-sdk-go/devices"
+	"github.com/microsoftgraph/msgraph-sdk-go/models"
+	"github.com/rs/zerolog/log"
+	"go.mondoo.com/cnquery/v11/llx"
+	"go.mondoo.com/cnquery/v11/providers-sdk/v1/plugin"
+	"go.mondoo.com/cnquery/v11/providers-sdk/v1/util/convert"
+	"go.mondoo.com/cnquery/v11/providers/ms365/connection"
+	"go.mondoo.com/cnquery/v11/types"
+)
+
+// see https://learn.microsoft.com/en-us/graph/api/resources/device?view=graph-rest-1.0
+var deviceSelectFields = []string{
+	"id", "displayName", "deviceId", "deviceCategory", "enrollmentProfileName", "enrollmentType",
+	"isCompliant", "isManaged", "manufacturer", "isRooted", "mdmAppId", "model", "operatingSystem",
+	"operatingSystemVersion", "physicalIds", "registrationDateTime", "systemLabels", "trustType",
+}
+
+func initMicrosoftDevices(runtime *plugin.Runtime, args map[string]*llx.RawData) (map[string]*llx.RawData, plugin.Resource, error) {
+	args["__id"] = newListResourceIdFromArguments("microsoft.devices", args)
+	resource, err := runtime.CreateResource(runtime, "microsoft.devices", args)
+	if err != nil {
+		return args, nil, err
+	}
+
+	return args, resource.(*mqlMicrosoftDevices), nil
+}
+
+// list fetches devices from Entra ID and allows the user provide a filter to retrieve
+// a subset of devices
+//
+// Permissions: Device.Read.All
+// see https://learn.microsoft.com/en-us/graph/api/device-list?view=graph-rest-1.0&tabs=http
+func (a *mqlMicrosoftDevices) list() ([]interface{}, error) {
+	conn := a.MqlRuntime.Connection.(*connection.Ms365Connection)
+	graphClient, err := conn.GraphClient()
+	if err != nil {
+		return nil, err
+	}
+
+	betaClient, err := conn.BetaGraphClient()
+	if err != nil {
+		return nil, err
+	}
+
+	// Index of devices are stored inside the top level resource `microsoft`, just like
+	// MFA response. Here we create or get the resource to access those internals
+	mainResource, err := CreateResource(a.MqlRuntime, "microsoft", map[string]*llx.RawData{})
+	if err != nil {
+		return nil, err
+	}
+	microsoft := mainResource.(*mqlMicrosoft)
+
+	// fetch device data
+	ctx := context.Background()
+	top := int32(999)
+	opts := &devices.DevicesRequestBuilderGetRequestConfiguration{
+		QueryParameters: &devices.DevicesRequestBuilderGetQueryParameters{
+			Select: deviceSelectFields,
+			Top:    &top,
+		},
+	}
+
+	if a.Search.State == plugin.StateIsSet || a.Filter.State == plugin.StateIsSet {
+		// search and filter requires this header
+		headers := abstractions.NewRequestHeaders()
+		headers.Add("ConsistencyLevel", "eventual")
+		opts.Headers = headers
+
+		if a.Search.State == plugin.StateIsSet {
+			log.Debug().
+				Str("search", a.Search.Data).
+				Msg("microsoft.devices.list.search set")
+			search, err := parseSearch(a.Search.Data)
+			if err != nil {
+				return nil, err
+			}
+			opts.QueryParameters.Search = &search
+		}
+		if a.Filter.State == plugin.StateIsSet {
+			log.Debug().
+				Str("filter", a.Filter.Data).
+				Msg("microsoft.devices.list.filter set")
+			opts.QueryParameters.Filter = &a.Filter.Data
+			count := true
+			opts.QueryParameters.Count = &count
+		}
+	}
+
+	resp, err := graphClient.Devices().Get(ctx, opts)
+	if err != nil {
+		return nil, transformError(err)
+	}
+	devices, err := iterate[*models.Device](ctx,
+		resp,
+		graphClient.GetAdapter(),
+		devices.CreateDeltaGetResponseFromDiscriminatorValue,
+	)
+	if err != nil {
+		return nil, transformError(err)
+	}
+
+	detailsResp, err := betaClient.
+		Reports().
+		AuthenticationMethods().
+		UserRegistrationDetails().
+		Get(ctx,
+			&reports.AuthenticationMethodsUserRegistrationDetailsRequestBuilderGetRequestConfiguration{
+				QueryParameters: &reports.AuthenticationMethodsUserRegistrationDetailsRequestBuilderGetQueryParameters{
+					Top: &top,
+				},
+			})
+	// we do not want to fail the device fetching here, this likely means the tenant does not have the right license
+	if err != nil {
+		microsoft.mfaResp = mfaResp{err: err}
+	} else {
+		userRegistrationDetails, err := iterate[*betamodels.UserRegistrationDetails](ctx, detailsResp, betaClient.GetAdapter(), betamodels.CreateUserRegistrationDetailsCollectionResponseFromDiscriminatorValue)
+		// we do not want to fail the device fetching here, this likely means the tenant does not have the right license
+		if err != nil {
+			microsoft.mfaResp = mfaResp{err: err}
+		} else {
+			mfaMap := map[string]bool{}
+			for _, u := range userRegistrationDetails {
+				if u.GetId() == nil || u.GetIsMfaRegistered() == nil {
+					continue
+				}
+				mfaMap[*u.GetId()] = *u.GetIsMfaRegistered()
+			}
+			microsoft.mfaResp = mfaResp{mfaMap: mfaMap}
+		}
+	}
+
+	// construct the result
+	res := []interface{}{}
+	for _, u := range devices {
+		graphDevice, err := newMqlMicrosoftDevice(a.MqlRuntime, u)
+		if err != nil {
+			return nil, err
+		}
+		// indexUser devices by id
+		microsoft.indexDevice(graphDevice)
+		res = append(res, graphDevice)
+	}
+
+	return res, nil
+}
+
+func initMicrosoftDevice(runtime *plugin.Runtime, args map[string]*llx.RawData) (map[string]*llx.RawData, plugin.Resource, error) {
+	// we only look up the user if we have been supplied by id, displayName or userPrincipalName
+	if len(args) > 1 {
+		return args, nil, nil
+	}
+
+	rawId, okId := args["id"]
+	rawDisplayName, okDisplayName := args["displayName"]
+
+	if !okId && !okDisplayName {
+		// required parameters are not set, we just pass-through the initialization arguments
+		return args, nil, nil
+	}
+
+	var filter *string
+	if okId {
+		idFilter := fmt.Sprintf("id eq '%s'", rawId.Value.(string))
+		filter = &idFilter
+	} else if okDisplayName {
+		displayNameFilter := fmt.Sprintf("displayName eq '%s'", rawDisplayName.Value.(string))
+		filter = &displayNameFilter
+	}
+	if filter == nil {
+		return nil, nil, errors.New("no filter found")
+	}
+
+	conn := runtime.Connection.(*connection.Ms365Connection)
+	graphClient, err := conn.GraphClient()
+	if err != nil {
+		return nil, nil, err
+	}
+
+	ctx := context.Background()
+	resp, err := graphClient.Devices().Get(ctx, &devices.DevicesRequestBuilderGetRequestConfiguration{
+		QueryParameters: &devices.DevicesRequestBuilderGetQueryParameters{
+			Filter: filter,
+		},
+	})
+	if err != nil {
+		return nil, nil, transformError(err)
+	}
+
+	val := resp.GetValue()
+	if len(val) == 0 {
+		return nil, nil, errors.New("device not found")
+	}
+
+	deviceId := val[0].GetId()
+	if deviceId == nil {
+		return nil, nil, errors.New("device id not found")
+	}
+
+	// fetch devices by id
+	device, err := graphClient.Devices().ByDeviceId(*deviceId).Get(ctx, &devices.DeviceItemRequestBuilderGetRequestConfiguration{})
+	if err != nil {
+		return nil, nil, transformError(err)
+	}
+	mqlMsApp, err := newMqlMicrosoftDevice(runtime, device)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	return nil, mqlMsApp, nil
+}
+
+func newMqlMicrosoftDevice(runtime *plugin.Runtime, u models.Deviceable) (*mqlMicrosoftDevice, error) {
+	graphDevice, err := CreateResource(runtime, "microsoft.device",
+		map[string]*llx.RawData{
+			"__id":                   llx.StringDataPtr(u.GetId()),
+			"id":                     llx.StringDataPtr(u.GetId()),
+			"displayName":            llx.StringDataPtr(u.GetDisplayName()),
+			"deviceId":               llx.StringDataPtr(u.GetDeviceId()),
+			"deviceCategory":         llx.StringDataPtr(u.GetDeviceCategory()),
+			"enrollmentProfileName":  llx.StringDataPtr(u.GetEnrollmentProfileName()),
+			"enrollmentType":         llx.StringDataPtr(u.GetEnrollmentType()),
+			"isCompliant":            llx.BoolDataPtr(u.GetIsCompliant()),
+			"isManaged":              llx.BoolDataPtr(u.GetIsManaged()),
+			"manufacturer":           llx.StringDataPtr(u.GetManufacturer()),
+			"isRooted":               llx.BoolDataPtr(u.GetIsRooted()),
+			"mdmAppId":               llx.StringDataPtr(u.GetMdmAppId()),
+			"model":                  llx.StringDataPtr(u.GetModel()),
+			"operatingSystem":        llx.StringDataPtr(u.GetOperatingSystem()),
+			"operatingSystemVersion": llx.StringDataPtr(u.GetOperatingSystemVersion()),
+			"physicalIds":            llx.ArrayData(convert.SliceAnyToInterface(u.GetPhysicalIds()), types.String),
+			"registrationDateTime":   llx.TimeDataPtr(u.GetRegistrationDateTime()),
+			"systemLabels":           llx.ArrayData(convert.SliceAnyToInterface(u.GetSystemLabels()), types.String),
+			"trustType":              llx.StringDataPtr(u.GetTrustType()),
+		})
+	if err != nil {
+		return nil, err
+	}
+	return graphDevice.(*mqlMicrosoftDevice), nil
+}

providers/ms365/resources/groups.go

@@ -74,7 +74,7 @@ func (a *mqlMicrosoftGroup) members() ([]interface{}, error) {
 		if err != nil {
 			return nil, err
 		}
-		mqlMicrosoftResource.index(newUserResource.(*mqlMicrosoftUser))
+		mqlMicrosoftResource.indexUser(newUserResource.(*mqlMicrosoftUser))
 		res = append(res, newUserResource)
 	}
 	return res, nil

providers/ms365/resources/microsoft.go

@@ -8,6 +8,7 @@ import (
 )
 
 var idxUsersById = &sync.RWMutex{}
+var idxDevicesById = &sync.RWMutex{}
 
 type mfaResp struct {
 	// holds the error if that is what the request returned
@@ -19,6 +20,8 @@ type mqlMicrosoftInternal struct {
 	permissionIndexer
 	// index users by id
 	idxUsersById map[string]*mqlMicrosoftUser
+	// index devices by id
+	idxDevicesById map[string]*mqlMicrosoftDevice
 	// the response when asking for the user registration details
 	mfaResp mfaResp
 }
@@ -29,17 +32,20 @@ func (a *mqlMicrosoft) initIndex() {
 	if a.idxUsersById == nil {
 		a.idxUsersById = make(map[string]*mqlMicrosoftUser)
 	}
+	if a.idxDevicesById == nil {
+		a.idxDevicesById = make(map[string]*mqlMicrosoftDevice)
+	}
 }
 
-// index adds a user to the internal indexes
-func (a *mqlMicrosoft) index(user *mqlMicrosoftUser) {
+// indexUser adds a user to the internal indexes
+func (a *mqlMicrosoft) indexUser(user *mqlMicrosoftUser) {
 	a.initIndex()
 	idxUsersById.Lock()
 	a.idxUsersById[user.Id.Data] = user
 	idxUsersById.Unlock()
 }
 
-// userById returns a user by id if it exists in the index
+// userById returns a user by id if it exists in the indexUser
 func (a *mqlMicrosoft) userById(id string) (*mqlMicrosoftUser, bool) {
 	if a.idxUsersById == nil {
 		return nil, false
@@ -50,3 +56,23 @@ func (a *mqlMicrosoft) userById(id string) (*mqlMicrosoftUser, bool) {
 	idxUsersById.RUnlock()
 	return res, ok
 }
+
+// indexDevice adds a device to the internal indexes
+func (a *mqlMicrosoft) indexDevice(device *mqlMicrosoftDevice) {
+	a.initIndex()
+	idxUsersById.Lock()
+	a.idxDevicesById[device.Id.Data] = device
+	idxUsersById.Unlock()
+}
+
+// deviceById returns a device by id if it exists in the indexDevice
+func (a *mqlMicrosoft) deviceById(id string) (*mqlMicrosoftDevice, bool) {
+	if a.idxDevicesById == nil {
+		return nil, false
+	}
+
+	idxDevicesById.RLock()
+	res, ok := a.idxDevicesById[id]
+	idxDevicesById.RUnlock()
+	return res, ok
+}

providers/ms365/resources/ms365.lr

@@ -263,6 +263,57 @@ private microsoft.group @defaults("id displayName") {
   membershipRuleProcessingState string
 }
 
+// List of Microsoft Entra devices
+microsoft.devices {
+  []microsoft.device
+
+  init(filter? string, search? string)
+  // Filter devices by property values
+  filter string
+  // Search devices by search phrases
+  search string
+}
+
+// Microsoft device
+private microsoft.device @defaults("id displayName") {
+  // Device ID
+  id string
+  // Device display name
+  displayName string
+  // Unique identifier set
+  deviceId string
+  // User-defined property set by Intune
+  deviceCategory string
+  // Enrollment profile applied to the device
+  enrollmentProfileName string
+  // Enrollment type of the device
+  enrollmentType string
+  // Whether the device complies with Mobile Device Management (MDM) policies
+  isCompliant bool
+  // Whether the device is managed by a Mobile Device Management (MDM) app
+  isManaged bool
+  // Manufacturer
+  manufacturer string
+  // Whether the device is rooted or jail-broken
+  isRooted bool
+  // Application identifier used to register device into MDM
+  mdmAppId string
+  // Model of the device
+  model string
+  // The type of operating system on the device
+  operatingSystem string
+  // The version of the operating system on the device
+  operatingSystemVersion string
+  // Physical IDs
+  physicalIds []string
+  // Date and time of when the device was registered
+  registrationDateTime time
+  // List of labels applied to the device by the system
+  systemLabels []string
+  // Type of trust for the joined device
+  trustType string
+}
+
 // Microsoft domain
 private microsoft.domain @defaults("id") {
   // Domain ID