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 your managed application in Microsoft Azure AD.

  2. Set up permissions in Microsoft Graph API > Application permissions according to how you want to configure the sensor:

    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

      • Mail.ReadWrite, for deleting emails

      • User.ReadWrite.All, for enforcing password resets and disabling of accounts

        Important

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

        In the Azure AD admin center, navigate to Roles and administratorsUser administrator role > Add assignments, search for the application name used for the GravityZone O365 Mail sensor integration and assign it.

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

        Important

        IdentityRiskyUser.ReadWrite.All requires an Azure AD Premium P2 license. The other permissions do not require Azure AD 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.

  3. Grant Admin consent.

  4. Generate Client secret value.

Note

Learn more about Mail sensor requirements here.

Audit sensor setup
  1. Register your managed application in Microsoft Azure AD.

  2. Set up permissions according to how you want to configure the sensor:

    1. If you want to be able to receive events and also be able to take response actions for O365 incidents directly from GravityZone:

      1. In the Microsoft Graph API > Application permissions section, add the following permissions: User.ReadWrite.All and IdentityRiskyUser.ReadWrite.All.

      2. In the Office 365 Management APIs > Application permissions section, add the following permissions: ActivityFeed.Read, ActivityFeed.ReadDlp and ServiceHealth.Read.

      Important

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

      In the Azure AD admin center, navigate to Roles and administratorsUser administrator role > Add assignments, search for the application name used for the GravityZone O365 Mail sensor integration and assign it.

      Important

      IdentityRiskyUser.ReadWrite.All requires an Azure AD Premium P2 license. The other permissions do not require Azure AD 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, set the following permissions in Office 365 Management APIs > Application permissions: ActivityFeed.Read, ActivityFeed.ReadDlp and ServiceHealth.Read.

  3. Grant Admin consent.

  4. Generate the Client secret value.

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

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

    $ClientID = "client_id"           // @todo replace with your client id, e.g: f5b17a13-6e4e-4c3e-81f4-51fb9a377182
    $ClientSecretValue = "client_secret_value"   // @todo replace with your client secret value, e.g: UOJ7Q~YN5hkilURseLkfRN6~kTQp80Fndn9eJ
    $tenantdomain = "tenant_domain"   // @todo replace with your tenant domain, e.g: [email protected]
    $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=$ClientID;client_secret=$ClientSecretValue}
    $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:

$ClientID = "client_id"           // @todo replace with your client 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: [email protected]
$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=$ClientID;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