cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Show  only  | Search instead for 
Did you mean: 
Microsoft 365 Compliance audit log activities via O365 Management API - Part 2
By
Walid_Elmorsy
Published Nov 15 2021 09:00 AM 123K Views
Walid_Elmorsy
Microsoft
‎Nov 15 2021 09:00 AM

Microsoft 365 Compliance audit log activities via O365 Management API - Part 2

‎Nov 15 2021 09:00 AM

In the previous part of this blog series- Microsoft 365 Compliance audit log activities via O365 Management API - Part 1, we discussed the importance of auditing and reporting for an organization's security and compliance posture. We also discussed Microsoft auditing solutions, auditing architecture (and its components), as well as Microsoft Information Protection audit log schema

 

DLP-Activities Audit Log Schema

Let’s try to go over some of the audit log schema parameters for email and file events to make it clearer. Please note that the below is a cut-down list of the schema as most of the schema parameters are self-explanatory. For a full and updated list of DLP log schema, please visit Microsoft official documentation here, however, we will highlight a few schema parameters that we believe are important to explain what they mean and how can we use them. Below is an example of a DLP audit log:

 

{"CreationTime":  "2021-11-02T21:52:10", "Id":  "1c446afc-5996-4236-845c-c6d28557bd78", "Operation":  "DlpRuleMatch","OrganizationId":  "123456-8385-8539b47e6810", "RecordType":  13, "UserKey":  "1153801120595078600","UserType":  4, "Version":  1, "Workload":  "Exchange", "ObjectId":  "\u003cBL0PR01MB52980905BA71DB19C194A324BA8B9@prod.exchangelabs.com", "UserId":  "user.one@nodomain.xyz","IncidentId":  "3d3db700-9bea-643b-3000-08d99e4c1d8b", "PolicyDetails":  [{"PolicyId":  "fad884cb-d5a5-4ad2-9dab-24283e4bb6cc","PolicyName":  "Email X-Header Tagging","Rules":  [{"Actions":  ["ExSetHeader","ExModifySubject"], "ConditionsMatched":  {"ConditionMatchedInNewScheme":  true, "OtherConditions":  [{"Name":  "SensitivityLabels", "Value":  "OFFICIAL"} ,"ManagementRuleId":  "edb9343d-fabe-47b4-a725-18f0cb031b54", "RuleId":  "ad484e0b-752f-4787-befd-bd14db5598d4","RuleMode":  "Enable","RuleName":  "Stamp the X-Header and Append the Subject [SEC=OFFICIAL]", "Severity":  "Medium"}], "SensitiveInfoDetectionIsIncluded":  true, "ExchangeMetaData":  {"BCC":  [], "CC":  [], "FileSize":  18823, "From":  "user.one@nodomain.xyz", "MessageID":  "\u003cBL0PR01MB52980905BA71DB19C194A324BA8B9@prod.exchangelabs.com", "RecipientCount":  1, "Sent":  "2021-11-02T21:52:09","Subject":  "RE: Test new - 3rd Nov - 03  [SEC=OFFICIAL]", "To":  ["admin@nodomain.xyz"],"UniqueID":  "32e0decc-4e67-4259-ef4b-08d99e4b052f"}}

 

DLP log event schema reference

 

Schema parameter

Description

Potential Values

Notes

DLP-Specific Base Schema

RecordType

The operation type indicated by the record
  • 11 = ComplianceDLPSharePoint
  • 13 = ComplianceDLPExchange
  • 33 = ComplianceDLPSharePointClassification
  • 63 = DLPEndpoint
  • 99 = OnPremisesFileShareScannerDlp
  • 100 = OnPremisesSharePointScannerDlp

For a complete updated list and full description of the Log RecordType, please refer to this article. Here we are only listing the relevant DLP Record types.

Operation

The operation type for the audit log (Referenced here as discussed above)
  • DlpRuleMatch
  • DlpRuleUndo
  • DlpInfo
  • DlpRuleMatch - This indicates a DLP rule was matched. These events exist in both Exchange and SharePoint Online and OneDrive for Business.
    • For Exchange it includes false positive and override information.
    • For SharePoint Online and OneDrive for Business, false positive and overrides generate separate events.
  • DlpRuleUndo - These only exist in SharePoint Online and OneDrive for Business. These events indicate a previously applied policy action has been "undone" – either because of false positive/override designation by user, or because the document is no longer subject to policy (either due to policy change or change to content in doc).
  • DlpInfo - These only exist in SharePoint Online and OneDrive for Business. These events indicate a false positive designation but no action was "undone."

IncidentId

The DLP incident unique ID
  • String of text

 

DLP-Specific Extended Schema

PolicyId

The GUID of the DLP policy for this event
  • DLP Policy GUID

 

PolicyName

The friendly name of the DLP policy for this event
  • DLP Policy name (string)

 

RuleId

The GUID of the DLP rule for this event.
  • DLP Rule GUID

 

RuleName

The friendly name of the DLP rule for this event
  • DLP Rule name (string)

 

Actions

A list of actions taken because of a DLP RuleMatch event.

Examples only:

  • ExSetHeader
  • ExModifySubject
  • ApplyContentMarking
  • Encrypt
  • BlockAccess
  • NotifyUser

The DLP policy actions depend on many variables, such as, workload in scope (EXO, SPO, etc.) and conditions selected. Here we listed a few DLP policy action examples for the purpose of the article.

Severity

The severity of the rule match.
  • Low
  • Medium
  • High

 

DLP-Specific Extended SENSITIVE Schema (the SensitiveInformationDetections section of the log)

DetectedValues

An array of sensitive information that was detected.
  • Name
  • Value
  • DLP sensitive data is only available in the activity feed API to users that have been granted "Read DLP sensitive data" permissions.
  • Example from our tenant API (Teams DLP event):
Walid_Elmorsy_0-1636686147548.png

 

ResultsTruncated

Indicates if the logs were truncated due to large number of results.
  • True
  • False
  • DLP sensitive data is only available in the activity feed API to users that have been granted "Read DLP sensitive data" permissions.
  • See example above

DLP-Specific Extended SENSITIVE Schema (the ExceptionInfo section of the log)

Reason

For a DLPRuleUndo event, which indicates why the rule no longer applies.
  • Override
  • Document Change
  • Policy Change
  • DLP sensitive data is only available in the activity feed API to users that have been granted "Read DLP sensitive data" permissions.
  • Example from our tenant API (Teams DLP event):
Walid_Elmorsy_1-1636686147550.png

 

Justification

If the user chose to override policy, any user-specified justification is captured here.
  • String of text
  • DLP sensitive data is only available in the activity feed API to users that have been granted "Read DLP sensitive data" permissions.
  • See example above

Rules

A collection of GUIDs for each rule that was designated as a false positive or override, or for which an action was undone.
  • DLP Rule GUID(s)
  • DLP sensitive data is only available in the activity feed API to users that have been granted "Read DLP sensitive data" permissions.
  • See example above

 

MIP/DLP in Office 365 Management API

So before knowing how to retrieve MIP and DLP logs via Office 365 Management API queries, we need to know first, where to look for them.

Below is a summary of each of the Office 365 Management API content blobs and what operations they contain. Please use this as a reference whenever you are performing a log search for a specific activity event for MIP and/or DLP.

 

Content Blob

Operation

Notes

Audit.AzureActiveDirectory
  • UserLoggedIn

Very useful in general for any investigation or reporting purposes.

Audit.Exchange
  • MIPLabel
  • DLPRuleMatch
  • AutoSensitivityLabelRuleMatch

 

Audit.SharePoint
  • DLPRuleMatch
  • DLPRuleUndo
  • DlpInfo
  • FileSensitivityLabelChanged
  • FileSensitivityLabelChanged is applicable to a document using:
    • Office on the Web

Audit.General
  • SensitivityLabelApplied
  • SensitivityLabelUpdated
  • SensitivityLabelChanged
  • SensitivityLabelRemoved
  • SensitivityLabeledFileOpened
  • SensitivityLabeledFileApplied
  • SensitivityLabeledFileRenamed
  • SensitivityLabeledFileRemoved
  • FileSensitivityLabelChanged
  • AutoSensitivityLabelRuleMatch
  • DLPRuleMatch
  • DLPRuleUndo
  • DlpInfo
  • SensitivityLabelApplied, SensitivityLabelChanged, SensitivityLabelRemoved are applicable to:
    • SPO/Teams sites
    • Emails and files activities from Microsoft 365 Apps Only
  • SensitivityLabelUpdated is applicable to a document using:
    • Microsoft 365 Apps.
  • SensitivityLabeledFileChanged is applicable to a document using:
    • Office on the Web
    • Auto-labelling policy.
  • SensitivityLabeledFileRemoved is applicable to a document using:
  • SensitivityLabeledFileOpened is applicable to a document using:
    • Microsoft 365 Apps

DLP.All
  • DLPRuleMatch
  • DLPRuleUndo
  • DlpInfo
  • MIPLabel

DLP events may include sensitive data (if configured)

 

Querying Management API

In this section, we will go over the configuration details in depth to prepare the environment before performing any API queries. As well as the "Compliance API" script that we have created to help querying and exporting the Microsoft 365 audit log activities via Office 365 management API.

 

Register your application in Azure AD

In order to be able to query the Office 365 Management API endpoints, you will need to configure your application with the right permissions. For a step-by-step guide, please visit the Microsoft official documentation here for more details.

 

Compliance-API Script

We have created a sample Office Management API script that enables administrators to access their tenant management API service (given all the prerequisites steps above have been completed). The script uses a few variables that you will need to update to be able to use it in your tenant (explained below). Also, the script mainly uses the “Get” function to export the log activities to a bunch of JSON files from the main 5 content blobs that we need. Now, let’s go through the script.

Script facts

  • We highly recommend using this script and testing it first in your testing environment. If you need to use it in your production environment, consider removing the hard-coded variables (as shown below) from the script. It is highly NOT RECOMMENDED to keep any passwords, secrets, etc. within files or scripts on endpoints. You may consider using secure string or Azure Key Vault with Azure functions/variables.
  • The script exports the log data to JSON files as mentioned, due to the extensive information and attributes for each log event. The aim was to export all the Microsoft 365 audit logs so that they suit everyone's needs (not only for MIP and DLP). For example, if there are MIG, eDiscovery, or Communication Compliance audit logs, these will be exported too. Further customization can be done to the script if needed to narrow the export scope, by applying export filters (i.e., Operation -eq, etc.). So, it is up to you to use it the way that works best for you.
  • The script checks content availability (i.e., notifications) that became available today, which means from 12:00 AM UTC to the current time. If you want to specify a different period (keeping in mind that the maximum period for which you can query is 24 hours), you can add the starttime and endtime parameters in the script to the URI in the last 24 hours from the time runs. Like the below (don’t forget to define the starttime and endtime parameters):

 

 

Invoke-WebRequest -Method GET -Headers $OfficeToken -Uri "$BaseURI/content?contentType=$Subscription&startTime=$Date022T00:00&endTime=$Date022T23:59&PublisherIdentifier=$TenantGUID" ErrorAction Stop

 

 

 

 

Script variables

The script defined variables are depicted below, you will need to update the following:

 

 

 

•$AppClientID = " The Azure AD registered application ID "
•$ClientSecretValue = " The application secret Value"
•$TenantGUID = " Tenant ID – you can get it from Azure AD portal"
•$tenantdomain = " Tenantname.onmicrosoft.com"
•$OutputPath = "Logs folder path – i.e., C:\APILogs"
•$APIResource = Endpoint URI ($Enterprise, $GCC, $GCCH, $DOD)

 

 

 

MIP/DLP PowerBI (PBI) Reports

So now we have the MIP/DLP logs exported via the Office 365 management API to JSON files, what can we do with them?. We can use those JSON files in various ways, such as:

  • Import them to your 3rd party SIEM solution for reporting and analysis.
  • Use 3rd JSON reading tools to export/convert to other formats for further analysis.
  • Use PowerBI to create reports based on the data in those files.

Here we will show you an example on how to use PowerBI Desktop tool to create MIP/DLP audit report. We have selected to create a report for DLP policy incidents in the last 24 hours within our tenant

Configuration steps

  • Download the PowerBI Desktop client from here then install it on your machine. Run the client once the install is complete.
  • Once the client is running, click on File, then Get Data, then click on Get data to get started

Walid_Elmorsy_0-1636690526624.png

 

  • In the Get Data page, select JSON from the list, then click Connect

Walid_Elmorsy_1-1636690526635.png

 

  • Select the JSON file(s) that you would like to create a report for, then click Open

Walid_Elmorsy_2-1636690526644.png

 

  • The Power Query editor page will open. Here you can modify the JSON file results’ view and data. You can rename column headers, remove columns/rows, and expand an array data into values to name a few.  For our report, this is what we have decided to do:
    • We have filtered the “operation” column to just show “DLPRuleMatch” and “DLPRuleUndo” operations

Walid_Elmorsy_3-1636690526647.png

 

  • We have expanded all the “list” items to their original headers and values. The “list” items are the data into the complex (i.e., array) part within the audit log. Then we will select to show only the “PolicyName” and “Rules” headers.

   Walid_Elmorsy_5-1636690526651.png

 

Walid_Elmorsy_4-1636690526649.png

  • We will also expand the “Rules” data and show the ones selected below

Walid_Elmorsy_6-1636690526654.png

 

Walid_Elmorsy_7-1636690526661.png

 

  • Then click on the close and apply to exit the query editor.

Walid_Elmorsy_8-1636690526670.png

Report examples

  • From the visualizations section, select the visualization that you would like to use, then drag and drop fields that you would like to create a report for. Below is what we have chosen to configure for our DLP incidents reporting:
    • A simple report to report on DLP incidents in the last 24 hours, per workload, per DLP policy:  

Walid_Elmorsy_9-1636690526672.png

 

 

 

  • This report shows the number of DLP incidents, per user, per workload, per DLP policy:

Walid_Elmorsy_10-1636690526674.png

 

 

  • The last one has more details. This shows the DLP incident severity, per DLP Policy, per user, with visual count on bars, per workload (in the tooltip):

 

 

Walid_Elmorsy_12-1636690526678.png

 

References

Additional resources

MIP & Compliance One Stop Shop Resource Page: https://aka.ms/mipc/OSS

Read all the latest MIP updates and blogs at: https://aka.ms/MIPblog

Join MIP & Compliance preview programs at: https://aka.ms/MIPC/Previews

 

Thank you.

 

15 Comments
Co-Authors
Version history
Last update:
‎Nov 16 2021 10:46 AM
Updated by:
Labels