⚡️ filtered resources: microsoft.users & microsoft.roles

When writing policies that require fetching huge amount of data only to
search or filter for specific resources, we fetch all resources and then
we apply the filters using the builtin functions `where()` `any()` and
more.

An example of a policy check that uses these patterns is:
```
// search for emergency accounts
microsoft.users.any(displayName == /emergency/)

// emrgIds holds the ids which match the above criteria
emrgID = microsoft.users.where(displayName == /emergency/).map(id)

// check if at least one of the accounts identified as such is attached to the "Global Administrator" role
microsoft.rolemanagement.roleDefinitions.where(displayName == "Global Administrator").all(assignments.any(principalId == emrgID))
```

To improve these resources, I am proposing a new pattern, similar to the
one used at #5156, but with the
difference that it doesn't override builtin functions, instead it
leverages list resources which are natively supported in MQL with
additional query parameters `filter` and `search`.

These query parameters will be used directly when executing API requests
against Microsoft Graph API. These query parameters are documented at:

https://learn.microsoft.com/en-us/graph/filter-query-parameter?tabs=http#filter-using-lambda-operators

The above example can be rewritten using these two new filtered
resources like:

```
// search for emergency accounts
microsoft.users(search: "displayName:emergency").any()

// emrgIds holds the ids which match the above criteria
emrgID = microsoft.users(search: "displayName:emergency").map(id)

// check if at least one of the accounts identified as such is attached to the "Global Administrator" role
microsoft.roles(filter: "displayName eq 'Global Administrator'").all(assignments.any(principalId == emrgID))
```

Additionally, since these query parameters are directly passed to
Microsoft API's, we can write very complex filters for these two new
resources.

A couple examples are:
```
microsoft.roles(filter: "isBuiltIn eq true and startswith(displayName, 'Global')")
microsoft.users(filter: "accountEnabled eq true AND userType eq 'Member'", search: "officeLocation:berlin")
```

Closes #5110

Signed-off-by: Salim Afiune Maya <[email protected]>

providers/ms365/resources/api_query_parameters.go

@@ -0,0 +1,76 @@
+// Copyright (c) Mondoo, Inc.
+// SPDX-License-Identifier: BUSL-1.1
+
+package resources
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	"go.mondoo.com/cnquery/v11/llx"
+)
+
+// newListResourceIdFromArguments generates a new __id for a list resource that has query
+// parameters `filter` and/or `search`. We need to use these parameters as the resource id
+// so that different query parameters, or no parameter, create different resources.
+//
+// If none is set, the default id returned is `all`
+func newListResourceIdFromArguments(resourceName string, args map[string]*llx.RawData) *llx.RawData {
+	filter, filterExist := args["filter"]
+	search, searchExist := args["search"]
+
+	if filterExist || searchExist {
+		id := resourceName
+		if filterExist {
+			id += fmt.Sprintf("/filter-%s", filter.Value.(string))
+		}
+		if searchExist {
+			id += fmt.Sprintf("/search-%s", search.Value.(string))
+		}
+		return llx.StringData(id)
+	}
+
+	return llx.StringData(resourceName + "/all")
+}
+
+// parseSearch tries to help the user understand the format of Microsoft API searches.
+// By default, if the user runs a simple search of one field, we scape it for them,
+// though if more complicated searches with ANDs/ORs are provided, we let the user know
+// that they need to scape the query on their own.
+//
+// Simple search:
+//
+//	resource(search: "property:my value goes here")
+//
+// Multiple fields search:
+//
+//	resource(search: '"property1:one value" and "property2:something else and complex"')
+func parseSearch(search string) (string, error) {
+	if !strings.Contains(search, ":") {
+		return "", errors.New("search is not of right format: \"property:value\"")
+	}
+
+	if strings.Contains(search, "\"") {
+		// the search filter is already scaped
+		return search, nil
+	}
+
+	if len(strings.Split(search, ":")) > 2 {
+		// special case for multi field search like `displayName:foo or mail:bar`
+		// witout scaping the filters on their own
+		return "", errors.New("search with multiple fields is not of right format: " +
+			"'\"property:value\" [AND | OR] \"property:value\"'")
+	}
+
+	// scape simple search filter like: `displayName:my name`
+	return fmt.Sprintf("\"%s\"", search), nil
+}
+
+// We do not have a parseFilter function since those query parameters can be passed as is,
+// and the APIs return helpful information to the user.
+//
+// https://learn.microsoft.com/en-us/graph/filter-query-parameter?tabs=http#filter-using-lambda-operators
+// func parseFilter(search string) (string, error) {
+// return "", nil
+// }

providers/ms365/resources/applications.go

@@ -30,12 +30,14 @@ func (a *mqlMicrosoft) applications() ([]interface{}, error) {
 		return nil, err
 	}
 	ctx := context.Background()
+
 	top := int32(500)
-	resp, err := graphClient.Applications().Get(ctx, &applications.ApplicationsRequestBuilderGetRequestConfiguration{
+	opts := &applications.ApplicationsRequestBuilderGetRequestConfiguration{
 		QueryParameters: &applications.ApplicationsRequestBuilderGetQueryParameters{
 			Top: &top,
 		},
-	})
+	}
+	resp, err := graphClient.Applications().Get(ctx, opts)
 	if err != nil {
 		return nil, transformError(err)
 	}

providers/ms365/resources/ms365.lr

@@ -11,7 +11,7 @@ microsoft {
   // Deprecated: use `microsoft.tenant` instead
   organizations() []microsoft.tenant
   // List of users
-  users() []microsoft.user
+  users() microsoft.users
   // List of groups
   groups() []microsoft.group
   // List of domains
@@ -23,7 +23,7 @@ microsoft {
   // List of enterprise applications
   enterpriseApplications() []microsoft.serviceprincipal
   // List of roles
-  roles() []microsoft.rolemanagement.roledefinition
+  roles() microsoft.roles
   // Microsoft 365 settings
   settings() dict
   // The connected tenant's default domain name
@@ -56,6 +56,17 @@ microsoft.tenant @defaults("name") {
   subscriptions() []dict
 }
 
+// List of Microsoft Entra users with optional filters
+microsoft.users {
+  []microsoft.user
+
+  init(filter? string, search? string)
+  // Filter users by property values
+  filter string
+  // Search users by search phrases
+  search string
+}
+
 // Microsoft Conditional Access Policies
 microsoft.conditionalAccess {
   // Named locations container
@@ -571,11 +582,21 @@ microsoft.policies {
   consentPolicySettings() dict
 }
 
+// List of Microsoft Entra role definitions with optional filters
+microsoft.roles {
+  []microsoft.rolemanagement.roledefinition
+
+  init(filter? string, search? string)
+  // Filter roles by property values
+  filter string
+  // Search roles by search phrases
+  search string
+}
 
 // Deprecated: use `microsoft.roles` instead
 microsoft.rolemanagement {
   // Deprecated: use `microsoft.roles` instead
-  roleDefinitions() []microsoft.rolemanagement.roledefinition
+  roleDefinitions() microsoft.roles
 }
 
 // Microsoft role definition
@@ -830,4 +851,4 @@ private ms365.teams.teamsMeetingPolicyConfig {
 private ms365.teams.teamsMessagingPolicyConfig {
   // Whether users can report security concerns
   allowSecurityEndUserReporting bool
-}
+}