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).
Related Built-in Rules
Benefit from SEKOIA.IO built-in rules and upgrade Office365 Message Trace with the following detection capabilities out-of-the-box.
SEKOIA.IO x Office365 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": {
"kind": "event",
"category": [
"email"
],
"type": [
"info"
],
"action": "GettingStatus"
},
"@timestamp": "2022-07-25T12:26:13.240000Z",
"office365": {
"message_trace": {
"MessageTraceId": "3b4fc661-180d-4c2f-60c9-08da6e38dd10",
"Size": 87680
}
},
"source": {
"ip": "1.1.1.1",
"address": "1.1.1.1"
},
"email": {
"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"
},
"organization": {
"name": "examplecorp.onmicrosoft.com"
},
"related": {
"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": {
"kind": "event",
"category": [
"email"
],
"type": [
"info"
],
"action": "Delivered"
},
"@timestamp": "2022-08-24T12:43:12.170000Z",
"office365": {
"message_trace": {
"MessageTraceId": "1203cd7a-18d5-4a92-4343-08da85ce34c9",
"Size": 0
}
},
"email": {
"message_id": "<123456@abc-prod2.mcc-soft.com>",
"from": {
"address": [
"support@abc.com"
]
},
"to": {
"address": [
"user@abc.fr"
]
}
},
"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 Azure Active Directory tenant ID).
Add application:
- Azure Portal, navigate to
App registrations
- Register an application
- Name and create your application
- Collect the
Application (client) ID
(client_id) from theOverview
page
Create client's secret:
- From your newly created client page, navigate to
Certificates & secrets
- In the
Client secrets
view - Add a client secret by choosing
+ New client secret
- Once create, copy the secret value (client_secret)
Add required permission:
- From your newly created client page, navigate to
API permissions
Add a permissions
APIs my organization uses
Office 365 Exchange Online
Application permissions
ReportingWebService.Read.All
Add permissions
- To finish, use the
Grant admin consent for TENANT_NAME
button
Add required role:
- From the
Azure Active Directory
page - Open
Roles and administrators
- Search and open
Global Reader
- 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.