« Microsoft Entra ID 实体分析 Microsoft Exchange Server »
Elastic 文档 ›Elastic 集成 ›Microsoft

Microsoft Exchange Online 邮件跟踪

编辑

Microsoft Exchange Online 邮件跟踪

编辑

版本

1.25.0 (查看全部)

兼容的 Kibana 版本

8.13.0 或更高版本

支持的无服务器项目类型
这是什么？

安全
可观测性

订阅级别
这是什么？

基础版

支持级别
这是什么？

Elastic

此集成用于 Microsoft Exchange Online 邮件跟踪日志。它包括以下数据集，用于通过 Microsoft Exchange Online 邮件跟踪 API 接收日志或从文件读取日志

  • log 数据集：支持 Microsoft Exchange Online 邮件跟踪日志。

基本身份验证弃用通知

编辑

此集成已删除基本身份验证配置字段，因为 Microsoft 已弃用并禁用 Exchange Online 的基本身份验证。有关详细信息，请参阅弃用通知。

Office 365 帐户要求

编辑

至少，您的 Office 365 服务帐户应包含一个具有邮件跟踪和只读收件人权限的角色，并将其分配给将用于集成的 Office 365 用户帐户。使用Exchange 管理中心分配这些权限。

日志

编辑

日志可以通过 rest API 或通过日志文件收集。日志文档

Microsoft Exchange Online 邮件跟踪 API

编辑

log 数据集收集 Microsoft Exchange Online 邮件跟踪日志。要在 Elasticsearch 中搜索提取的日志，您需要使用 datastream.dataset: microsoft_exchange_online_message_trace.log 进行查询。此集成将轮询 Microsoft Exchange Online 邮件跟踪旧版 API (https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MessageTrace) 以提取邮件跟踪日志，并通过提取管道提取它们。

使用 OAuth2 配置

编辑

为了继续使用 Microsoft Exchange Online 邮件跟踪，您需要通过您的服务应用启用和配置 OAuth2 身份验证。

  • [discrete] === 服务应用配置

    1. 在Azure 门户中，创建一个 Microsoft Entra 应用（服务应用）注册。有关详细信息，请参阅官方Microsoft 文档。
    2. 在大多数情况下，在 重定向 URI 部分下，您需要为 应用类型 配置值 Web，并为 重定向 URI 配置 https://127.0.0.1，除非您的终端有一些特定要求。

    3. 为应用程序分配至少一个 Microsoft Entra (Azure AD) 角色，使其能够访问 Reporting Web Service

      • 安全读取者
      • 全局读取者
    4. 应用注册应包含以下 API 权限：Office 365 Exchange Online > ReportingWebService.Read.All（应用程序）。请参阅指定您的应用访问 Reporting Web Service 所需的权限。

  • [discrete] === 配置 OAuth2 凭据

    注册并配置服务应用后，您现在可以按如下方式配置 OAuth2 凭据：-

    1. 为您的注册服务应用生成客户端密码。复制并存储 客户端密码值，因为它将是您的 OAuth2 凭据所必需的。

    2. 使用来自您的已配置的服务应用的适当值填写以下字段：-

      • 客户端 ID：您的服务应用的 client_id，用于在 OAuth 请求参数中传递。
      • 客户端密码：您先前生成的服务应用的 client_secret，用于在 OAuth 请求参数中传递。

      • 租户 ID：您的 Microsoft Entra ID（Azure Active Directory）中服务应用的目录 ID（租户标识符）。

        现在配置了这些值，集成的 OAuth2 配置应该理想地完成。有关详细信息，请查看Reporting Web Service 入门的官方文档。

注意
编辑
  • 对于配置 本地域，您可以查看您的Microsoft 管理 Exchange 中心，了解您的组织中可用的域。它们通常位于 https://admin.exchange.microsoft.com//accepteddomains[接受的域] 和 https://admin.exchange.microsoft.com//remotedomains[远程域] 部分下。
  • 默认的 轮询间隔和 初始间隔值配置为 1 小时，您可以将其更改为您所需的值。初始间隔的回溯值不应超过 200 小时，因为这可能会导致 API 出现意外错误。

  • 默认的 其他回溯时间值配置为 1 小时。这是为了捕获可能由于最终一致性而最初不存在的事件。此值不需要超过24 小时。

    • 注意：此值越大，事件被遗漏的可能性就越小，但是，这将导致集成需要更长的时间来提取所有事件，从而导致较新的事件需要更长的时间才能出现。
  • 批处理大小的默认值设置为 1000。这意味着对于每个请求，Httpjson 将以每页 1000 个结果的值进行分页。邮件跟踪 API 支持的最大页面大小为 2000。当没有更多日志要提取时，API 将返回一个空的 value 数组，并且分页将以可以忽略的错误终止。

日志文件收集

编辑

免责声明：由于现在禁用基本身份验证支持，下面提供的 PowerShell 脚本将无法按原样工作。但是，您可以在此处查看有关如何使用 EXO V2 和 V3 模块使用不同身份验证技术连接到 PowerShell 的指南。结合下面的脚本和指南中提到的备用身份验证方法，您可以像往常一样执行日志文件收集。

以下示例 Powershell 脚本可用于获取日志并将其放入 JSON 文件中，然后该文件可以被日志文件输入使用

先决条件

通过运行以下命令安装 Exchange Online 管理模块

Install-Module -Name ExchangeOnlineManagement

通过运行以下命令导入 Exchange Online 管理模块

Import-Module -Name ExchangeOnlineManagement

必须按照指定的回溯间隔，以一定的间隔触发此脚本。在此示例脚本中，回溯将为 24 小时，因此间隔需要是每天。根据文档，只能获取最多 1k 页。如果这应该是一个问题，请尝试减少 $looback 或增加 $pageSize。

# Username and Password
$username = "[email protected]"
$password = "PASSWORD"
# Lookback in Hours
$lookback = "-24"
# Page Size, should be no problem with 1k
$pageSize = "1000"
# Output of the json file
# This would then be ingested via the integration
$output_location = "C:\temp\messageTrace.json"

$password = ConvertTo-SecureString $password -AsPlainText -Force
$Credential = New-Object System.Management.Automation.PSCredential ($username, $password)
$startDate = (Get-Date).AddHours($lookback)
$endDate = Get-Date

Connect-ExchangeOnline -Credential $Credential
$paginate = 1
$page = 1
$output = @()
while ($paginate -eq 1)
{
    $messageTrace = Get-MessageTrace -PageSize $pageSize -StartDate $startDate -EndDate $endDate -Page $page
    $page
    if (!$messageTrace)
    {
        $paginate = 0
    }
    else
    {
        $page++
        $output = $output + $messageTrace
    }
}
if (Test-Path $output_location)
{
    Remove-Item $output_location
}
foreach ($event in $output)
{
    $event.StartDate = [Xml.XmlConvert]::ToString(($event.StartDate), [Xml.XmlDateTimeSerializationMode]::Utc)
    $event.EndDate = [Xml.XmlConvert]::ToString(($event.EndDate), [Xml.XmlDateTimeSerializationMode]::Utc)
    $event.Received = [Xml.XmlConvert]::ToString(($event.Received), [Xml.XmlDateTimeSerializationMode]::Utc)
    $event = $event | ConvertTo-Json -Compress
    Add-Content $output_location $event -Encoding UTF8
}
示例

log 的示例事件如下

{
    "@timestamp": "2022-10-21T17:25:30.600Z",
    "agent": {
        "ephemeral_id": "1928ec83-7c3a-4ad0-9066-63dae084a2e1",
        "id": "bd32c689-9c8b-44ea-ae34-b04c1bf3fd7d",
        "name": "elastic-agent-75168",
        "type": "filebeat",
        "version": "8.15.3"
    },
    "data_stream": {
        "dataset": "microsoft_exchange_online_message_trace.log",
        "namespace": "89156",
        "type": "logs"
    },
    "destination": {
        "domain": "contoso.com",
        "registered_domain": "contoso.com",
        "top_level_domain": "com",
        "user": {
            "domain": "contoso.com",
            "email": "[email protected]",
            "id": "[email protected]",
            "name": "linus"
        }
    },
    "ecs": {
        "version": "8.11.0"
    },
    "elastic_agent": {
        "id": "bd32c689-9c8b-44ea-ae34-b04c1bf3fd7d",
        "snapshot": false,
        "version": "8.15.3"
    },
    "email": {
        "attachments": {
            "file": {
                "size": 22704
            }
        },
        "delivery_timestamp": "2022-10-21T17:25:30.6006882Z",
        "from": {
            "address": [
                "[email protected]"
            ]
        },
        "local_id": "a6f62809-5cda-4454-0962-08dab38940d6",
        "message_id": "<GVAP278MB037518E76F4082DFE9B607B3DA2D9@GVAP278MB0375.CHEP278.PROD.OUTLOOK.COM>",
        "subject": "testmail 1",
        "to": {
            "address": [
                "[email protected]"
            ]
        }
    },
    "event": {
        "agent_id_status": "verified",
        "category": [
            "email"
        ],
        "created": "2024-11-04T20:39:54.654Z",
        "dataset": "microsoft_exchange_online_message_trace.log",
        "end": "2022-10-22T09:40:10.000Z",
        "ingested": "2024-11-04T20:39:57Z",
        "original": "{\"EndDate\":\"2022-10-22T09:40:10Z\",\"FromIP\":\"40.107.23.81\",\"Index\":1,\"MessageId\":\"\\u003cGVAP278MB037518E76F4082DFE9B607B3DA2D9@GVAP278MB0375.CHEP278.PROD.OUTLOOK.COM\\u003e\",\"MessageTraceId\":\"a6f62809-5cda-4454-0962-08dab38940d6\",\"Organization\":\"contoso.com\",\"Received\":\"2022-10-21T17:25:30.6006882Z\",\"RecipientAddress\":\"[email protected]\",\"SenderAddress\":\"[email protected]\",\"Size\":22704,\"StartDate\":\"2022-10-21T09:40:10Z\",\"Status\":\"Delivered\",\"Subject\":\"testmail 1\",\"ToIP\":null}",
        "outcome": "success",
        "start": "2022-10-21T09:40:10.000Z",
        "type": [
            "info"
        ]
    },
    "input": {
        "type": "httpjson"
    },
    "microsoft": {
        "online_message_trace": {
            "EndDate": "2022-10-22T09:40:10Z",
            "FromIP": "40.107.23.81",
            "Index": 1,
            "MessageId": "<GVAP278MB037518E76F4082DFE9B607B3DA2D9@GVAP278MB0375.CHEP278.PROD.OUTLOOK.COM>",
            "MessageTraceId": "a6f62809-5cda-4454-0962-08dab38940d6",
            "Organization": "contoso.com",
            "Received": "2022-10-21T17:25:30.6006882Z",
            "RecipientAddress": "[email protected]",
            "SenderAddress": "[email protected]",
            "Size": 22704,
            "StartDate": "2022-10-21T09:40:10Z",
            "Status": "Delivered",
            "Subject": "testmail 1"
        }
    },
    "related": {
        "user": [
            "[email protected]",
            "[email protected]",
            "linus",
            "noreply"
        ]
    },
    "source": {
        "domain": "azure.microsoft.com",
        "ip": "40.107.23.81",
        "registered_domain": "microsoft.com",
        "subdomain": "azure",
        "top_level_domain": "com",
        "user": {
            "domain": "azure.microsoft.com",
            "email": "[email protected]",
            "id": "[email protected]",
            "name": "noreply"
        }
    },
    "tags": [
        "preserve_original_event",
        "forwarded"
    ]
}
导出的字段
字段 描述 类型

@timestamp

事件发生时的日期/时间。这是从事件中提取的日期/时间，通常表示事件由源生成的时间。如果事件源没有原始时间戳，则此值通常由管道首次接收事件时填充。所有事件的必填字段。

日期

data_stream.dataset

该字段可以包含任何对表示数据源有意义的内容。示例包括 nginx.access、prometheus、endpoint 等。对于其他方面适合但未设置数据集的数据流，我们将数据集值使用值 "generic"。 event.dataset 应具有与 data_stream.dataset 相同的值。除了上面提到的 Elasticsearch 数据流命名标准之外，dataset 值还有其他限制：* 不能包含 - * 不得超过 100 个字符

constant_keyword

data_stream.namespace

用户定义的命名空间。命名空间对于允许对数据进行分组非常有用。许多用户已经以这种方式组织其索引，并且数据流命名方案现在提供了此最佳实践作为默认值。许多用户将使用 default 填充此字段。如果未使用任何值，则会回退为 default。除了上面提到的 Elasticsearch 索引命名标准之外，namespace 值还有其他限制：* 不能包含 - * 不得超过 100 个字符

constant_keyword

data_stream.type

数据流的总体类型。当前允许的值为 “logs” 和 “metrics”。我们希望在不久的将来还添加 “traces” 和 “synthetics”。

constant_keyword

event.dataset

事件数据集

constant_keyword

input.type

关键字

log.offset

长整型

microsoft.online_message_trace.EndDate

此字段用于限制报告期间。在 $filter 查询选项中使用此字段来设置报告期间的结束日期和时间。如果您在 $filter 选项中提供 EndDate，则还必须提供 StartDate。在此报告中，此字段对应于为邮件记录的最后一个处理步骤的日期和时间。

date_nanos

microsoft.online_message_trace.FromIP

将邮件传输到 Office 365 电子邮件系统的 IPv4 或 IPv6 地址。

关键字

microsoft.online_message_trace.Index

长整型

microsoft.online_message_trace.MessageId

如果提供了邮件的 Internet MessageID 标头。此值也可以显式为空。</p></td>

关键字

microsoft.online_message_trace.MessageTraceId

用于获取详细邮件传输跟踪信息的标识符。</p></td>

关键字

microsoft.online_message_trace.Organization

正在处理电子邮件的完全限定域名。</p></td>

关键字

microsoft.online_message_trace.Received

Office 365 电子邮件系统收到电子邮件的日期和时间。这对应于第一个邮件跟踪详细信息条目的 Date 字段。</p></td>

date_nanos

microsoft.online_message_trace.RecipientAddress

邮件发送到的用户的 SMTP 电子邮件地址。</p></td>

关键字

microsoft.online_message_trace.SenderAddress

据称邮件来自的用户的 SMTP 电子邮件地址。因为发件人地址通常在垃圾邮件中被欺骗，所以它们被认为不是完全可靠的。</p></td>

关键字

microsoft.online_message_trace.Size

邮件的大小（以字节为单位）。

长整型

microsoft.online_message_trace.StartDate

此字段用于限制报告周期。在 $filter 查询选项中使用此字段来设置报告周期的开始日期和时间。如果在 $filter 选项中提供 StartDate，则还必须指定 EndDate。在此报告中，此字段对应于消息记录的第一个处理步骤的日期和时间。</p></td>

date_nanos

microsoft.online_message_trace.Status

消息在 Office 365 电子邮件系统中的状态。这对应于消息记录的最后一个处理步骤的 Detail 字段。</p></td>

关键字

microsoft.online_message_trace.Subject

消息的主题行（如果消息存在主题）。</p></td>

关键字

microsoft.online_message_trace.ToIP

Office 365 电子邮件系统将消息发送到的 IPv4 或 IPv6 地址。</p></td>

关键字

更新日志

编辑
更新日志
版本 详细信息 Kibana 版本

1.25.0

增强 (查看拉取请求)
不要在主摄取管道中删除 event.original。

8.13.0 或更高版本

1.24.0

增强 (查看拉取请求)
为 event.kind 设置为 "pipeline_error" 的文档添加 "preserve_original_event" 标签。

8.13.0 或更高版本

1.23.1

Bug 修复 (查看拉取请求)
改进文档指纹解析。

8.13.0 或更高版本

1.23.0

增强 (查看拉取请求)
为所有事件添加 event.category 和 event.type。

8.13.0 或更高版本

1.22.1

Bug 修复 (查看拉取请求)
阐明配置文档。

8.13.0 或更高版本

1.22.0

增强 (查看拉取请求)
将 kibana 约束更新为 ^8.13.0。修改了字段定义，以删除 ecs@mappings 组件模板中多余的 ECS 字段。

8.13.0 或更高版本

1.21.2

Bug 修复 (查看拉取请求)
修复不使用本地域时模板失败的问题。

8.12.0 或更高版本

1.21.1

Bug 修复 (查看拉取请求)
修复示例事件。

8.12.0 或更高版本

1.21.0

增强 (查看拉取请求)
使 event.outcome 字段符合 ECS 字段定义。

8.12.0 或更高版本

1.20.0

增强 (查看拉取请求)
改进对空响应的处理。

8.12.0 或更高版本

1.19.0

增强 (查看拉取请求)
将敏感值设置为 secret。

8.12.0 或更高版本

1.18.1

增强 (查看拉取请求)
更改所有者

8.7.1 或更高版本

1.18.0

增强 (查看拉取请求)
添加配置附加回溯时间的功能。

Bug 修复 (查看拉取请求)
修复光标可能导致数据间隙的问题。

8.7.1 或更高版本

1.17.2

Bug 修复 (查看拉取请求)
修复 exclude_files 模式。

8.7.1 或更高版本

1.17.1

Bug 修复 (查看拉取请求)
更新 httpjson 模板以修复由于存在额外的 ] 而导致的破坏性问题。更新了测试参数以适应更改。

8.7.1 或更高版本

1.17.0

增强 (查看拉取请求)
更新 httpjson 模板以正确解析数据，重新编写了文档并更新了默认模板值。

8.7.1 或更高版本

1.16.0

增强 (查看拉取请求)
将请求跟踪器日志计数限制为 5。

8.7.1 或更高版本

1.15.0

增强 (查看拉取请求)
ECS 版本更新至 8.11.0。

8.7.1 或更高版本

1.14.0

增强 (查看拉取请求)
改进 event.original 检查，以避免在设置时出现错误。

8.7.1 或更高版本

1.13.1

Bug 修复 (查看拉取请求)
清理了文档，并修复了 scope & login_url 的默认值。

8.7.1 或更高版本

1.13.0

增强 (查看拉取请求)
ECS 版本更新至 8.10.0。

8.7.1 或更高版本

1.12.0

增强 (查看拉取请求)
包清单中的 format_version 从 2.11.0 更改为 3.0.0。从包清单中删除了带点的 YAML 键。将 owner.type: elastic 添加到包清单中。

8.7.1 或更高版本

1.11.0

增强 (查看拉取请求)
添加 tags.yml 文件，以便使用“安全解决方案”标记集成的仪表板和已保存的搜索，并在安全解决方案 UI 中显示。

8.7.1 或更高版本

1.10.0

增强 (查看拉取请求)
将包更新到 ECS 8.9.0。

8.7.1 或更高版本

1.9.0

增强 (查看拉取请求)
记录持续时间单位。

8.7.1 或更高版本

1.8.0

增强 (查看拉取请求)
将 package-spec 更新到 2.9.0。

8.7.1 或更高版本

1.7.0

增强 (查看拉取请求)
将仪表板转换为 Lens。

8.7.1 或更高版本

1.6.0

增强 (查看拉取请求)
记录有效的持续时间单位。

8.7.1 或更高版本

1.5.0

增强 (查看拉取请求)
确保为管道错误正确设置 event.kind。

8.7.1 或更高版本

1.4.0

增强 (查看拉取请求)
将包更新到 ECS 8.8.0。

8.7.1 或更高版本

1.3.0

增强 (查看拉取请求)
添加一个新标志以启用请求跟踪

8.7.1 或更高版本

1.2.0

增强 (查看拉取请求)
将包更新到 ECS 8.7.0。

8.0.0 或更高版本

1.1.0

增强 (查看拉取请求)
弃用了基本身份验证字段，并添加了对 OAuth2 的支持。

8.0.0 或更高版本

1.0.0

增强 (查看拉取请求)
正式发布 Microsoft Exchange Online 邮件跟踪。

8.0.0 或更高版本

0.4.1

增强 (查看拉取请求)
添加了类别和/或子类别。

—

0.4.0

增强 (查看拉取请求)
添加了配置 request.timeout 的功能

Bug 修复 (查看拉取请求)
添加缺少的 event.created 和 event.start ECS 映射

—

0.3.0

增强 (查看拉取请求)
以结构化格式保留原始数据。

增强 (查看拉取请求)
将字段映射到 ECS。

—

0.2.0

增强 (查看拉取请求)
将包更新到 ECS 8.6.0。

—

0.1.0

增强 (查看拉取请求)
将包更新到 ECS 8.5.0。

—

0.0.1

增强 (查看拉取请求)
Microsoft Exchange Online 邮件跟踪日志包的初始草案

—
« Microsoft Entra ID 实体分析 Microsoft Exchange Server »