Auditing in the MIP SDK

The Microsoft Purview portal provides access to audit reports through Activity explorer. These reports provide visibility into the labels that users apply, manually or automatically, across any applications that integrate the MIP SDK. Development partners that use the SDK can enable this functionality, which lets information from their applications surface in customer reports.

Event types

The SDK can send three types of audit events: heartbeat events, discovery events, and change events.

Heartbeat events

The SDK automatically generates heartbeat events for any application that integrates the Policy SDK. Heartbeat events include:

  • TenantId
  • Time generated
  • User principal name
  • Name of the machine that generated the audit
  • Process name
  • Platform
  • Application ID - corresponds to the Microsoft Entra application ID

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

Discovery events

Discovery events provide information on labeled content that the Policy SDK reads or consumes. These events are useful as they surface the devices, location, and users who access information across an organization.

To generate discovery events in the Policy SDK, set a flag when you create the mip::PolicyHandler object. In the following example, the value for isAuditDiscoveryEnabled is set to true. When you pass mip::ExecutionState to ComputeActions() or GetSensitivityLabel() (with existing metadata information and content identifier), the SDK submits discovery information to Microsoft Purview Activity explorer.

The SDK generates the discovery audit after the application calls ComputeActions() or GetSensitivityLabel() and provides mip::ExecutionState. The SDK generates this event only once per handler.

Review the mip::ExecutionState concepts documentation for more details on execution state.

// Create PolicyHandler, passing in true for isAuditDiscoveryEnabled
auto handler = mEngine->CreatePolicyHandler(true);

// Returns vector of mip::Action and generates discovery event.
auto actions = handler->ComputeActions(*state);

//Or, get the label for a given state
auto label = handler->GetSensitivityLabel(*state);

In practice, set isAuditDiscoveryEnabled to true during mip::PolicyHandler construction to allow file access information to flow to Activity explorer.

Change event

Change events provide information about the file, the label that was applied or changed, and any justifications provided by the user. To generate change events, call NotifyCommittedActions() on mip::PolicyHandler. Make the call after the application successfully commits a change to a file, passing in the mip::ExecutionState that computed the actions.

Note

If the application fails to call this function, no audit events are sent.

handler->NotifyCommittedActions(*state);

Audit dashboard

Audit events sent by the SDK are available in Microsoft Purview Activity explorer.

Next steps

  • Last updated on