Skip to content

Message trace

Overview

Microsoft 365 Message trace follows email messages as they travel through your Exchange Online organization. You can determine if a message was received, rejected, deferred, or delivered by the service. It also shows what actions were taken on the message before it reached its final status. You can use the information from message trace to efficiently answer user questions about what happened to messages, troubleshoot mail flow issues, and validate policy changes (More information on microsoft.com).

The following Sekoia.io built-in rules match the intake Microsoft 365 Message Trace. This documentation is updated automatically and is based solely on the fields used by the intake which are checked against our rules. This means that some rules will be listed but might not be relevant with the intake.

SEKOIA.IO x Microsoft 365 Message Trace on ATT&CK Navigator

SEKOIA.IO Intelligence Feed

Detect threats based on indicators of compromise (IOCs) collected by SEKOIA's Threat and Detection Research team.

  • Effort: elementary

Event Categories

The following table lists the data source offered by this integration.

Data Source Description
Mail server Message trace follows email messages as they travel through your Exchange Online organization.
Email gateway Message trace follows email messages as they travel through your Exchange Online organization.

In details, the following table denotes the type of events produced by this integration.

Name Values
Kind event
Category email
Type info

Event Samples

Find below few samples of events and how they are normalized by Sekoia.io.

{
    "message": "{\"__metadata\": {\"id\": \"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MessageTrace(0)\", \"uri\": \"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MessageTrace(0)\", \"type\": \"TenantReporting.MessageTrace\"}, \"Organization\": \"examplecorp.onmicrosoft.com\", \"MessageId\": \"<3a273efc-cd65-4335-96ec-5f6934f0fb10@az.uksouth.production.microsoft.com>\", \"Received\":\"/Date(1658751973240)/\", \"SenderAddress\": \"azure-noreply@microsoft.com\", \"RecipientAddress\": \"foo.bar@example.corp\", \"Subject\": \"PIM: MessageTrace API service account has the Privileged Role Administrator role\", \"Status\": \"GettingStatus\", \"ToIP\": null, \"FromIP\": \"1.1.1.1\", \"Size\": 87680, \"MessageTraceId\": \"3b4fc661-180d-4c2f-60c9-08da6e38dd10\", \"StartDate\":\"/Date(1658579297628)/\", \"EndDate\":\"/Date(1658752097628)/\", \"Index\": 0}",
    "event": {
        "action": "GettingStatus",
        "category": [
            "email"
        ],
        "kind": "event",
        "type": [
            "info"
        ]
    },
    "@timestamp": "2022-07-25T12:26:13.240000Z",
    "email": {
        "from": {
            "address": [
                "azure-noreply@microsoft.com"
            ]
        },
        "message_id": "<3a273efc-cd65-4335-96ec-5f6934f0fb10@az.uksouth.production.microsoft.com>",
        "subject": "PIM: MessageTrace API service account has the Privileged Role Administrator role",
        "to": {
            "address": [
                "foo.bar@example.corp"
            ]
        }
    },
    "office365": {
        "message_trace": {
            "MessageTraceId": "3b4fc661-180d-4c2f-60c9-08da6e38dd10",
            "Size": 87680
        }
    },
    "organization": {
        "name": "examplecorp.onmicrosoft.com"
    },
    "related": {
        "ip": [
            "1.1.1.1"
        ]
    },
    "source": {
        "address": "1.1.1.1",
        "ip": "1.1.1.1"
    }
}

{
    "message": "{\"__metadata\":{\"id\":\"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MessageTrace(5)\",\"uri\":\"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MessageTrace(5)\",\"type\":\"TenantReporting.MessageTrace\"},\"Organization\":\"abc.onmicrosoft.com\",\"MessageId\":\"<123456@abc-prod2.mcc-soft.com>\",\"Received\":\"/Date(1661344992170)/\",\"SenderAddress\":\"support@abc.com\",\"RecipientAddress\":\"user@abc.fr\",\"Subject\":null,\"Status\":\"Delivered\",\"ToIP\":null,\"FromIP\":null,\"Size\":0,\"MessageTraceId\":\"1203cd7a-18d5-4a92-4343-08da85ce34c9\",\"StartDate\":\"/Date(1661344937835)/\",\"EndDate\":\"/Date(1661344997835)/\",\"Index\":5}\n",
    "event": {
        "action": "Delivered",
        "category": [
            "email"
        ],
        "kind": "event",
        "type": [
            "info"
        ]
    },
    "@timestamp": "2022-08-24T12:43:12.170000Z",
    "email": {
        "from": {
            "address": [
                "support@abc.com"
            ]
        },
        "message_id": "<123456@abc-prod2.mcc-soft.com>",
        "to": {
            "address": [
                "user@abc.fr"
            ]
        }
    },
    "office365": {
        "message_trace": {
            "MessageTraceId": "1203cd7a-18d5-4a92-4343-08da85ce34c9",
            "Size": 0
        }
    },
    "organization": {
        "name": "abc.onmicrosoft.com"
    }
}

Extracted Fields

The following table lists the fields that are extracted, normalized under the ECS format, analyzed and indexed by the parser. It should be noted that infered fields are not listed.

Name Type Description
@timestamp date Date/time when the event originated.
email.from.address keyword The sender's email address.
email.message_id keyword Value from the Message-ID header.
email.subject keyword The subject of the email message.
email.to.address keyword Email address of recipient.
event.action keyword The action captured by the event.
event.category keyword Event category. The second categorization field in the hierarchy.
event.kind keyword The kind of the event. The highest categorization field in the hierarchy.
event.type keyword Event type. The third categorization field in the hierarchy.
office365.message_trace.MessageTraceId keyword An identifier used to get the detailed message transfer trace information.
office365.message_trace.Size number The size of the message, in bytes.
organization.name keyword Organization name.
source.ip ip IP address of the source.

Prerequisite

According to docs.microsoft.com, Message Trace is available to the following plans :

  • Exchange Online Protection
  • Microsoft Defender for Office 365 plan 1 and plan 2
  • Microsoft 365 Defender

In Sekoia.io XDR, create a new intake key using the "Message Trace" format.

Configure OAuth

Collect your Tenant ID from your Azure Portal (for more information read (How to find your Microsoft Entra ID (Azure AD) tenant ID).

Add application:

  1. Azure Portal, navigate to App registrations
  2. Register an application
  3. Name and create your application
  4. Collect the Application (client) ID (client_id) from the Overview page

Create client's secret:

  1. From your newly created client page, navigate to Certificates & secrets
  2. In the Client secrets view
  3. Add a client secret by choosing + New client secret
  4. Once create, copy the secret value (client_secret)

Add required permission:

  1. From your newly created client page, navigate to API permissions
  2. Add a permissions
  3. APIs my organization uses
  4. Office 365 Exchange Online
  5. Application permissions
  6. ReportingWebService.Read.All
  7. Add permissions
  8. To finish, use the Grant admin consent for TENANT_NAME button

Add required role:

  1. From the Microsoft Entra ID (Azure AD) page
  2. Open Roles and administrators
  3. Search and open Global Reader
  4. Use the + Add assignments to add this role to your application

For a detailed explanation, please read the related documentation Azure portal - Assign a role.

You can now create the playbook "Create a new playbook > Create a playbook from scratch" and add the "Office 365 Message Trace OAuth" trigger.

Create a trigger configuration and input the following information:

  • client_id
  • client_secret
  • intake_key
  • tenant_id

Save your configuration and start the trigger.

Configure Basic Auth (Deprecated)

In Microsoft Azure, create a service account with the Reports reader and Security reader rights and a strong password (for more information: MessageTrace report required permissions and About admin roles in the Microsoft 365 admin center).

Once a dedicated service account as been created, you can validate user's rights by running the following command:

curl --user USERNAME:PASSWORD 'https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MessageTrace?$format=json'

This command will contact Microsoft Reporting Web Service API with the provided credentials.

The response should look like this one (you can use | jq to format the response): 

{
  "d": {
    "results": [
      {
        "__metadata": {
          "id": "https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MessageTrace(0)",
          "uri": "https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MessageTrace(0)",
          "type": "TenantReporting.MessageTrace"
        },
        "Organization": "corp.onmicrosoft.com",
        "MessageId": "<123@sender.foo>",
        "Received": "/Date(1659020996164)/",
        "SenderAddress": "sender@mail.sender.foo",
        "RecipientAddress": "user@corp.net",
        "Subject": "Subject",
        "Status": "Delivered",
        "ToIP": null,
        "FromIP": "1.1.1.1",
        "Size": 33435,
        "MessageTraceId": "579cd25c-9b30-4ce4-d5eb-08da70ab3b38",
        "StartDate": "/Date(1658851300604)/",
        "EndDate": "/Date(1659024100604)/",
        "Index": 0
      }
    ]
  }
}

You can now create the playbook "Create a new playbook > Create a playbook from scratch" and add the "Message Trace" trigger.

Create a trigger configuration and input the following information:

  • account_name
  • account_password
  • intake_key

Save your configuration and start the trigger.

Configure time range

Configure the trigger timedelta parameter to pull only events from 24 hours ago (1440 minutes) to be compliant with Microsoft documentation:

Events may be delayed by up to 24 hours before they appear in a report.

Configure the trigger start_time parameter to pull events from X hours ago if you want to import events that happened in the past. You can, for example, pull events from 30 days ago to now as explain in Microsoft documentation:

The information for this report is available for a period of 30 days, or until the subscription is canceled.

Debug

If your user cannot access the MessageTrace API, please visit the Azure Sign-in Logs dashboard and use the Add filters button to filter on the username. You can then choose an authentication event to learn about the issue and use the Launch the Sign-in Diagnostic. button to go further.