Using the Microsoft Purview Audit Search Graph API
Published May 09 2024 09:00 AM 1,780 Views
Microsoft

We recently shared the news about the upcoming release of the Microsoft Purview Audit Search Graph API, a new feature that is currently in Public Preview and will be Generally Available by June 2024.

 

The new API available through Microsoft Graph would allow to programmatically search and get relevant audit logs with improvements in search completeness, reliability, and performance This API is an improved option compared to the existing PowerShell cmdlet, Search-UnifiedAuditLog.

 

In this blog, we will demonstrate how we can use the API to get the DLP Rule Matches across all the workloads.

 

Step 1: Register a client application in Microsoft Entra ID using the default options and capture the Application ID (client ID) and Tenant ID --> Link

 

Step 2: Generate the Client Secret and capture the value --> Link

 

Step 3: Grant the AuditLogsQuery.Read.All Permissions by following the below steps:

  • Navigate to the app in Entra ID - Click on API Permissions under Manage
  • Remove the existing permissions if any
  • Click on Add Permission – Under Microsoft API’s select Microsoft Graph – Applications Permissions – Expand AuditLogsQuery – Select AuditLogsQuery.Read.All – Add Permissions
  • Grant the admin Consent

Note – Global Admin role is needed to Grant the Consent (Permission Reference - Microsoft Graph permissions reference - Microsoft Graph | Microsoft Learn)

 

Step 4: Setup Microsoft Graph Beta Security Module.

 

Install the Microsoft.Graph.Beta.Security Module and import it using the below cmdlets:

Install-Module Microsoft.Graph.Beta.Security

Import-Module Microsoft.Graph.Beta.Security

 

Connect to Microsoft Graph using the below cmdlet. Enter Client_ID and client_secret in the password prompt:

$ClientSecretCredential = Get-Credential -Credential "Client_Id"

Connect-MgGraph -TenantId "Tenant_Id" -ClientSecretCredential $ClientSecretCredential

 

Install the Microsoft Graph PowerShell SDK | Microsoft Learn

 

Step 5: Declare the Parameter and create the audit log query.

 

Run the below commands to provide the input parameters, replace the values as needed.

$params = @{

                "@odata.type" = "#microsoft.graph.security.auditLogQuery"

                displayName = "DLPRuleMatches-EXO/SPO/Endpoint"

         filterStartDateTime = [System.DateTime]::Parse("2024-04-02T11:23:34Z")

           filterEndDateTime = [System.DateTime]::Parse("2024-05-02T11:23:34Z")

                operationFilters = @(

"DLPRuleMatch"

)

}

 

You can add more filters/parameters as needed. The supported parameters are mentioned in the below articles:

Create auditLogQuery - Microsoft Graph beta | Microsoft Learn

New-MgBetaSecurityAuditLogQuery (Microsoft.Graph.Beta.Security) | Microsoft Learn

 

Run the below command to Create an Audit Log Query and capture the Id value.

New-MgBetaSecurityAuditLogQuery -BodyParameter $params

 

The search job would take some time to complete based on the input parameters and the output. You can run the below command to check the status of the search Job.

Get-MgBetaSecurityAuditLogQuery -AuditLogQueryId “ID Value captured in previous step” | select status

Get-MgBetaSecurityAuditLogQuery (Microsoft.Graph.Beta.Security) | Microsoft Learn

 

Step 6: Once the search is complete you can run the below command to get export the output as JSON.

Get-MgBetaSecurityAuditLogQueryRecord -AuditLogQueryId 79badea7-e869-4206-942e-99ef759260f5 | ConvertTo-Json -Depth 100 | Out-File -Encoding UTF8 -FilePath c:\temp\DLPRuleMatches.json

Get-MgBetaSecurityAuditLogQueryRecord (Microsoft.Graph.Beta.Security) | Microsoft Learn

 

Hope this article helps you in your Microsoft Purview journey!

Co-Authors
Version history
Last update:
‎May 08 2024 05:47 PM
Updated by: