Microsoft Purview Audit alert_v2
LAST UPDATED: 11/29/2023
Overview
Microsoft Purview auditing solutions provide an integrated solution to help organizations effectively respond to security events, forensic investigations, internal investigations, and compliance obligations.
D3 SOAR is providing REST operations to function with Microsoft Purview Audit alert_v2.
Microsoft Purview Audit alert_v2 is available for use in:
Known limitations
The $top OData query parameter has a limit of 1000 alerts. It is recommended to use only the $top parameter and not include $skip in your first GET query. For pagination, you may use @odata.nextLink. If $skip is used, it is limited to 500 alerts. For example, if you send a request like "/security/alerts?$top=10&$skip=500", a 200 OK response code will be returned, but a request like "/security/alerts?$top=10&$skip=501" will result in a 400 Bad Request response code. For more information, see Microsoft Graph Security API error responses.
Connection
To connect to Microsoft Purview Audit alert_v2 from D3 SOAR, please follow this part to collect the required information below:
Parameter | Description | Example |
Tenant ID | The tenant ID to authenticate the connection. | h41***-9jW***-*** |
Client ID | The client ID to authenticate the connection. | jz2***-de3-***-aap |
Client Secret | The client secret to authenticate the connection. | atp***C~uc-***-vbh |
API Version | The API version to use for the connection. | v1.0 |
Permission Requirements
Each endpoint in the Microsoft Purview Audit alert_v2 API requires a certain permission scope. The following are required scopes for the commands in this integration:
Command | Office 365 Management APIs (Application Permissions) |
Fetch Event | ActivityFeed.Read, ActivityFeed.ReadDIp, ServiceHealth.Read |
Other permissions: Microsoft Graph: SecurityAlert.Read.All,SecurityEvents.Read.All DLP.All content type subscription | |
Get Audit Log | ActivityFeed.Read, ActivityFeed.ReadDIp |
List Current Subscriptions | ActivityFeed.ReadDIp |
Start Subscription | ActivityFeed.Read |
Stop Subscription | ActivityFeed.Read |
Test Connection | No permission needed |
READER NOTE
For Office 365 Management APIs, the following application permissions are required:
ActivityFeed.Read: This permission allows the application to retrieve activity data for your organization.
ActivityFeed.ReadDlp: This permission enables the application to access activity data related to Data Loss Prevention (DLP)
ServiceHealth.Read: This permission enables the application to read service health information for your organization.
For Microsoft Graph, the following application permissions are required:
SecurityAlert.Read.All: This permission allows the application to read all security alerts without requiring a signed-in user.
SecurityEvents.Read.All: This permission enables the application to access security events for your organization without requiring a signed-in user.
Since D3 SOAR uses the client credential authentication method, these permissions fall under application permissions. To ensure you select the appropriate API permission, please refer to steps 10-12 of Configuring Microsoft Purview Audit alert_v2 to Work with D3 SOAR.
ALERT
To run the Fetch Event command, two types of permissions are required: Office 365 Management APIs and Microsoft Graph. Additionally, the connector must be subscribed to DLP.All content types before running the command. Please refer to the corresponding command reader note for more details.
Configuring Microsoft Purview Audit alert_v2 to Work with D3 SOAR
Log in to the Azure Portal (https://portal.azure.com/).
Navigate to the top search bar, then search and select App registrations.
If you already have created apps, you can use one of them. Skip to step 5 to obtain the Client ID & Tenant ID. If you do not have an app, click + New registration to create one.
Register the application.
Enter an application Name.
For Supported account types, select Accounts in this organizational directory only (<Your Directory Name> only - Single tenant).
Click Register.
In the App Overview tab, copy and save the Application(client) ID and Directory(tenant) ID. They will be required to build the integration connection in D3 SOAR. Navigate to Client credentials, then click Add a certificate or secret.
Click + New Client Secret. Enter a Description for the client secret, and select a client secret expiry period using the Expires dropdown menu. Click Add. Note: The client ID will not be able to access the API resources after the client secret expires. You must renew the client secret to keep the client ID active.
Copy and save the Secret Value. It will be required to build the integration connection in D3 SOAR connection. Note: The created Client Secret can only be viewed once. Store it in a secure location before leaving the page.
Configure the API permissions. Click API permissions on the left navigation menu, then + Add a permission.
Select Microsoft Graph.
Search and select the required Application permissions. After selecting the required permissions, click Add permissions. See Permission Requirements for the required permissions for each command in this integration. Note: This is only required for the Fetch Event command.
Select Office 365 Management APIs.
Select the desired permissions. See Permission Requirements for the required permissions for each command. To run all commands, select all three permissions.
Some permissions may need to be granted admin consent for your directory (d3uat in the sample screenshot) to use. Ensure Grant admin consent for <Your Directory> is checked.
You may see Not granted for <Your Directory> in the status column. Those are the ungranted permissions you want to use. After successfully granting permissions, a green checkmark will appear under the permission status column for the corresponding permissions. If your login account does not have admin privileges, ask your admin to grant consent.
Configuring D3 SOAR to Work with Microsoft Purview Audit alert_v2
Log in to D3 SOAR.
Find the Microsoft Purview Audit alert_v2 integration.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Microsoft Purview Audit alert_v2 in the search box to find the integration, then click it to select it.
Click + New Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Microsoft Purview Audit alert_v2.
Connection Name: The desired name for the connection.
Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
Description (Optional): Add your desired description for the connection.
Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.
Configure User Permissions: Defines which users have access to the connection.
Active: Check the tick box to ensure the connection is available for use.
System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
1. Input your Tenant ID. Refer to step 4 of Configuring Microsoft Purview Audit alert_v2 to Work with D3 SOAR.
2. Input your Client ID.
3. Copy the Client Secret from the Microsoft Purview platform. Refer to step 4 of Configuring Microsoft Purview Audit alert_v2 to Work with D3 SOAR.
4. Input your API Version.Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
Test the connection.
Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
Click OK to close the alert window.
Click + Add to create and add the configured connection.
Commands
Microsoft Purview Audit alert_v2 includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.
Integration API Note
For more information about the Microsoft Purview Audit alert_v2 API, please refer to the Microsoft Purview Audit alert_v2 API reference.
READER NOTE
Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Microsoft Purview Audit alert_v2 to Work with D3 SOAR for details.
Note for Time-related parameters
The input format of time-related parameters may vary based on your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:
Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose your desired date and time format.
After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.
Fetch Event
Returns audit logs from Microsoft Purview as events in D3 SOAR based on the specified criteria.
READER NOTE
To run this command, you must enable the DLP.All subscription to retrieve DLP events. You can enable the subscription using the Start Subscription command.
Run the List Current Subscription command to view your current connector's subscriptions.
Input
Input Parameter | Required/Optional | Description | Example |
Start Time | Required | The start time of the time range to fetch audit logs in UTC time. It is required to either define both the Start Time and End Time parameters or leave both unspecified. Additionally, the time range between the start time and end time must not exceed 24 hours, with the start time preceding the end time, and the start time cannot be more than 7 days from now. If this parameter is not defined, the default start time is 24 hours before now. | 2022-03-15 00:00 |
End Time | Required | The end time of the time range to fetch audit logs in UTC time. It is required to either define both the Start Time and End Time parameters or leave both unspecified. Additionally, the time range between the start time and end time must not exceed 24 hours, with the start time preceding the end time, and the start time cannot be more than 7 days from now. If this parameter is not defined, the default end time is the current time. | 2022-03-16 00:00 |
Top Recent Event Number | Required | The maximum number of the most recent audit logs to fetch. | 10 |
Search Condition | Optional | The query to filter audit logs. For more information about the query syntax, see List alerts - Microsoft Graph v1.0. | serviceSource in ('microsoftDataLossPrevention') |
Auto Start DLP Subscription | Optional | The option to automatically start the DLP subscription if the subscription status is disabled. The default setting is False. | False |
Output
Fetch Event Field Mapping
Please note that Fetch Event commands require event field mapping. Field mapping plays a key role in the data normalization process part of the event pipeline. Field mapping converts the original data fields from the different providers to the D3 fields which are standardized by the D3 Model. Please refer to Event and Incident Intake Field Mapping for details.
If you require a custom field mapping, click +Add Field to add a custom field mapping. You may also remove built-in field mappings by clicking x. Please note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.
As a system integration, the Microsoft Purview Audit alert_v2 integration has some pre-configured field mappings for default field mapping.
Default Event Source
The Default Event Source is the default set of field mappings that are applied when this fetch event command is executed. For out-of-the-box integrations, you will find a set of field mapping provided by the system. Default event source provides field mappings for common fields from fetched events. The default event source has a “Main Event JSON Path” (i.e., $.value) that is used to extract a batch of events from the response raw data. Click Edit Event Source to view the “Main Event JSON Path”.
Main Event JSON Path: $.value
The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...’]) should be used to separate child elements in JSON arrays.
For example, the root node of a JSON Path is value. The child node denoting the Incident ID field would be incidentId. Putting it together, the JSON Path expression to extract the Incident ID is $.value.incidentId.
The pre-configured field mappings are detailed below:
Field Name | Source Field |
Document ID | .id |
Start Time | .createdDateTime |
Event Type | .serviceSource |
Description | .description |
Severity | .severity |
Status | .status |
Alert Name | .title |
Source vendor product name | .detectionSource |
Event category | .category |
Techniques | .mitreTechniques |
Incident ID | .incidentId |
First Activity Time | .firstActivityDateTime |
Last Activity Time | .lastActivityDateTime |
User Evidence | .evidence..userAccount.accountName |
File Evidence | .evidence..fileDetails.fileName |
Email Evidence | .evidence..internetMessageId |
Recipient | .evidence..recipientEmailAddress |
Sender IP | .evidence..senderIp |
File Hash SHA1 | .evidence..fileDetails.sha1 |
File Hash SHA256 | .evidence..fileDetails.sha256 |
READER NOTE
The Unique Event Key field mapping is used to prevent duplicate event ingestions. D3 SOAR will check if the value of a selected JSON path matches any Unique Event Key of previously ingested events. If a match is found, the event will be dismissed. If no match is found, an event will be created. However, if no Unique Event Key is mapped, then the hash value from the event pending ingestion will be used to check for any matches with existing events. If no match is found, the event will be created.
Unlike most other D3 SOAR integrations, the Microsoft Purview Audit alert_v2 integration’s Fetch Event command’s Default Event Source mapping does not include Unique Event Key in order to fetch the same fetched audit log with multiple updates.
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Fetch Event failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is AF20002, some inputs are invalid to run the command. The user or system support would need to check and adjust the input parameters. Refer to the Management Activity API reference > Errors for details. | Status Code: AF20003. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Start time and end time must both be specified (or both omitted) and must be less than or equal to 24 hours apart, with the start time prior to end time and start time no more than 7 days in the past. |
Error Sample Data Fetch Event failed. Status Code: AF20003. Message: Start time and end time must both be specified (or both omitted) and must be less than or equal to 24 hours apart, with the start time prior to end time and start time no more than 7 days in the past. |
Get Audit Log
Retrieves the audit log for the specified content type.
READER NOTE
To run this command, the subscription you select in the Content Type parameter must be enabled. You can enable the desired subscription using the Start Subscription command.
Run the List Current Subscription command to view your current connector's subscriptions.
Input
Input Parameter | Required/Optional | Description | Example |
Content Type | Required | The content type of the audit logs to receive. | Audit.AzureActiveDirectory |
Start Time | Optional | The start time of the time range to fetch events in UTC time. It is required to either define both the Start Time and End Time parameters or leave both unspecified. Additionally, the time range between the start time and end time must not exceed 24 hours, with the start time preceding the end time, and the start time cannot be more than 7 days old. | 2023-03-15 00:00 |
End Time | Optional | The end time of the time range to fetch events in UTC time. It is required to either define both the Start Time and End Time parameters or leave both unspecified. Additionally, the time range between the start time and end time must not exceed 24 hours, with the start time preceding the end time, and the start time cannot be more than 7 days old. | 2023-03-16 00:00 |
User Principal Names | Optional | The principal names of the users to filter and retrieve audit logs. If this parameter is not defined, all users' audit logs will be returned. | [ "*****@*****.com" ] |
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get Audit Log failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is AF20002, some inputs are invalid to run the command. The user or system support would need to check and adjust the input parameters. Refer to the Management Activity API reference > Errors for details. | Status Code: AF20023. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The subscription was disabled. |
Error Sample Data Get Audit Log failed. Status Code: AF20023. Message: The subscription was disabled. |
List Current Subscriptions
Retrieves a collection of the current subscriptions with their associated webhooks.
Input
N/A
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | List Current Subscriptions failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is AF20002, some inputs are invalid to run the command. The user or system support would need to check and adjust the input parameters. Refer to the Management Activity API reference > Errors for details. | Status Code: AF20010. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Application with identifier '0cb****-87ca-4****-b****a52' was not found in the directory '*****'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant. |
Error Sample Data List Current Subscriptions failed. Status Code: AF20010. Message: Application with identifier '0cb****-87ca-4****-b****a52' was not found in the directory '*****'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant. |
Start Subscription
Starts a subscription to the specified content type.
READER NOTE
You can only subscribe to the same content type subscription once. To subscribe again, you must stop the existing subscription by running the Stop Subscription command.
Input
Input Parameter | Required/Optional | Description | Example |
Content Type | Required | The content type to subscribe to. | Audit.AzureActiveDirectory |
Webhook Address | Optional | The HTTPS endpoint to receive notifications. | https://demo.d3soar.com/webhook |
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Start Subscription failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is AF20002, some inputs are invalid to run the command. The user or system support would need to check and adjust the input parameters. Refer to the Management Activity API reference > Errors for details. | Status Code: AF20021. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The webhook endpoint (.j,l) could not be validated. |
Error Sample Data Start Subscription failed. Status Code: AF20021. Message: The webhook endpoint (.j,l) could not be validated. |
Stop Subscription
Stops a subscription to the specified content type.
Input
Input Parameter | Required/Optional | Description | Example |
Content Type | Required | The content type to stop subscribing to. | Audit.AzureActiveDirectory |
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Stop Subscription failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is AF20002, some inputs are invalid to run the command. The user or system support would need to check and adjust the input parameters. Refer to the Management Activity API reference > Errors for details. | Status Code: AF20010. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Application with identifier '0cb****-87ca-4****-b****a52' was not found in the directory '*****'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant. |
Error Sample Data Stop Subscription failed. Status Code: AF20010. Message: Application with identifier '0cb****-87ca-4****-b****a52' was not found in the directory '*****'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant. |
Test Connection
Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.
Input
N/A
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Test Connection failed. Failed to check the connector. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is AF20002, some inputs are invalid to run the command. The user or system support would need to check and adjust the input parameters. Refer to the Management Activity API reference > Errors for details. | Status Code: AF20010. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Application with identifier '0cb****-87ca-4****-b****a52' was not found in the directory '*****'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant. |
Error Sample Data Test Connection failed. Failed to check the connector. Status Code: AF20010. Message: Message: Application with identifier '0cb****-87ca-4****-b****a52' was not found in the directory '*****'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant. |