top of page
Writer's pictureWill Francillette
Jan 143 min read

Connect to Advanced Hunting API with the Graph SDK PowerShell module

Defender

In this blog, I want to show how to connect to the Graph Security API using the PowerShell Graph SDK Module. We will focus on the Advanced Hunting module as an example but other modules are available:

  • Alerts and incidents

  • Attack simulation and training

  • eDiscovery

  • Information protection

  • Record management

  • Secure score

  • Threat intelligence


Table of contents


Overview


The Microsoft Graph security API federates queries to all onboarded security providers and aggregates responses. Use the Microsoft Graph security API to build applications that:

  1. Consolidate and correlate security alerts from multiple sources.

  2. Pull and investigate all incidents and alerts from services that are part of or integrated with Microsoft 365 Defender.

  3. Unlock contextual data to inform investigations.

  4. Automate security tasks, business processes, workflows, and reporting.

  5. Send threat indicators to Microsoft products for customized detections.

  6. Invoke actions to in response to new threats.

  7. Provide visibility into security data to enable proactive risk management.


Advanced hunting via Graph security API


You may wander why would you use the Graph Security API to run our Advanced hunting queries instead of the Defender XDR portal?

  1. Threshold: the portal limits the results returned by a query to 10,000 results however the API allow you to retrieve 100,000 results

  2. Automation: In my previous blog I used this API to automate MDE update status using an Azure Automation account but the possibilities are unlimited: MDE: Keeping your Antivirus up to date - deep dive | french365connection.co.uk

  3. All other benefits mentioned in the overview

Quotas and resource allocation


We are still subject to the following quotas and limitations

  1. Queries explore and return data from the past 30 days.

  2. Results can return up to 100,000 rows.

  3. You can make up to at least 45 calls per minute per tenant. The number of calls varies per tenant based on its size.

  4. Each tenant is allocated CPU resources, based on the tenant size. Queries are blocked if the tenant has reached 100% of the allocated resources until after the next 15-minute cycle. To avoid blocked queries due to excess consumption, follow the guidance in Optimize your queries to avoid hitting CPU quotas.

  5. If a single request runs for more than three minutes, it times out and returns an error.

  6. A 429 HTTP response code indicates that you've reached the allocated CPU resources, either by number of requests sent, or by allotted running time. Read the response body to understand the limit you have reached.


Graph SDK vs Web Request


Why would we use the Graph SDK instead of a traditional web request?

  1. Token management: you don't need to generate and manage the authentication token yourself as you would with a simple web request

  2. Authentication method support: the Graph SDK supports all type of authentication and particularly Managed Identity, Certificate in addition to the user credentials or service principal + secret

  3. Improved security: Integration with Conditional Access, permission management


Permissions


Those are the permissions to query advanced hunting with the Security Graph API

Permission type

Permission

Application

ThreatHunting.Read.All

Delegated (work or school account)

ThreatHunting.Read.All

Refer to the doc for the other modules


How-To


1 - Connection

To connect, we use Connect-MgGraph and here for example we use a system assigned managed identity






We can also use:

  • Certificate Thumbprint

  • Service Principal Secret

  • User credentials

See the examples from this doc to find out how to connect per authentication method type: Connect-MgGraph (Microsoft.Graph.Authentication) | Microsoft Learn


2 - Query

My advise is to initially design your query in the Microsoft Defender XDR portal

We use the action runHuntingQuery and Invoke-MgGraphRequest as shown below

(I used the query from my previous blog)



3 - Retrieve results

Results are returns paginated so we use a simple loop to retrieve all results in a single variable $results










You can then parse and format your results and send as an email or a teams message, redirect the result to another API. To find out an example for sending an email automatically refer to my previous blog (I know again but really want you to have a look 😁)


Conclusion


The Graph SDK should be our first stop when using the Graph API. I used PowerShell but other language are available


References



 
Will Frenchie

I am a Microsoft Solutions Architect specialized in Microsoft 365, Entra and Azure security products at Threatscape.

I love learning, blogging and coding. My interests are very diverse from architecture, security, cloud engineering, automation, DevOps and PowerShell.

I own over a dozen Microsoft certifications and have worked in IT across multiple and diverse industries for over 15 years now.




916 views0 comments

Comments

bottom of page