In-place Search for Microsoft Graph API

When forensically preserving data from an M365 or personal Microsoft accounts (e.g., Hotmail, Outlook.com, etc.) using Microsoft Graph API, it is possible to perform In-place Searches to narrow down the data set. You can launch the In-place Search interface for Graph by clicking the In-place Search link in Forensic Email Collector (FEC) as shown below:

1. Email

Graph API supports two mechanisms for In-place Search: the filter query parameter and the search query parameter. FEC uses the filter query parameter by default in order to work around the API cap associated with the search query parameter. You can control this behavior via the Use Search instead of Filter for In-place Email Searches option in Graph API settings as in the screenshot below.

Filtering

The filter query parameter supports the following search operators:

• equals eq / not equals ne
• less than lt / greater than gt
• less than or equal to le / greater than or equal to ge
• and and / or or
• in in
• Negation not
• lambda operator any any
• lambda operator all all
• Starts with startsWith
• Ends with endsWith
• Contains contains

For a list of properties that can be filtered (with some caveats), please refer to Microsoft’s documentation below:

https://docs.microsoft.com/en-us/graph/api/resources/message?view=graph-rest-1.0

Example Searches:

Example 1 — Items with sent or received dates between January 1, 2019 and December 31, 2019:

(receivedDateTime ge 2019-01-01 AND receivedDateTime le 2019-12-31) OR (sentDateTime ge 2019-01-01 AND sentDateTime le 2019-12-31)

Example 2 — Emails from a specific address:

from/emailAddress/address eq '[email protected]'

Example 3 — Emails that contain a specific name in their From field:

contains(from/emailAddress/name,'john')

Example 4 — Emails with a specific Internet Message-ID:

internetMessageId eq '<[email protected]>'

You can use the Unified Query Builder to construct participant and date restrictions using the filter query parameter.

Caution

As of this writing, it is not possible to filter the recipient email fields (i.e., toRecipients, ccRecipients, and bccRecipients). Therefore, Unified Query Builder does not show those participant types as an option when using Graph API with the filter query parameter. You can find a list of which fields are filterable here.

Searching

If you select the  Use Search instead of Filter for In-place Email Searches option in Graph API settings, FEC will use the search query parameter instead of the filter query parameter. The search query parameter is much more flexible, but it has the following important limitation:

Warning

When using the search query parameter, Microsoft Graph API currently limits search results to 275 items per search. If your search query returns more than 275 results per folder, Microsoft will cap the results and return only 275 responsive items per folder.

If you are running into this limitation, you can: i) Use Inline Search instead; ii) Perform your In-place Search via filtering as described above; iii) Or perform your acquisition and In-place Search via EWS or IMAP instead—depending on if you are targeting M365 or Microsoft personal accounts.

We are watching Microsoft’s handling of this issue closely and will update our documentation if/when they remove this limitation. For clarity, this is not a limitation specific to FEC and applies to Microsoft Graph API in general.

Graph API In-place Searches via the search query parameter use Keyword Query Language (KQL) syntax. You can find the details in Microsoft’s documentation below:

Keyword Query Language (KQL) syntax reference

Important Note

KQL syntax looks very similar to the Advanced Query Syntax (AQS) used with EWS. Please note that date searches in KQL should appear without colons, as in the example below:

received>=2016-01-01 OR sent>=2016-01-01

2. OneDrive

Searching OneDrive for Personal Microsoft Accounts

We have found during our testing that the Graph API search functionality for personal OneDrive accounts sometimes does not return any results until a search is performed on Microsoft’s OneDrive web interface. While the underlying reason is unclear, perhaps performing a search on the web triggers Microsoft to index the personal OneDrive contents.

Saving and Clearing the Search Query

Once you have finalized your search query, you can save it by using the SAVE button. This will close the In-place Search window and activate your query. If you would like to clear the search query, you can click on the small 🗑️ symbol next to the Search Query Activated text.

Limitations of Graph Search

The search functionality built into Graph API and utilized by FEC is limited to the documents that Microsoft’s servers are able to recognize and index. For instance, a proprietary CAD file unrecognized by the server, or files inside an encrypted file archive would not be indexed or searched. Similarly, if a file has no extractable text (e.g., a scanned TIFF image of a document), the server would not be able to extract text from it or index it. Keep these limitations in mind if you plan to use this functionality to perform a blanket search intended to search all items and their attachments recursively.