创建与 Amazon 外部事件源的集成 - Amazon CloudTrail
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

创建与 Amazon 外部事件源的集成

您可以使用 CloudTrail 记录和存储来自您的混合环境中任何来源的用户活动数据,如本地或云中托管的内部或 SaaS 应用程序、虚拟机或容器。您无需维护多个日志聚合器和报告工具,即可对这些数据进行存储、访问、分析、故障排除和操作。

来自非 Amazon 来源的活动事件通过使用通道,将来自与 CloudTrail 配合使用的外部合作伙伴或您自己的来源的事件引入 CloudTrail Lake。在创建通道时,您可以选择一个或多个事件数据存储,用于存储来自通道来源的事件。只要将目标事件数据存储设置为记录 eventCategory="ActivityAuditLog" 事件,即可根据需要更改通道的目标事件数据存储。当您为来自外部合作伙伴的活动创建通道时,您需要向合作伙伴或来源应用程序提供通道 ARN。附加到该通道的资源策略允许来源通过该通道传输事件。如果通道没有资源策略,则只有通道所有者可以针对该通道调用 PutAuditEvents API。

CloudTrail 已与很多事件源提供商结成合作伙伴,如 Okta 和 LaunchDarkly。当您创建与 Amazon 外部事件源的集成时,您可以选择其中一个合作伙伴作为事件源,也可以选择 My custom integration(我的自定义集成),将来自您自己的来源的事件集成到 CloudTrail 中。每个来源最多允许一个通道。

有两种类型的集成:直接集成和解决方案集成。通过直接集成,合作伙伴将调用 PutAuditEvents API 以将事件传送到您的 Amazon 账户的事件数据存储中。通过解决方案集成,应用程序将在您的 Amazon 账户中运行,并且它将调用 PutAuditEvents API 将事件传送到您的 Amazon 账户的事件数据存储中。

Integrations(集成)页面上,您可以选择 Available sources(可用来源)选项卡,以查看合作伙伴的 Integration type(集成类型)。

首先,使用 CloudTrail 控制台创建集成,以记录来自合作伙伴或其他应用程序来源的事件。

创建与 CloudTrail 合作伙伴的集成

当您创建与 Amazon 外部事件源的集成时,您可以选择其中一个合作伙伴作为事件源。当您在 CloudTrail 中创建与合作伙伴应用程序的集成时,该合作伙伴需要您在此工作流中创建的通道的 Amazon 资源名称(ARN),才能向 CloudTrail 发送事件。在创建集成后,您可以按照合作伙伴的说明向合作伙伴提供所需的通道 ARN,以完成集成的配置。在合作伙伴针对集成的通道调用 PutAuditEvents 后,集成会开始将合作伙伴事件摄取到 CloudTrail 中。

  1. 登录到 Amazon Web Services Management Console,然后通过以下网址打开 CloudTrail 控制台:https://console.aws.amazon.com/cloudtrail

  2. 在导航窗格中,打开 Lake 子菜单,然后选择集成

  3. Add integration(添加集成)页面上,为您的通道输入名称。该名称可以包含 3-128 个字符。只允许使用字母、数字、句点、下划线和短划线。

  4. 选择要从中获取事件的合作伙伴应用程序来源。如果您要与来自您自己的应用程序(在本地或云中托管)的事件集成,请选择 My custom integration(我的自定义集成)。

  5. Event delivery location(事件传送位置)中,选择将相同活动事件记录到现有事件数据存储中,或创建新的事件数据存储。

    如果您选择创建新的事件数据存储,请输入事件数据存储的名称,选择定价选项,并以天为单位指定保留期。事件数据存储将保留指定天数内的事件数据。

    如果您选择将活动事件记录到一个或多个现有事件数据存储中,请从列表中选择事件数据存储。事件数据存储只能包含活动事件。控制台中的事件类型必须是 Events from integrations(来自集成的事件)。在 API 中,eventCategory 值必须为 ActivityAuditLog

  6. Resource policy(资源策略)中,为集成的通道配置资源策略。资源策略是 JSON 策略文档,它们指定了指定主体可在资源上执行的操作,以及在什么条件下执行操作。在资源策略中定义为主体的账户可以调用 PutAuditEvents API,以向您的通道传送事件。如果资源所有者的 IAM policy 允许 cloudtrail-data:PutAuditEvents 操作,则资源所有者将拥有对资源的隐式访问权限。

    该策略所需的信息由集成类型决定。对于直接集成,CloudTrail 会自动添加合作伙伴的 Amazon 账户 ID,并要求您输入合作伙伴提供的唯一外部 ID。对于解决方案集成,您必须指定至少一个 Amazon 账户 ID 作为主体,并且可以选择输入外部 ID,以防范混淆代理。

    注意

    如果您没有为通道创建资源策略,则只有通道所有者可以针对该通道调用 PutAuditEvents API。

    1. 对于直接集成,请输入您的合作伙伴提供的外部 ID。集成合作伙伴将提供唯一的外部 ID(如账户 ID 或随机生成的字符串)用于集成,以防范混淆代理。合作伙伴负责创建和提供唯一的外部 ID。

      您可以选择 How to find this?(如何查找?),以查看描述如何查找外部 ID 的合作伙伴文档。

      注意

      如果资源策略包括外部 ID,则针对 PutAuditEvents API 的所有调用都必须包括该外部 ID。但是,如果策略未定义外部 ID,合作伙伴仍然可以调用 PutAuditEvents API,并指定 externalId 参数。

    2. 对于解决方案集成,选择添加 Amazon 账户,以指定要在策略中添加为主体的 Amazon 账户 ID。

  7. (可选)在 Tags(标签)区域中,您最多可以添加 50 个标签键和值对,以帮助您对事件数据存储和通道的访问进行识别、排序和控制。要详细了解如何使用 IAM 策略以根据标签授权对事件数据存储的访问,请参阅示例:拒绝基于标签创建或删除事件数据存储的访问权限。有关如何在 Amazon 中使用标签的更多信息,请参阅《Amazon Web Services 一般参考》中的 Tagging Amazon resources

  8. 在准备好创建新的集成后,请选择 Add integration(添加集成)。没有审阅页。CloudTrail 将创建集成,但您必须向合作伙伴应用程序提供通道 Amazon 资源名称(ARN)。有关向合作伙伴应用程序提供通道 ARN 的说明,可在合作伙伴文档网站上找到。有关更多信息,请在 Integrations(集成)页面的 Available sources(可用来源)选项卡上,选择与合作伙伴相对应的 Learn more(了解更多)链接,以便在 Amazon Web Services Marketplace 中打开合作伙伴的页面。

要完成集成的设置,请向合作伙伴或来源应用程序提供通道 ARN。根据集成类型,您、合作伙伴或应用程序将运行 PutAuditEvents API,以将活动事件传送到您的 Amazon 账户的事件数据存储。在传送活动事件后,您可以使用 CloudTrail Lake 搜索、查询和分析您的应用程序中记录的数据。您的事件数据包括与 CloudTrail 事件有效负载相匹配的字段,如 eventVersioneventSourceuserIdentity

创建自定义集成

您可以使用 CloudTrail 记录和存储来自您的混合环境中任何来源的用户活动数据,如本地或云中托管的内部或 SaaS 应用程序、虚拟机或容器。在 CloudTrail Lake 控制台中执行此过程的前半部分,然后调用 PutAuditEvents API 摄取事件,提供您的通道 ARN 和事件有效负载。在使用 PutAuditEvents API 将应用程序活动摄取到 CloudTrail 中后,您可以使用 CloudTrail Lake 搜索、查询和分析您的应用程序中记录的数据。

  1. 登录到 Amazon Web Services Management Console,然后通过以下网址打开 CloudTrail 控制台:https://console.aws.amazon.com/cloudtrail

  2. 在导航窗格中,打开 Lake 子菜单,然后选择集成

  3. Add integration(添加集成)页面上,为您的通道输入名称。该名称可以包含 3-128 个字符。只允许使用字母、数字、句点、下划线和短划线。

  4. 选择 My custom integration(我的自定义集成)。

  5. Event delivery location(事件传送位置)中,选择将相同活动事件记录到现有事件数据存储中,或创建新的事件数据存储。

    如果您选择创建新的事件数据存储,请输入事件数据存储的名称,并以天为单位指定保留期。如果您选择一年可延期保留定价选项,则可以将事件数据在事件数据存储中最多保留 3653 天(大约 10 年);如果您选择七年保留定价选项,则最多可以保留 2557 天(大约 7 年)。

    如果您选择将活动事件记录到一个或多个现有事件数据存储中,请从列表中选择事件数据存储。事件数据存储只能包含活动事件。控制台中的事件类型必须是 Events from integrations(来自集成的事件)。在 API 中,eventCategory 值必须为 ActivityAuditLog

  6. Resource policy(资源策略)中,为集成的通道配置资源策略。资源策略是 JSON 策略文档,它们指定了指定主体可在资源上执行的操作,以及在什么条件下执行操作。在资源策略中定义为主体的账户可以调用 PutAuditEvents API,以向您的通道传送事件。

    注意

    如果您没有为通道创建资源策略,则只有通道所有者可以针对该通道调用 PutAuditEvents API。

    1. (可选)输入唯一的外部 ID,以提供额外一层保护。该外部 ID 是一个唯一的字符串,如账户 ID 或随机生成的字符串,以防范混淆代理。

      注意

      如果资源策略包括外部 ID,则针对 PutAuditEvents API 的所有调用都必须包括该外部 ID。但是,如果策略未定义外部 ID,您仍然可以调用 PutAuditEvents API,并指定 externalId 参数。

    2. 选择添加 Amazon 账户,以指定要在通道的资源策略中添加为主体的每个 Amazon 账户 ID。

  7. (可选)在 Tags(标签)区域中,您最多可以添加 50 个标签键和值对,以帮助您对事件数据存储和通道的访问进行识别、排序和控制。要详细了解如何使用 IAM 策略以根据标签授权对事件数据存储的访问,请参阅示例:拒绝基于标签创建或删除事件数据存储的访问权限。有关如何在 Amazon 中使用标签的更多信息,请参阅《Amazon Web Services 一般参考》中的 Tagging Amazon resources

  8. 在准备好创建新的集成后,请选择 Add integration(添加集成)。没有审阅页。CloudTrail 将创建集成,但要集成您的自定义事件,您必须在 PutAuditEvents 请求中指定通道 ARN。

  9. 调用 PutAuditEvents API,以将您的活动事件摄取到 CloudTrail 中。每个 PutAuditEvents 请求最多可以添加 100 个活动事件(或最多 1MB)。您将需要在前面的步骤中创建的通道 ARN、您希望 CloudTrail 添加的事件有效负载,以及外部 ID(如果已为您的资源策略指定)。在将事件有效负载摄取到 CloudTrail 中之前,请确保事件有效负载中没有敏感或个人身份识别信息。您摄取到 CloudTrail 中的事件必须遵循 CloudTrail Lake 集成事件架构

    提示

    使用 Amazon CloudShell 确保您正在运行最新的 Amazon API。

    以下示例演示了如何使用 put-audit-events CLI 命令。--audit-events--channel-arn 参数是必需的。您需要在前面的步骤中创建的通道的 ARN,可以从集成详细信息页面复制该 ARN。--audit-events 的值是事件对象的 JSON 数组。--audit-events 包括来自事件的所需 ID、事件所需的有效负载(作为 EventData 的值)以及可选校验和,以帮助在摄取到 CloudTrail 中后验证事件的完整性。

    aws cloudtrail-data put-audit-events \ --region region \ --channel-arn $ChannelArn \ --audit-events \ id="event_ID",eventData='"{event_payload}"' \ id="event_ID",eventData='"{event_payload}"',eventDataChecksum="optional_checksum"

    以下是包含两个事件示例的示例命令。

    aws cloudtrail-data put-audit-events \ --region us-east-1 \ --channel-arn arn:aws:cloudtrail:us-east-1:01234567890:channel/EXAMPLE8-0558-4f7e-a06a-43969EXAMPLE \ --audit-events \ id="EXAMPLE3-0f1f-4a85-9664-d50a3EXAMPLE",eventData='"{\"eventVersion\":\0.01\",\"eventSource\":\"custom1.domain.com\", ... \}"' \ id="EXAMPLE7-a999-486d-b241-b33a1EXAMPLE",eventData='"{\"eventVersion\":\0.02\",\"eventSource\":\"custom2.domain.com\", ... \}"',eventDataChecksum="EXAMPLE6e7dd61f3ead...93a691d8EXAMPLE"

    以下示例命令添加了 --cli-input-json 参数,以指定事件有效负载的 JSON 文件(custom-events.json)。

    aws cloudtrail-data put-audit-events \ --channel-arn $channelArn \ --cli-input-json file://custom-events.json \ --region us-east-1

    以下是示例 JSON 文件 custom-events.json 的示例内容。

    { "auditEvents": [ { "eventData": "{\"version\":\"eventData.version\",\"UID\":\"UID\", \"userIdentity\":{\"type\":\"CustomUserIdentity\",\"principalId\":\"principalId\", \"details\":{\"key\":\"value\"}},\"eventTime\":\"2021-10-27T12:13:14Z\",\"eventName\":\"eventName\", \"userAgent\":\"userAgent\",\"eventSource\":\"eventSource\", \"requestParameters\":{\"key\":\"value\"},\"responseElements\":{\"key\":\"value\"}, \"additionalEventData\":{\"key\":\"value\"}, \"sourceIPAddress\":\"source_IP_address\",\"recipientAccountId\":\"recipient_account_ID\"}", "id": "1" } ] }

(可选)计算校验和值

您在 PutAuditEvents 请求中作为 EventDataChecksum 的值指定的校验和可以帮助您验证 CloudTrail 是否收到与该校验和相匹配的事件;它可以帮助验证事件的完整性。校验和值采用一种 base64-SHA256 算法,您可以通过运行以下命令来计算该值。

printf %s "{"eventData": "{\"version\":\"eventData.version\",\"UID\":\"UID\", \"userIdentity\":{\"type\":\"CustomUserIdentity\",\"principalId\":\"principalId\", \"details\":{\"key\":\"value\"}},\"eventTime\":\"2021-10-27T12:13:14Z\",\"eventName\":\"eventName\", \"userAgent\":\"userAgent\",\"eventSource\":\"eventSource\", \"requestParameters\":{\"key\":\"value\"},\"responseElements\":{\"key\":\"value\"}, \"additionalEventData\":{\"key\":\"value\"}, \"sourceIPAddress\":\"source_IP_address\", \"recipientAccountId\":\"recipient_account_ID\"}", "id": "1"}" \ | openssl dgst -binary -sha256 | base64

该命令将返回校验和。以下是示例。

EXAMPLEHjkI8iehvCUCWTIAbNYkOgO/t0YNw+7rrQE=

校验和值将成为您的 PutAuditEvents 请求中 EventDataChecksum 的值。如果该校验和与所提供事件的校验和不匹配,CloudTrail 将通过 InvalidChecksum 错误拒绝该事件。

有关集成合作伙伴的其他信息

本节中的表格提供了每个集成合作伙伴的来源名称,并标识了集成类型(直接集成或解决方案集成)。

在调用 CreateChannel API 时,需要提供 Source name(源名称)列中的信息。您可以将源名称指定为 Source 参数的值。

合作伙伴名称(控制台) 源名称(API) 集成类型
我的自定义集成 Custom solution
Cloud Storage Security CloudStorageSecurityConsole solution
Clumio Clumio 直接
CrowdStrike CrowdStrike solution
CyberArk CyberArk solution
GitHub GitHub solution
Kong Inc KongGatewayEnterprise solution
LaunchDarkly LaunchDarkly 直接
Netskope NetskopeCloudExchange solution
Nordcloud,IBM 旗下的一家公司 IBMMulticloud 直接
MontyCloud MontyCloud 直接
Okta OktaSystemLogEvents solution
One Identity OneLogin solution
Shoreline.io Shoreline solution
Snyk.io Snyk 直接
Wiz WizAuditLogs solution

查看合作伙伴文档

您可以通过查看合作伙伴的文档,了解有关合作伙伴与 CloudTrail Lake 的集成的更多信息。

查看合作伙伴文档

  1. 登录到 Amazon Web Services Management Console,然后通过以下网址打开 CloudTrail 控制台:https://console.aws.amazon.com/cloudtrail

  2. 在导航窗格中,打开 Lake 子菜单,然后选择集成

  3. Integrations(集成)页面上,选择 Available sources(可用资源),然后选择与您要查看其文档的合作伙伴相对应的 Learn more(了解更多)。