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!
