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).

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.

Event Samples

Find below few samples of events and how they are normalized by SEKOIA.IO.

{
    "event": {
        "start": "2022-07-23T12:28:17.628000Z",
        "end": "2022-07-25T12:28:17.628000Z",
        "outcome": "success"
    },
    "office365": {
        "message_trace": {
            "MessageTraceId": "3b4fc661-180d-4c2f-60c9-08da6e38dd10",
            "Size": 87680,
            "Status": "GettingStatus"
        }
    },
    "email": {
        "delivery_timestamp": "2022-07-25T12:26:13.240000Z",
        "message_id": "<3a273efc-cd65-4335-96ec-5f6934f0fb10@az.uksouth.production.microsoft.com>",
        "from": {
            "address": "azure-noreply@microsoft.com"
        },
        "to": {
            "address": "foo.bar@example.corp"
        },
        "subject": "PIM: MessageTrace API service account has the Privileged Role Administrator role"
    },
    "source": {
        "ip": "1.1.1.1",
        "address": "1.1.1.1"
    },
    "organization": {
        "name": "examplecorp.onmicrosoft.com"
    },
    "related": {
        "ip": [
            "1.1.1.1"
        ]
    }
}

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
email.delivery_timestamp keyword None
email.from.address keyword None
email.message_id keyword None
email.subject keyword None
email.to.address keyword None
event.end date event.end contains the date when the event ended or when the activity was last observed.
event.start date event.start contains the date when the event started or when the activity was first observed.
office365.message_trace.MessageTraceId keyword None
office365.message_trace.Size number None
office365.message_trace.Status keyword None
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.

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

Configure

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.

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 clic on an authentication event to learn about the issue and use the Launch the Sign-in Diagnostic. button to go further.