使用 Amazon CLI 管理 CloudTrail Lake - Amazon CloudTrail
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

使用 Amazon CLI 管理 CloudTrail Lake

以下为示例 Amazon CLI 命令,用于在 CloudTrail Lake 中创建和管理事件数据存储和查询。

为 CloudTrail 数据事件创建事件数据存储

以下示例 Amazon Command Line Interface(Amazon CLI)命令创建一个名为 my-event-data-store 的事件数据存储,它将选择所有 Amazon S3 数据事件。本示例中的事件数据存储保留期为 90 天。--name 为必填项;其它参数为可选项。--retention-period 的有效值是 7 到 2557 之间的整数,表示天数。如果您未指定 --retention-period,CloudTrail 将使用默认的保留期 2557 天。默认情况下,即使未添加参数,也会设置 --multi-region-enabled,并且事件数据存储包含来自所有区域的事件。默认情况下,不会为 Amazon Organizations 组织中的所有账户启用事件数据存储。要使事件数据存储能够收集组织中所有账户的事件,请添加 --organization-enabled 参数。分别为参数 --termination-protection-enabled(默认),以及 --no-termination-protection-enabled 设置和删除终止保护。或者,您可以选择启用 Amazon Key Management Service 加密,然后通过向命令添加 --kms-key-id 并将 KMS 密钥 ARN 指定为值,来指定 Amazon KMS key。--advanced-event-selectors 参数可以包括或排除您的事件数据存储中的数据事件。有关 --advanced-event-selectors 的更多信息,请参阅《CloudTrail API 参考》中的 AdvancedEventSelectors

当您使用高级事件选择器为 S3 对象上的数据事件做出选择时,请始终使用 StartsWith 运算符。

aws cloudtrail create-event-data-store --name my-event-data-store --retention-period 90 --kms-key-id "arn:aws:kms:us-east-1:0123456789:alias/KMS_key_alias" \ --advanced-event-selectors '[ { "Name": "Select all S3 data events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["Data"] }, { "Field": "resources.type", "Equals": ["AWS::S3::Object"] }, { "Field": "resources.ARN", "StartsWith": ["arn:aws:s3"] } ] } ]'

以下为响应示例。

{ "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-ee54-4813-92d5-999aeEXAMPLE", "Name": "my-event-data-store", "Status": "CREATED", "AdvancedEventSelectors": [ { "Name": "Select all S3 data events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "Data" ] }, { "Field": "resources.type", "Equals": [ "AWS::S3::Object" ] }, { "Field": "resources.ARN", "StartsWith": [ "arn:aws:s3" ] } ] } ], "MultiRegionEnabled": true, "OrganizationEnabled": false, "RetentionPeriod": 90, "KmsKeyId": "arn:aws:kms:us-east-1:0123456789:alias/KMS_key_alias", "TerminationProtectionEnabled": true, "CreatedTimestamp": "2021-12-09T22:19:39.417000-05:00", "UpdatedTimestamp": "2021-12-09T22:19:39.603000-05:00" }

为 Amazon Config 配置项目创建事件数据存储

以下示例 Amazon CLI create-event-data-store 命令创建一个名为 my-event-data-store 的事件数据存储,它将选择 Amazon Config 配置项目。此示例中的事件数据存储保留期限为 90 天。--name 参数为必需的;其他参数是可选的。--retention-period 的有效值是 7 到 2557 之间的整数,表示天数。如果您不指定 --retention-period,CloudTrail 将使用默认保留期限 2557 天。默认情况下,即使未添加参数,也会设置 --multi-region-enabled,并且事件数据存储包含来自所有 Amazon Web Services 区域 的配置项目。默认情况下,不会为 Amazon Organizations 组织中的所有账户启用事件数据存储;要使事件数据存储能够收集组织中所有账户的配置项目,请添加 --organization-enabled 参数。分别为参数 --termination-protection-enabled(默认),以及 --no-termination-protection-enabled 设置和删除终止保护。或者,您可以选择启用 Amazon Key Management Service 加密,然后通过向命令添加 --kms-key-id 并将 KMS 密钥 ARN 指定为值,来指定 Amazon KMS key。--advanced-event-selectors 参数通过指定 eventCategory 字段等于 ConfigurationItem,以包含您的事件数据存储中的配置项目。

aws cloudtrail create-event-data-store --name my-event-data-store --retention-period 90 --kms-key-id "arn:aws:kms:us-east-1:0123456789:alias/KMS_key_alias" \ --advanced-event-selectors '[ { "Name": "Select Amazon Config configuration items", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["ConfigurationItem"] } ] } ]'

以下为响应示例。

{ "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-ee54-4813-92d5-999aeEXAMPLE", "Name": "my-event-data-store", "Status": "CREATED", "AdvancedEventSelectors": [ { "Name": "Select Amazon Config configuration items", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "ConfigurationItem" ] } ] } ], "MultiRegionEnabled": true, "OrganizationEnabled": false, "RetentionPeriod": 90, "KmsKeyId": "arn:aws:kms:us-east-1:0123456789:alias/KMS_key_alias", "TerminationProtectionEnabled": true, "CreatedTimestamp": "2022-10-07T19:03:24.277000+00:00", "UpdatedTimestamp": "2022-10-07T19:03:24.468000+00:00" }

获取事件数据存储

以下示例 Amazon CLI get-event-data-store 命令返回有关由必需的 --event-data-store 参数指定的事件数据存储的信息,该参数接受 ARN 或 ARN 的 ID 后缀。

aws cloudtrail get-event-data-store --event-data-store arn:aws:cloudtrail:us-east-1:12345678910:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE

以下为响应示例。创建时间和上次更新时间采用 timestamp 格式。

{ "EventDataStoreARN": "arn:aws:cloudtrail:us-east-1:12345678910:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE", "Name": "my-event-data-store", "Status": "Enabled", "AdvancedEventSelectors": [ { "Name": "Select All S3 Data Events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["Data"] }, { "Field": "resources.type", "Equals": ["AWS::S3::Object"] }, { "Field": "resources.ARN", "StartsWith": ["arn:aws:s3"] } ] } ] "CreatedTimestamp": 1248496624, "UpdatedTimestamp": 1598296624, "MultiRegionEnabled": true, "RetentionPeriod": 90, "TerminationProtectionEnabled": true, }

列出账户中的所有事件数据存储

以下示例 Amazon CLI list-event-data-stores 命令返回有关当前区域内某个账户中的所有事件数据存储的信息。可选参数包括 --max-results,以指定希望在单个页面上通过命令返回的最大结果数。如果结果数超过指定的 --max-results 值,请再次运行命令,添加返回的 NextToken 值来获取下一页的结果。

aws cloudtrail list-event-data-stores

以下为响应示例。

{ "EventDataStores": [ { "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-ee54-4813-92d5-999aeEXAMPLE", "Name": "my-event-data-store" } ] }

更新事件数据存储

以下示例 Amazon CLI update-event-data-store 命令更新事件数据存储,以将其保留期限更改为 100 天,并启用终止保护。必要的 --event-data-store 参数值是 ARN(或 ARN 的 ID 后缀),且是必填项;其它参数是可选项。在此示例中,添加了 --retention-period 参数,以将保留期限更改为 100 天。或者,您可以选择启用 Amazon Key Management Service 加密,然后通过向命令添加 --kms-key-id 并将 KMS 密钥 ARN 指定为值,来指定 Amazon KMS key。添加 --termination-protection-enabled 以在未启用终止保护的事件数据存储上启用终止保护。

aws cloudtrail update-event-data-store --event-data-store arn:aws:cloudtrail:us-east-1:12345678910:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE --retention-period 100 --kms-key-id "arn:aws:kms:us-east-1:0123456789:alias/KMS_key_alias" \ --termination-protection-enabled

以下为响应示例。

{ "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-ee54-4813-92d5-999aeEXAMPLE", "Name": "my-event-data-store", "Status": "ENABLED", "AdvancedEventSelectors": [ { "Name": "Select all S3 data events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "Data" ] }, { "Field": "resources.type", "Equals": [ "AWS::S3::Object" ] }, { "Field": "resources.ARN", "StartsWith": [ "arn:aws:s3" ] } ] } ], "MultiRegionEnabled": true, "OrganizationEnabled": false, "RetentionPeriod": 100, "KmsKeyId": "arn:aws:kms:us-east-1:0123456789:alias/KMS_key_alias", "TerminationProtectionEnabled": true, "CreatedTimestamp": "2021-12-09T22:19:39.417000-05:00", "UpdatedTimestamp": "2021-12-09T22:19:39.603000-05:00" }

删除事件数据存储

以下示例 Amazon CLI delete-event-data-store 命令禁用由 --event-data-store 指定的事件数据存储,它接受事件数据存储 ARN 或 ARN 的 ID 后缀。运行 delete-event-data-store 之后,事件数据存储的最终状态为 PENDING_DELETION,事件数据存储将在七天等待期后自动删除。必须在事件数据存储中设置 --no-termination-protection-enabled;如果已设置 --termination-protection-enabled,则此操作将无法正常工作。

在事件数据存储上运行 delete-event-data-store 之后,您无法在使用已禁用的数据存储的查询上运行 list-queriesdescribe-queryget-query-results。处于等待删除状态时,事件数据存储不计入您的账户最多五个事件数据存储的限额内。

aws cloudtrail delete-event-data-store --event-data-store arn:aws:cloudtrail:us-east-1:12345678910:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE

如果成功执行操作,则没有响应。

恢复事件数据存储

以下示例 Amazon CLI restore-event-data-store 命令恢复待删除的事件数据存储。事件数据存储由 --event-data-store 指定,它接受事件数据存储 ARN 或 ARN 的 ID 后缀。您只能在删除后的七天等待期内恢复被删除的事件数据存储。

aws cloudtrail restore-event-data-store --event-data-store EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE

响应包括有关事件数据存储的信息,包括其 ARN、高级事件选择器以及还原状态。

开始查询

以下示例 Amazon CLI start-query 命令针对在查询语句中指定为 ID 的事件数据存储运行查询,并将查询结果传送到指定的 S3 桶。必需的 --query-statement 参数提供 SQL 查询,用单引号括起来。可选参数包括 --delivery-s3uri,用于将查询结果传送到指定的 S3 存储桶。

aws cloudtrail start-query --query-statement 'SELECT eventID, eventTime FROM EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE LIMIT 10' --delivery-s3uri "s3://aws-cloudtrail-lake-query-results-12345678910-us-east-1"

响应是 QueryId 字符串。要获取查询的状态,请使用 start-query 返回的值 QueryId 运行 describe-query。如果查询成功,您可以运行 get-query-results 以获取结果。

输出

{ "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE" }
注意

运行时间超过一小时的查询可能会超时。您仍可获得在查询超时之前处理的部分结果。

如果您使用可选的 --delivery-s3uri 参数将查询结果传送到 S3 存储桶,则存储桶策略必须授予 CloudTrail 向存储桶传送查询结果的权限。有关手动编辑存储桶策略的信息,请参阅用于 CloudTrail Lake 查询结果的 Amazon S3 存储桶策略

获取有关查询的元数据

以下示例 Amazon CLI describe-query 命令获取有关查询的元数据,包括以毫秒为单位的查询运行时间、扫描和匹配的事件数、扫描的总字节数以及查询状态。BytesScanned 值与账户支付查询费用的总字节数匹配,除非查询仍在运行。

您必须指定 ARN 或 --event-data-store ARN 的 ID 后缀,以及 --query-id 的值。

aws cloudtrail describe-query --event-data-store EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE --query-id EXAMPLEd-17a7-47c3-a9a1-eccf7EXAMPLE

以下为响应示例。

{ "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE", "QueryString": "SELECT eventID, eventTime FROM EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE LIMIT 10", "QueryStatus": "RUNNING", "QueryStatistics": { "EventsMatched": 10, "EventsScanned": 1000, "BytesScanned": 35059, "ExecutionTimeInMillis": 3821, "CreationTime": "1598911142" } }

获取查询结果

以下示例 Amazon CLI get-query-results 命令获取查询的事件数据结果。您必须指定 ARN 或 --event-data-store ARN 的 ID 后缀,以及 start-query 命令返回的 QueryIDBytesScanned 值与账户支付查询费用的总字节数匹配,除非查询仍在运行。可选参数包括 --max-query-results,以指定希望在单个页面上通过命令返回的最大结果数。如果结果数超过指定的 --max-query-results 值,请再次运行命令,添加返回 NextToken 值来获取下一页的结果。

aws cloudtrail get-query-results --event-data-store EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE --query-id EXAMPLEd-17a7-47c3-a9a1-eccf7EXAMPLE

输出

{ "QueryStatus": "RUNNING", "QueryStatistics": { "ResultsCount": 244, "TotalResultsCount": 1582, "BytesScanned":27044 }, "QueryResults": [ { "key": "eventName", "value": "StartQuery", } ], "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE", "QueryString": "SELECT eventID, eventTime FROM EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE LIMIT 10", "NextToken": "20add42078135EXAMPLE" }

列出事件数据存储中的所有查询

以下示例 Amazon CLI list-queries 命令返回过去七天内针对指定事件数据存储的查询和查询状态的列表。您必须指定 ARN 或 --event-data-store ARN 值的 ID 后缀。或者,要缩短结果列表,您可以通过添加 --start-time--end-time 参数和 --query-status 值来指定时间范围、格式化为时间戳。QueryStatus 的有效值包括 QUEUEDRUNNINGFINISHEDFAILEDCANCELLED

list-queries 还有可选的分页参数。使用 --max-results 以指定希望在单个页面上通过命令返回的最大结果数。如果结果数超过指定的 --max-results 值,请再次运行命令,添加返回 NextToken 值来获取下一页的结果。

aws cloudtrail list-queries --event-data-store EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE --query-status CANCELLED --start-time 1598384589 --end-time 1598384602 --max-results 10

输出

{ "Queries": [ { "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE", "QueryStatus": "CANCELLED", "CreationTime": 1598911142 }, { "QueryId": "EXAMPLE2-4e89-9230-2127-5dr3aEXAMPLE", "QueryStatus": "CANCELLED", "CreationTime": 1598296624" } ], "NextToken": "20add42078135EXAMPLE" }

取消正在运行的查询

以下示例 Amazon CLI cancel-query 命令取消状态为 RUNNING 的查询。您必须指定 ARN 或 --event-data-store ARN 值的 ID 后缀,以及 --query-id 的值。当您运行 cancel-query 时,即使尚未完成 cancel-query 操作,查询状态也可能会显示为 CANCELLED

注意

取消的查询可能会产生费用。您的账户仍需为取消查询之前扫描的数据量支付费用。

以下是 CLI 示例。

aws cloudtrail cancel-query --event-data-store EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE --query-id EXAMPLEd-17a7-47c3-a9a1-eccf7EXAMPLE

输出

QueryId -> (string) QueryStatus -> (string)