Collect data from Defender for O365

See the changelog of the HTTP Listener here.

Overview

The following article outlines a basic data flow from Microsoft Defender for Office 365 (MDO) to the Office 365 Listener.

Prerequisites

• Administrative access to the Microsoft Defender portal

Contact Onum to get the required JWT token, which will be needed on the Listener setup.

You can also contact us if you cannot generate the required TLS certificates. Note that these certificates must be signed by a recognized Certificate Authority (CA). Self-signed certificates are not accepted.

Defender for Cloud Apps Setup

Microsoft Defender for Office 356 (MDO) can be configured to send logs to Onum. Here's how to set it up:

1. Access the Microsoft Defender for Office 365 portal.

2. Go to Azure Active Directory > App registrations

   • Click New registration and give it a name.

   • Supported account type - Accounts in this organizational directory only

   • Redirect URI - Leave blank for now

   • Click "Register"

3. Retrieve the Application (Client) ID

   • Go to the All Applications tab and click on the application name.

   • On the overview page, you'll see "Application (client) ID" displayed prominently. This is the GUID you need for Onum.

4. In your new app registration, go to API permissions

   • Click Add a permission and select Microsoft Graph > Application permissions

   • Add these permissions

     • SecurityEvents.Read.All

     • SecurityEvents.ReadWrite.All

     • SecurityIncident.Read.All

     • ThreatIntelligence.Read.All

   • For Office 365 Management API, add

     • ActivityFeed.Read

     • ActivityFeed.ReadDlp

     • ServiceHealth.Read

   • Click Grant admin consent

5. Create a client secret

   • Go to Certificates & secrets

   • Click New client secret

   • Add a description and select expiration

   • Copy the secret value immediately (it won't be shown again)

6. Locate and save your Tenant ID

   • Go to Azure Active Directory > App registrations

   • On the Azure AD overview page, look for Tenant ID in the basic information section. It will be displayed as a GUID (e.g., 12a34567-89b0-12c3-d456-789012ef3456).

   • Keep it somewhere safe to paste it into the Listener.

Start/stop a subscription

The Office 365 Listener supports the start/stop subscription feature. You can start/stop a subscription using some other Office 365 API or using this curl command:

curl -d "client_secret={client_secret}&resource={resource}&client_id={app_id}&grant_type=client_credentials" -X POST https://login.windows.net/{tenantID}/oauth2/token

You should get a response like this:

{
    "token_type": "Bearer",
    "expires_in": "string",
    "ext_expires_in": "string",
    "expires_on": "string",
    "not_before": "string",
    "resource": "string",
    "access_token": "string"
}

Use the access_token value to start or stop a subscription. These are the available content values:

• Audit.AzureActiveDirectory

• Audit.Exchange

• Audit.SharePoint

• Audit.General

• DLP.All

These are some of the requests you can perform:

• Start a subscription to begin receiving notifications and retrieving activity data for a tenant.

curl -d "" -H "Authorization: Bearer {access_token}" -X POST "https://manage.office.com/api/v1.0/{tenant_id}/activity/feed/subscriptions/start?contentType={list_of_content_type_you_wanna_subscribe_to}"

• Stop a subscription to discontinue retrieving data for a tenant:

curl -d "" -H "Authorization: Bearer {access_token}" -X POST "https://manage.office.com/api/v1.0/{tenant_id}/activity/feed/subscriptions/stop?contentType={list_of_content_type_you_wanna_unsubscribe_from}"

• Content type example (this will subscribe you to active directory and exchange):

contentType=Audit.AzureActiveDirectory,Audit.Exchange

Here is the list of all the API requests you can use. Once you start subscription, you can use the Listener to fetch your data.

For easier testing, here is the curl command to fetch the list of updates:

curl -d "" -H "Authorization: Bearer {access_token}" -X GET "https://manage.office.com/api/v1.0/{tenant_id}/activity/feed/subscriptions/content?contentType={list_of_content_types}"

Onum Setup

1

Log in to your Onum tenant and click Listeners > New listener.

2

Double-click the Office 365 Listener.

3

Enter a Name for the new Listener. Optionally, add a Description and some Tags to identify the Listener.

4

Enter your defender for O365 Azure Tenant ID*.

5

The Application (client) ID* is needed when accessing Office 365 through APIs or applications. For applications registered in other directories, the Application (Client) ID is located in the application credentials.

6

Assign your data a Content Type in the form of reusable columns, document templates, workflows, or behaviors. Click Add element to add the required content types.

These are the available content values:

• Audit.AzureActiveDirectory

• Audit.Exchange

• Audit.SharePoint

• Audit.General (includes all other workloads not included in the previous content types)

• DLP.All (DLP events only for all workloads)

For details about the events and properties associated with these content types, see Office 365 Management Activity API schema.

7

The Client Secret (also called Application Secret) is used for authentication in Microsoft Entra ID (formerly Azure AD) when accessing APIs. To get it:

1. Click App registrations under the Manage section.

2. Select your registered application.

3. In the left menu, click Certificates & secrets.

4. Under Client secrets, check if an existing secret is available. You cannot view it, so you must have it saved somewhere.

5. If you need a new one, create one and copy the value immediately.

Learn more about secrets in Onum in this article.

8

In Onum, open the Secret field and click New secret to create a new one:

• Give the secret a Name.

• Turn off the Expiration date option.

• Click Add new value and paste the secret corresponding to the JWT token you generated before. Remember that the token will be added in the Microsoft 365 configuration.

• Click Save.

You can now select the secret you just created in the corresponding field.

9

Choose your Subscription Plan* from the list. Find this in the Microsoft Account Portal under Billing > Your Products.

10

Enter the Polling Interval* frequency in minutes with which to grab events. The minimum value is 1, and the maximum value is 60.

11

If you are using a proxy to establish the connection, toggle on the Proxy configuration button and enter the details here.

• Scheme* - Choose the scheme to connect to.

• URL* - The host and port of the proxy URL used to establish the connection

• Username - This is the username used to access the proxy.

• Password - Enter the proxy passcode.

12

Decide whether to skip or require TLS validations to the server.

13

Finally, click Create labels. Optionally, you can set labels to be used for internal Onum routing of data. By default, data will be set as Unlabeled. Click Create listener when you're done.

Learn more about labels in this article.

Click Create listener when you're done.

Ports

The Office 365 Listener has two output ports:

• Default port - Events are sent through this port if no error occurs while processing them.

• Error port - Events are sent through this port if an error occurs while processing them.