› › ›

实体分析输入

编辑

实体分析输入编辑

此功能处于技术预览阶段，可能会在未来版本中更改或删除。 Elastic 将努力修复任何问题，但技术预览版中的功能不受官方 GA 功能支持 SLA 的约束。

实体分析输入从外部身份提供者收集身份资产，例如用户。

支持以下身份提供者

配置选项编辑

entity-analytics 输入支持以下配置选项以及稍后描述的通用选项。

`provider`编辑

身份提供者。必须是以下之一：activedirectory、azure-ad 或 okta。

通用选项编辑

所有输入都支持以下配置选项。

`enabled`编辑

使用 enabled 选项启用和禁用输入。默认情况下，enabled 设置为 true。

`tags`编辑

Filebeat 包含在每个已发布事件的 tags 字段中的标签列表。标签可以轻松地在 Kibana 中选择特定事件或在 Logstash 中应用条件过滤。这些标签将附加到常规配置中指定的标签列表中。

示例

filebeat.inputs:
- type: entity-analytics
  . . .
  tags: ["json"]

`fields`编辑

您可以指定可选字段，以向输出添加其他信息。例如，您可以添加可用于过滤日志数据的字段。字段可以是标量值、数组、字典或它们的任何嵌套组合。默认情况下，您在此处指定的字段将分组在输出文档中的 fields 子字典下。要将自定义字段存储为顶级字段，请将 fields_under_root 选项设置为 true。如果在常规配置中声明了重复字段，则其值将被此处声明的值覆盖。

filebeat.inputs:
- type: entity-analytics
  . . .
  fields:
    app_id: query_engine_12

`fields_under_root`编辑

如果此选项设置为 true，则自定义字段将存储为输出文档中的顶级字段，而不是分组在 fields 子字典下。如果自定义字段名称与 Filebeat 添加的其他字段名称冲突，则自定义字段将覆盖其他字段。

`processors`编辑

要应用于输入数据的处理器列表。

有关在配置中指定处理器的更多信息，请参见 处理器。

`pipeline`编辑

要为此输入生成的事件设置的摄取管道 ID。

管道 ID 也可以在 Elasticsearch 输出中配置，但此选项通常会导致配置文件更简单。如果在输入和输出中都配置了管道，则使用输入中的选项。

`keep_null`编辑

如果此选项设置为 true，则值为 null 的字段将在输出文档中发布。默认情况下，keep_null 设置为 false。

`index`编辑

如果存在，此格式字符串将覆盖此输入事件的索引（对于 elasticsearch 输出），或设置事件元数据的 raw_index 字段（对于其他输出）。此字符串只能引用代理名称和版本以及事件时间戳；要访问动态字段，请使用 output.elasticsearch.index 或处理器。

示例值："%{[agent.name]}-myindex-%{+yyyy.MM.dd}" 可能会扩展为 "filebeat-myindex-2019.11.01"。

`publisher_pipeline.disable_host`编辑

默认情况下，所有事件都包含 host.name。可以将此选项设置为 true 以禁用向所有事件添加此字段。默认值为 false。

提供者编辑

Active Directory (`activedirectory`)编辑

activedirectory 提供者允许输入从 Active Directory 检索用户及其组成员身份。

设置编辑

必须在 Active Directory 服务器管理器中设置具有适当权限的用户，才能使提供程序正常运行。

工作原理编辑

概述编辑

Active Directory 提供者定期查询 Active Directory 服务器，检索用户和组的更新，更新其用户和组元数据以及组成员信息的内部缓存，并将更新后的用户元数据发送到 Elasticsearch。

提取和发送更新在以下两个过程之一中进行：完全同步和 增量更新。完全同步将发送状态下的完整用户列表和组成员身份，以及指示同步事件开始和结束的写入标记。增量更新将仅发送该事件期间已更改用户的数据。对用户的更改可以采用多种形式，无论是对用户元数据的更改、添加或修改了用户，还是更改了组成员身份。

将用户和设备元数据发送到 Elasticsearch编辑

在完全同步期间，状态中存储的所有用户和组都将发送到输出，而增量更新将仅发送已更新的用户和组。完全同步将在写入标记文档的两侧进行绑定，如下所示

{
    "@timestamp": "2022-11-04T09:57:19.786056-05:00",
    "event": {
        "action": "started",
        "start": "2022-11-04T09:57:19.786056-05:00"
    },
    "labels": {
        "identity_source": "activedirectory-1"
    }
}

用户文档将显示用户的当前状态。

示例用户文档

{
    "@timestamp": "2024-02-05T06:37:40.876026-05:00",
    "event": {
        "action": "user-discovered",
    },
    "activedirectory": {
        "id": "CN=Guest,CN=Users,DC=testserver,DC=local",
        "user": {
            "accountExpires": "2185-07-21T23:34:33.709551516Z",
            "badPasswordTime": "0",
            "badPwdCount": "0",
            "cn": "Guest",
            "codePage": "0",
            "countryCode": "0",
            "dSCorePropagationData": [
                "2024-01-22T06:37:40Z",
                "1601-01-01T00:00:01Z"
            ],
            "description": "Built-in account for guest access to the computer/domain",
            "distinguishedName": "CN=Guest,CN=Users,DC=testserver,DC=local",
            "instanceType": "4",
            "isCriticalSystemObject": true,
            "lastLogoff": "0",
            "lastLogon": "2185-07-21T23:34:33.709551616Z",
            "logonCount": "0",
            "memberOf": "CN=Guests,CN=Builtin,DC=testserver,DC=local",
            "name": "Guest",
            "objectCategory": "CN=Person,CN=Schema,CN=Configuration,DC=testserver,DC=local",
            "objectClass": [
                "top",
                "person",
                "organizationalPerson",
                "user"
            ],
            "objectGUID": "hSt/40XJQU6cf+J2XoYMHw==",
            "objectSid": "AQUAAAAAAAUVAAAA0JU2Fq1k30YZ7UPx9QEAAA==",
            "primaryGroupID": "514",
            "pwdLastSet": "2185-07-21T23:34:33.709551616Z",
            "sAMAccountName": "Guest",
            "sAMAccountType": "805306368",
            "uSNChanged": "8197",
            "uSNCreated": "8197",
            "userAccountControl": "66082",
            "whenChanged": "2024-01-22T06:36:59Z",
            "whenCreated": "2024-01-22T06:36:59Z"
        },
        "whenChanged": "2024-01-22T06:36:59Z"
    },
    "user": {
        "id": "CN=Guest,CN=Users,DC=testserver,DC=local"
    },
    "labels": {
        "identity_source": "activedirectory-1"
    }
}

配置编辑

示例配置

filebeat.inputs:
- type: entity-analytics
  enabled: true
  id: activedirectory-1
  provider: activedirectory
  sync_interval: "12h"
  update_interval: "30m"
  ad_url: "ldaps://host.domain.tld"
  ad_base_dn: "CN=Users,DC=SERVER,DC=DOMAIN"
  ad_user: "USERNAME"
  ad_password: "PASSWORD"

azure-ad 提供者支持以下配置

`ad_url`编辑

Active Directory 服务器 URL。此字段是必需的。

`ad_base_dn`编辑

Active Directory 基础可分辨名称。此字段是必需的。

`ad_user`编辑

客户端用户名。用于身份验证。用户必须具有 Active Directory 读取权限。此字段是必需的。

`ad_password`编辑

客户端的密码，用于身份验证。此字段是必需的。

`sync_interval`编辑

应该进行完全同步的时间间隔。该时间间隔必须长于更新时间间隔 (update_interval) 表示为持续时间字符串（例如，1 分钟、3 小时、24 小时）。默认为 24h（24 小时）。

`update_interval`编辑

应该进行增量更新的时间间隔。该时间间隔必须短于完全同步时间间隔 (sync_interval)。表示为持续时间字符串（例如，1 分钟、3 小时、24 小时）。默认为 15m（15 分钟）。

Azure Active Directory (`azure-ad`)编辑

azure-ad 提供者允许输入从 Azure Active Directory (AD) 检索用户及其组成员身份。

设置编辑

需要在 Azure 中授予必要的 API 权限，才能使提供程序正常运行

权限	类型
GroupMember.Read.All	应用程序
User.Read.All	应用程序
Device.Read.All	应用程序

有关如何设置必要的应用程序注册、权限授予和密钥配置的完整指南，请遵循此指南。

工作原理编辑

概述编辑

Azure AD 提供者定期联系 Azure Active Directory，检索用户、设备和组的更新，更新其用户和设备元数据以及组成员信息的内部缓存，并将更新后的用户元数据发送到 Elasticsearch。

提取和发送更新通过以下两种流程之一进行：完全同步 和 增量更新。完全同步将发送状态中的完整用户和设备列表，以及写入标记以指示同步事件的开始和结束。增量更新将仅发送该事件期间已更改的用户和设备的数据。用户或设备的更改可以采用多种形式，无论是用户或设备元数据的更改、添加或删除了用户/设备，还是更改了组成员身份（直接或传递）。

API 交互编辑

提供程序定期从 Microsoft Graph API for Azure Active Directory 检索用户、设备和组元数据的更改。这是通过调用三个 API 端点来完成的

/delta 端点将提供自上次调用以来发生的更改，并通过增量令牌跟踪状态。如果在没有增量令牌的情况下调用 /delta 端点，它将提供用户、设备或组的完整列表，类似于非增量端点。由于可能会返回许多结果，因此使用了一种分页机制。在响应正文中，可能会出现两个字段，@odata.nextLink 和 @odata.deltaLink。

如果返回 @odata.nextLink，则表示还有更多结果需要获取，并且此字段的值将包含应立即获取的 URL。
如果返回 @odata.deltaLink，则表示当前没有更多结果，并且此字段的值（一个 URL）应保存以供下次需要获取更新时使用（增量令牌）。

组元数据将用于使用组成员身份信息丰富用户和设备。将为用户和设备提供直接成员身份以及传递成员身份。

将用户和设备元数据发送到 Elasticsearch编辑

在完全同步期间，状态中存储的所有用户和设备都将发送到输出，而增量更新将仅发送已更新的用户。完全同步将在两侧由写入标记文档 delimit，其外观如下所示

{
    "@timestamp": "2022-11-04T09:57:19.786056-05:00",
    "event": {
        "action": "started",
        "start": "2022-11-04T09:57:19.786056-05:00"
    },
    "labels": {
        "identity_source": "azure-1"
    }
}

用户文档将显示用户的当前状态。

示例用户文档

{
    "@timestamp": "2022-11-04T09:57:19.786056-05:00",
    "event": {
        "action": "user-discovered",
    },
    "azure_ad": {
        "userPrincipalName": "[email protected]",
        "mail": "[email protected]",
        "displayName": "Example User",
        "givenName": "Example",
        "surname": "User",
        "jobTitle": "Software Engineer",
        "mobilePhone": "123-555-1000",
        "businessPhones": ["123-555-0122"]
    },
    "user": {
        "id": "5ebc6a0f-05b7-4f42-9c8a-682bbc75d0fc",
        "group": [
            {
                "id": "331676df-b8fd-4492-82ed-02b927f8dd80",
                "name": "group1"
            },
            {
                "id": "d140978f-d641-4f01-802f-4ecc1acf8935",
                "name": "group2"
            }
        ]
    },
    "labels": {
        "identity_source": "azure-1"
    }
}

设备文档将显示设备的当前状态。

设备文档示例

{
    "@timestamp": "2022-11-04T09:57:19.786056-05:00",
    "event": {
        "action": "device-discovered",
    },
    "azure_ad": {
        "accountEnabled": true,
        "deviceId": "2fbbb8f9-ff67-4a21-b867-a344d18a4198",
        "displayName": "DESKTOP-LETW452G",
        "operatingSystem": "Windows",
        "operatingSystemVersion": "10.0.19043.1337",
        "physicalIds": {
            "extensionAttributes": {
                "extensionAttribute1": "BYOD-Device"
            }
        },
        "alternativeSecurityIds": [
            {
                "type": 2,
                "identityProvider": null,
                "key": "DGFSGHSGGTH345A...35DSFH0A"
            },
        ]
    },
    "device": {
        "id": "adbbe40a-0627-4328-89f1-88cac84dbc7f",
        "group": [
            {
                "id": "331676df-b8fd-4492-82ed-02b927f8dd80",
                "name": "group1"
            }
        ]
        "registered_owners": [
            {
                "id": "5ebc6a0f-05b7-4f42-9c8a-682bbc75d0fc",
                "userPrincipalName": "[email protected]",
                "mail": "[email protected]",
                "displayName": "Example User",
                "givenName": "Example",
                "surname": "User",
                "jobTitle": "Software Engineer",
                "mobilePhone": "123-555-1000",
                "businessPhones": ["123-555-0122"]
            },
        ],
        "registered_users": [
            {
                "id": "5ebc6a0f-05b7-4f42-9c8a-682bbc75d0fc",
                "userPrincipalName": "[email protected]",
                "mail": "[email protected]",
                "displayName": "Example User",
                "givenName": "Example",
                "surname": "User",
                "jobTitle": "Software Engineer",
                "mobilePhone": "123-555-1000",
                "businessPhones": ["123-555-0122"]
            },
        ],
    },
    "labels": {
        "identity_source": "azure-1"
    }
}

配置编辑

示例配置

filebeat.inputs:
- type: entity-analytics
  enabled: true
  id: azure-1
  provider: azure-ad
  dataset: "all"
  sync_interval: "12h"
  update_interval: "30m"
  client_id: "CLIENT_ID"
  tenant_id: "TENANT_ID"
  secret: "SECRET"

azure-ad 提供者支持以下配置

`tenant_id`编辑

租户 ID。此字段为必填字段。

`client_id`编辑

客户端/应用程序 ID。用于身份验证。此字段为必填字段。

`secret`编辑

用于身份验证的密钥值。此字段为必填字段。

`dataset`编辑

要从 API 收集的数据集。可以是“全部”、“用户”或“设备”之一，也可以留空以使用默认行为，即收集所有实体。当 dataset 设置为“设备”时，会收集一些用户实体数据，以便为每个设备填充注册用户和注册所有者字段。

`sync_interval`编辑

`update_interval`编辑

`login_endpoint`编辑

覆盖默认的身份验证登录端点。仅在指示这样做时更改。更改此值还需要更改 login_scopes。

`login_scopes`编辑

覆盖默认的身份验证范围。仅在指示这样做时更改。

`select.users`编辑

覆盖默认的用户查询选择。这是一个可选查询参数列表。默认值为 ["accountEnabled", "userPrincipalName", "mail", "displayName", "givenName", "surname", "jobTitle", "officeLocation", "mobilePhone", "businessPhones"]。

`select.groups`编辑

覆盖默认的组查询选择。这是一个可选查询参数列表。默认值为 ["displayName", "members"]。

`select.devices`编辑

覆盖默认的设备查询选择。这是一个可选查询参数列表。默认值为 ["accountEnabled", "deviceId", "displayName", "operatingSystem", "operatingSystemVersion", "physicalIds", "extensionAttributes", "alternativeSecurityIds"]。

Okta 用户身份 (`okta`)编辑

okta 提供程序允许输入从 Okta 用户 API 检索用户和设备。

设置编辑

需要在 Okta 中授予必要的 API 权限才能使提供程序正常运行。在 Okta 帐户的管理控制台中，导航到“安全”>“API”，并在“令牌”选项卡中单击“创建令牌”按钮以创建新令牌。复制令牌值并保留此值以配置提供程序。请注意，令牌不会再次显示，因此必须立即复制。此值将通过 okta_token 配置字段提供给提供程序。

需要由 Okta 支持激活设备 API 访问权限。

工作原理编辑

概述编辑

Okta 提供程序定期联系 Okta API，检索用户和设备的更新，更新其用户元数据内部缓存，并将更新的用户/设备元数据发送到 Elasticsearch。

提取和发送更新通过以下两种流程之一进行：完全同步 和 增量更新。完全同步将发送状态中的完整用户和设备列表，以及写入标记以指示同步事件的开始和结束。增量更新将仅发送该事件期间已更改的用户和设备的数据。用户或设备的更改可以采用多种形式，无论是用户元数据的更改，还是添加或删除了用户。

API 交互编辑

提供程序定期从 Okta 用户和设备 API 检索用户/设备元数据的更改。这是通过调用以下内容来完成的

提供程序通过保留返回的用户列表中最后记录的更新时间的记录来跟踪更新。在提供程序更新期间，Okta 提供程序利用 Okta API 的查询过滤功能，仅请求在提供程序记录的上次更新时或之后更新的记录。

将用户元数据发送到 Elasticsearch编辑

在完全同步期间，状态中存储的所有用户/设备都将发送到输出，而增量更新将仅发送已更新的用户和设备。完全同步将在两侧由写入标记文档 delimit，其外观如下所示

{
    "@timestamp": "2022-11-04T09:57:19.786056-05:00",
    "event": {
        "action": "started",
        "start": "2022-11-04T09:57:19.786056-05:00"
    },
    "labels": {
        "identity_source": "okta-1"
    }
}

用户文档将显示用户的当前状态。

示例用户文档

{
    "@timestamp": "2023-07-04T09:57:19.786056-05:00",
    "event": {
        "action": "user-discovered",
    },
    "okta": {
        "id": "userid",
        "status": "RECOVERY",
        "created": "2023-06-02T09:33:00.189752+09:30",
        "activated": "0001-01-01T00:00:00Z",
        "statusChanged": "2023-06-02T09:33:00.189752+09:30",
        "lastLogin": "2023-06-02T09:33:00.189752+09:30",
        "lastUpdated": "2023-06-02T09:33:00.189753+09:30",
        "passwordChanged": "2023-06-02T09:33:00.189753+09:30",
        "type": {
            "id": "typeid"
        },
        "profile": {
            "login": "[email protected]",
            "email": "[email protected]",
            "firstName": "name",
            "lastName": "surname"
        },
        "credentials": {
            "password": {},
            "provider": {
                "type": "OKTA",
                "name": "OKTA"
            }
        },
        "_links": {
            "self": {
                "href": "https://127.0.0.1/api/v1/users/userid"
            }
        }
    },
    "user": {
        "id": "userid",
    },
    "labels": {
        "identity_source": "okta-1"
    }
}

设备文档将显示设备的当前状态，包括任何关联的用户。

设备文档示例

{
    "@timestamp": "2023-07-04T09:57:19.786056-05:00",
    "event": {
        "action": "device-discovered",
    },
    "okta": {
        "created": "2019-10-02T18:03:07Z",
        "id": "deviceid",
        "lastUpdated": "2019-10-02T18:03:07Z",
        "profile": {
            "diskEncryptionType": "ALL_INTERNAL_VOLUMES",
            "displayName": "Example Device name 1",
            "platform": "WINDOWS",
            "registered": true,
            "secureHardwarePresent": false,
            "serialNumber": "XXDDRFCFRGF3M8MD6D",
            "sid": "S-1-11-111"
        },
        "resourceAlternateID": "",
        "resourceDisplayName": {
            "sensitive": false,
            "value": "Example Device name 1"
        },
        "resourceID": "deviceid",
        "resourceType": "UDDevice",
        "status": "ACTIVE",
        "_links": {
            "activate": {
                "hints": {
                    "allow": [
                        "POST"
                    ]
                },
                "href": "https://127.0.0.1/api/v1/devices/deviceid/lifecycle/activate"
            },
            "self": {
                "hints": {
                    "allow": [
                        "GET",
                        "PATCH",
                        "PUT"
                    ]
                },
                "href": "https://127.0.0.1/api/v1/devices/deviceid"
            },
            "users": {
                "hints": {
                    "allow": [
                        "GET"
                    ]
                },
                "href": "https://127.0.0.1/api/v1/devices/deviceid/users"
            }
        },
        "users": [
            {
                "id": "userid",
                "status": "RECOVERY",
                "created": "2023-05-14T13:37:20Z",
                "activated": "0001-01-01T00:00:00Z",
                "statusChanged": "2023-05-15T01:50:30Z",
                "lastLogin": "2023-05-15T01:59:20Z",
                "lastUpdated": "2023-05-15T01:50:32Z",
                "passwordChanged": "2023-05-15T01:50:32Z",
                "type": {
                    "id": "typeid"
                },
                "profile": {
                    "login": "[email protected]",
                    "email": "[email protected]",
                    "firstName": "name",
                    "lastName": "surname"
                },
                "credentials": {
                    "password": {},
                    "provider": {
                        "type": "OKTA",
                        "name": "OKTA"
                    }
                },
                "_links": {
                    "self": {
                        "href": "https://127.0.0.1/api/v1/users/userid"
                    }
                }
            }
        ]
    },
    "device": {
        "id": "deviceid",
    },
    "labels": {
        "identity_source": "okta-1"
    }
}

配置编辑

示例配置

filebeat.inputs:
- type: entity-analytics
  enabled: true
  id: okta-1
  provider: okta
  dataset: "all"
  sync_interval: "12h"
  update_interval: "30m"
  okta_domain: "OKTA_DOMAIN"
  okta_token: "OKTA_TOKEN"

okta 提供程序支持以下配置

`okta_domain`编辑

Okta 域。此字段为必填字段。

`okta_token`编辑

Okta 密钥令牌，用于身份验证。此字段为必填字段。

`collect_device_details`编辑

输入是否应从 Okta API 收集设备和与设备关联的用户详细信息。必须在 Okta 帐户上激活设备详细信息才能使用此选项。

`dataset`编辑

`sync_interval`编辑

`update_interval`编辑

指标编辑

此输入在HTTP 监控端点下公开指标。这些指标在 /inputs 路径下公开。它们可用于观察输入的活动。

指标	说明
`sync_total`	完全同步的总数。
`sync_error`	由于错误而失败的完全同步次数。
`sync_processing_time`	已用完全同步时间的直方图，以纳秒为单位（从 API 联系到发送到输出的项目的时间）。
`update_total`	增量更新的总数。
`update_error`	由于错误而失败的增量更新次数。
`update_processing_time`	已用增量更新时间的直方图，以纳秒为单位（从 API 联系到发送到输出的项目的时间）。

此输入为实验性输入，并且正在积极开发中。配置选项和行为可能会在没有警告的情况下发生变化。请谨慎使用，并且不要在生产环境中使用。

« 容器输入 ETW 输入 »

实体分析输入

实体分析输入编辑

配置选项编辑

provider编辑

通用选项编辑

enabled编辑

tags编辑

fields编辑

fields_under_root编辑

processors编辑

pipeline编辑

keep_null编辑

index编辑

publisher_pipeline.disable_host编辑

提供者编辑

Active Directory (activedirectory)编辑

设置编辑

工作原理编辑

概述编辑

将用户和设备元数据发送到 Elasticsearch编辑

配置编辑

ad_url编辑

ad_base_dn编辑

ad_user编辑

ad_password编辑

sync_interval编辑

update_interval编辑

Azure Active Directory (azure-ad)编辑

设置编辑

工作原理编辑

概述编辑

API 交互编辑

将用户和设备元数据发送到 Elasticsearch编辑

配置编辑

tenant_id编辑

client_id编辑

secret编辑

dataset编辑

sync_interval编辑

update_interval编辑

login_endpoint编辑

login_scopes编辑

select.users编辑

select.groups编辑

select.devices编辑

Okta 用户身份 (okta)编辑

设置编辑

工作原理编辑

概述编辑

API 交互编辑

将用户元数据发送到 Elasticsearch编辑

配置编辑

okta_domain编辑

okta_token编辑

collect_device_details编辑

dataset编辑

sync_interval编辑

update_interval编辑

指标编辑

`provider`编辑

`enabled`编辑

`tags`编辑

`fields`编辑

`fields_under_root`编辑

`processors`编辑

`pipeline`编辑

`keep_null`编辑

`index`编辑

`publisher_pipeline.disable_host`编辑

Active Directory (`activedirectory`)编辑

`ad_url`编辑

`ad_base_dn`编辑

`ad_user`编辑

`ad_password`编辑

`sync_interval`编辑

`update_interval`编辑

Azure Active Directory (`azure-ad`)编辑

`tenant_id`编辑

`client_id`编辑

`secret`编辑

`dataset`编辑

`sync_interval`编辑

`update_interval`编辑

`login_endpoint`编辑

`login_scopes`编辑

`select.users`编辑

`select.groups`编辑

`select.devices`编辑

Okta 用户身份 (`okta`)编辑

`okta_domain`编辑

`okta_token`编辑

`collect_device_details`编辑

`dataset`编辑

`sync_interval`编辑

`update_interval`编辑