Skip to main content

The Office 365 sensors

The Microsoft Office 365 platform includes the Mail and Audit sensors, which enhance the XDR detections with data about email traffic and content, as well as user and admin operations retrieved from the Microsoft 365 unified audit log.

  • The Mail sensor accesses events such as when mail items were accessed, when mail items were replied to and forwarded, and when and what a user searched for in Exchange Online and SharePoint Online.

  • The Audit sensor accesses user and admin operations performed in Microsoft 365 services and solutions. These operations are captured, recorded, and retained in your organization's unified audit log.

O365 Prerequisites

Before you integrate the Office 365 sensor platform with GravityZone, you must configure the Mail and Audit sensors.

Mail sensor setup

  1. Register a Microsoft Entra application.

    The app registration's Overview page should be displayed.

  2. Set up the required permissions for the Microsoft Entra application:

    1. Click API permissions > Add a permission.

      add_permision_cp_1416445_en.png

    2. Click Microsoft APIs > Microsoft Graph.

      microsoft-graph_cp_1416445_en.png

    3. Select Application permissions.

      app_permission_cp_1416445_en.png

    4. Under Select permissions, select the permissions the app should have, according to how you want to configure the sensor integration:

      1. If you want to be able to receive events and also be able to take response actions for O365 incidents directly from GravityZone, the following permissions are needed:

        • AuditLog.Read.All. Allows the XDR sensor to read and query your audit log activities.

        • Mail.ReadWrite. Allows the security analysts to take response actions on email resources involved in XDR incidents.

        • User.ReadWrite.All, User.EnableDisableAccount.All. Allows the security analysts to disable user accounts involved in XDR incidents.

        • User.ReadWrite.All, User.RevokeSessions.All. Allows the security analysts to force password resets for user accounts involved in XDR incidents.

        • IdentityRiskyUser.ReadWrite.All, for marking a user account as compromised

          Important

          IdentityRiskyUser.ReadWrite.All becomes available only if at least one user who owns the Microsoft Entra application has a Microsoft Entra Premium P2 license. The other permissions do not require Microsoft Entra Premium licensing.

      2. If you only want to be able to receive events but not take response actions for O365 incidents directly from GravityZone incidents, the following permissions are sufficient: AuditLog.Read.All, Mail.Read and User.Read.All.

    5. Click Add permissions.

    Note

    For more information on adding permissions to access Microsoft Graph, refer to Add permissions to access Microsoft Graph.

  3. Grant Admin consent.

  4. To enforce password resets on O365 accounts directly from GravityZone XDR incidents, you must assign the User administrator role to the Microsoft Entra app.

    In the Microsoft Entra admin center, navigate to Roles & admins > User Administrator role > Add assignments, search for the application name used for the GravityZone O365 Mail sensor integration, and assign it.

  5. Generate client secret value.

Note

Learn more about Mail sensor requirements here.

Audit sensor setup

  1. Register a Microsoft Entra application.

  2. Set up the required permissions for the Microsoft Entra application:

    1. Click API permissions > Add a permission.

      add_permision_cp_1416445_en.png

    2. Click Microsoft APIs > Microsoft Graph.

      microsoft-graph_cp_1416445_en.png

    3. Select Application permissions.

      app_permission_cp_1416445_en.png

    4. Under Select permissions, select the permissions the app should have, according to how you want to configure the sensor integration:

      1. If you want to be able to receive events and also be able to take response actions for O365 incidents directly from GravityZone, add the following permissions: User.ReadWrite.All, Sites.Read.All, and IdentityRiskyUser.ReadWrite.All.

        Important

        IdentityRiskyUser.ReadWrite.All becomes available only if at least one user who owns the Microsoft Entra application has a Microsoft Entra Premium P2 license. The other permissions do not require Microsoft Entra Premium licensing.

      2. If you only want to be able to receive events but not take response actions for O365 incidents directly from GravityZone incidents, add the Sites.Read.All permission.

    5. Click Add permissions.

    6. Click API permissions > Add a permission.

      add_permision_cp_1416445_en.png

    7. Click Microsoft APIs > Office 365 Management APIs.

    8. Select Application permissions.

    9. Under Select permissions, select the permissions the app should have: ActivityFeed.Read, ActivityFeed.ReadDlp, and ServiceHealth.Read.

    10. Click Add permissions.

  3. Grant Admin consent.

  4. Generate the client secret value.

  5. To enforce password resets on O365 accounts directly from GravityZone XDR incidents, you must assign the User administrator role to the Microsoft Entra app.

    In the Microsoft Entra admin center, navigate to Roles & admins > User administrator role > Add assignments, search for the application name used for the GravityZone O365 Audit sensor integration, and assign it.

  6. Navigate to Microsoft Compliance > Audit and start recording user and admin activity.

  7. Enable the Audit.AzureActiveDirectory, Audit.Exchange, Audit.General, Audit.SharePoint, and DLP.All subscriptions by running the PowerShell script below. Make sure you replace the values in the first four lines of code:

    $ApplicationID = "application_id"           // @todo replace with your application id, e.g: f5b17a13-6e4e-4c3e-81f4-51fb9a377182
$ClientSecret = "client_secret"   // @todo replace with your client secret, e.g: UOJ7Q~YN5hkilURseLkfRN6~kTQp80Fndn9eJ
$tenantdomain = "tenant_domain"   // @todo replace with your tenant domain, e.g: tenantname.onmicrosoft.com
$TenantGUID = "tenant_guid"		  // @todo replace with your tenant guid,  e.g: ac593d47-7293-47ed-a8fc-c5824d38673a


$body = @{grant_type="client_credentials";resource="https://manage.office.com";client_id=$ApplicationID;client_secret=$ClientSecret}
$oauth = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$TenantGUID/oauth2/token?api-version=1.0" -Body $body
$headerParams = @{'Authorization'="$($oauth.token_type) $($oauth.access_token)"}

$p = @{
    "webhook"= $null
}

Invoke-WebRequest "https://manage.office.com/api/v1.0/$TenantGUID/activity/feed/subscriptions/start?contentType=Audit.AzureActiveDirectory" -Headers $headerParams -Method POST -Body $p -UseBasicParsing
Invoke-WebRequest "https://manage.office.com/api/v1.0/$TenantGUID/activity/feed/subscriptions/start?contentType=Audit.Exchange" -Headers $headerParams -Method POST -Body $p -UseBasicParsing
Invoke-WebRequest "https://manage.office.com/api/v1.0/$TenantGUID/activity/feed/subscriptions/start?contentType=Audit.SharePoint" -Headers $headerParams -Method POST -Body $p -UseBasicParsing
Invoke-WebRequest "https://manage.office.com/api/v1.0/$TenantGUID/activity/feed/subscriptions/start?contentType=Audit.General" -Headers $headerParams -Method POST -Body $p -UseBasicParsing
Invoke-WebRequest "https://manage.office.com/api/v1.0/$TenantGUID/activity/feed/subscriptions/start?contentType=DLP.All" -Headers $headerParams -Method POST -Body $p -UseBasicParsing

Note

It might take up to 24 hours for the systems to synchronize and send data.

Learn more about Audit sensor requirements here.

Setting up Office 365 sensors

To configure the Mail and Audit sensors, follow these steps:

  1. In the Configuration > Sensors Management page, click Add new to integrate a new sensor platform.

  2. Select the Office 365 sensor platform and click Integrate.

  3. On the Check requirements page, confirm that the prerequisite steps have been completed.

  4. Name your sensor integration.

  5. Fill out your Office 365 credentials: Application ID, Tenant ID, and Client Secret value.

  6. Click Test connectivity to make sure the link between the Office 365 platform and GravityZone is working properly.

    O365 sensor setup

  7. Click APPLY to save the sensor integration setup.

    The new integration will be available in the Sensors Management grid, with the status: Active.

Troubleshooting

If the integration is not successful, you can use the PowerShell below to enable the following subscriptions:

  • Audit.AzureActiveDirectory

  • Audit.Exchange

  • Audit.General

  • Audit.SharePoint

  • DLP.All

Replace the values in the first four lines of code, and run the script:

$ApplicationID = "application_id"           // @todo replace with your application id, e.g: f5b17a13-6e4e-4c3e-81f4-51fb9a377182
$ClientSecret = "client_secret"   // @todo replace with your client secret, e.g: UOJ7Q~YN5hkilURseLkfRN6~kTQp80Fndn9eJ
$tenantdomain = "tenant_domain"   // @todo replace with your tenant domain, e.g: tenantname.onmicrosoft.com
$TenantGUID = "tenant_guid"		  // @todo replace with your tenant guid, e.g: ac593d47-7293-47ed-a8fc-c5824d38673a


$body = @{grant_type="client_credentials";resource="https://manage.office.com";client_id=$ApplicationID;client_secret=$ClientSecret} 
$oauth = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$TenantGUID/oauth2/token?api-version=1.0" -Body $body
$headerParams = @{'Authorization'="$($oauth.token_type) $($oauth.access_token)"}

$p = @{
    "webhook"= $null
}

Invoke-WebRequest "https://manage.office.com/api/v1.0/$TenantGUID/activity/feed/subscriptions/start?contentType=Audit.AzureActiveDirectory" -Headers $headerParams -Method POST -Body $p -UseBasicParsing 
Invoke-WebRequest "https://manage.office.com/api/v1.0/$TenantGUID/activity/feed/subscriptions/start?contentType=Audit.Exchange" -Headers $headerParams -Method POST -Body $p -UseBasicParsing 
Invoke-WebRequest "https://manage.office.com/api/v1.0/$TenantGUID/activity/feed/subscriptions/start?contentType=Audit.SharePoint" -Headers $headerParams -Method POST -Body $p -UseBasicParsing 
Invoke-WebRequest "https://manage.office.com/api/v1.0/$TenantGUID/activity/feed/subscriptions/start?contentType=Audit.General" -Headers $headerParams -Method POST -Body $p -UseBasicParsing 
Invoke-WebRequest "https://manage.office.com/api/v1.0/$TenantGUID/activity/feed/subscriptions/start?contentType=DLP.All" -Headers $headerParams -Method POST -Body $p -UseBasicParsing
In this section: