Auditing in the MIP File SDK

The unified audit log provides access to audit events. These events show which labels users are applying, manually or automatically, across any applications or services integrated with the Microsoft Information Protection (MIP) SDK. Development partners using the SDK can enable this functionality to surface information from their applications in customer reports.

Enabling Auditing

By default, MIP SDK does not send audit events. Auditing must be enabled in one or more label policies for audit events to fire from MIP SDK-enabled applications.

To send audit data, enable the following advanced setting.

• Add the following policy advanced setting using Security & Compliance Center PowerShell:

  • Key: EnableAudit
  • Value: True

  For example, if your label policy is named "Global":

  Set-LabelPolicy -Identity Global -AdvancedSettings @{EnableAudit="True"}
  

  Note

  By default, this advanced setting isn't present in the policy, and the audit logs aren't sent.

Event Types

There are three types of events that can be submitted via the SDK to Microsoft Purview. Heartbeat events, discovery events, and change events

Heartbeat Events

Heartbeat events are generated automatically for any application integrated with the File SDK. Heartbeat events appear in the unified audit log as AipHeartBeat events. Heartbeat events include:

• TenantId
• Time Generated
• User Principal Name
• Name of the machine where the audit was generated
• Process Name
• Platform
• Application ID - Corresponds to the Microsoft Entra Application ID.

These events are useful in detecting applications across your enterprise that are using the Microsoft Information Protection SDK.

Discovery Events

Discovery events provide information on labeled information read or consumed with the File SDK. These events are useful as they surface the devices, location, and users who are accessing information across an organization. Discovery events appear in the unified audit log as AipDiscover events.

These events are sent to audit, by setting the AuditDiscoveryEnabled parameter to true when creating a new mip::FileHandler. Additionally, a content identifier that identifies the file in some human-readable format is provided. The file path should generally be used for this identifier.

The following example creates a new mip::FileHandler with audit discovery enabled. The CreateFileHandler() method is called on the mip::FileEngine and AuditDiscoveryEnabled set to true. Once the FileHandler reads the label, a discovery audit is generated.

// Create FileHandler with discovery enabled
auto handlerPromise = std::make_shared<std::promise<std::shared_ptr<FileHandler>>>();
auto handlerFuture = handlerPromise->get_future();
fileEngine->CreateFileHandlerAsync(inputFilePath, actualFilePath, true /*AuditDiscoveryEnabled*/, make_shared<FileHandlerObserver>(), createFileHandlerPromise);
auto handler = handlerFuture.get();

// Read label. This generates the discovery audit.
auto label = handler->GetLabel();

Change Events

Change events provide information about the file, the label that was applied or changed, and any justifications provided by the user. Change events are generated by calling NotifyCommitSuccessful() on the mip::FileHandler, after a change is successfully committed to a file. Change events can appear in the unified audit as AipSensitivityLabelAction, AipProtectionAction, or AipFileDeleted.

// Create labeling options, set label
string contentId = "C:\\users\\myuser\\Documents\\MyPlan.docx";
mip::LabelingOptions labelingOptions(mip::AssignmentMethod::PRIVILEGED);
handler->SetLabel(labelId, labelingOptions, mip::ProtectionSettings());
auto commitPromise = std::make_shared<std::promise<bool>>();
auto commitFuture = commitPromise->get_future();

// CommitAsync() returns a bool. If the change was successful, call NotifyCommitSuccessful().
fileHandler->CommitAsync(outputFile, commitPromise);
if(commitFuture.get()) {

    // Submit audit event.
    handler->NotifyCommitSuccessful(contentId);
}