The AWS CloudTrail API contains several data types that various actions use. This section describes each data type in detail.
Note
The order of each element in a data type structure is not guaranteed. Applications should not assume a particular order.
The following data types are supported:
• AdvancedEventSelector (p. 110)
• AdvancedFieldSelector (p. 111)
• DataResource (p. 115)
• Event (p. 117)
• EventDataStore (p. 119)
• EventSelector (p. 121)
• InsightSelector (p. 123)
• LookupAttribute (p. 124)
• PublicKey (p. 125)
• Query (p. 126)
• QueryStatistics (p. 127)
• QueryStatisticsForDescribeQuery (p. 128)
• Resource (p. 129)
• ResourceTag (p. 130)
• Tag (p. 131)
• Trail (p. 132)
• TrailInfo (p. 135)
AdvancedEventSelector
AdvancedEventSelector
Advanced event selectors let you create fine-grained selectors for the following AWS CloudTrail event record fields. They help you control costs by logging only those events that are important to you.
For more information about advanced event selectors, see Logging data events for trails in the AWS CloudTrail User Guide.
• readOnly
• eventSource
• eventName
• eventCategory
• resources.type
• resources.ARN
You cannot apply both event selectors and advanced event selectors to a trail.
Contents
FieldSelectors
Contains all selector statements in an advanced event selector.
Type: Array of AdvancedFieldSelector (p. 111) objects Array Members: Minimum number of 1 item.
Required: Yes Name
An optional, descriptive name for an advanced event selector, such as "Log data events for only two S3 buckets".
Type: String
Length Constraints: Minimum length of 0. Maximum length of 1000.
Pattern: .*
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
AdvancedFieldSelector
AdvancedFieldSelector
A single selector statement in an advanced event selector.
Contents
EndsWith
An operator that includes events that match the last few characters of the event record field specified as the value of Field.
Type: Array of strings
Array Members: Minimum number of 1 item.
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern: .+
Required: No Equals
An operator that includes events that match the exact value of the event record field specified as the value of Field. This is the only valid operator that you can use with the readOnly, eventCategory, and resources.type fields.
Type: Array of strings
Array Members: Minimum number of 1 item.
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern: .+
Required: No Field
A field in an event record on which to filter events to be logged. Supported fields include readOnly, eventCategory, eventSource (for management events), eventName, resources.type, and resources.ARN.
• readOnly - Optional. Can be set to Equals a value of true or false. A value of false logs both read and write events.
• eventSource - For filtering management events only. This can be set only to NotEquals kms.amazonaws.com.
• eventName - Can use any operator. You can use it to filter in or filter out any data event logged to CloudTrail, such as PutBucket or GetSnapshotBlock. You can have multiple values for this field, separated by commas.
• eventCategory - This is required. It must be set to Equals, and the value must be Management or Data.
• resources.type - This field is required. resources.type can only use the Equals operator, and the value can be one of the following:
• AWS::S3::Object
• AWS::Lambda::Function
• AWS::DynamoDB::Table
• AWS::S3Outposts::Object
• AWS::ManagedBlockchain::Node
Contents
You can have only one resources.type field per selector. To log data events on more than one resource type, add another selector.
• resources.ARN - You can use any operator with resources.ARN, but if you use Equals or NotEquals, the value must exactly match the ARN of a valid resource of the type you've specified in the template as the value of resources.type. For example, if resources.type equals AWS::S3::Object, the ARN must be in one of the following formats. To log all data events for all objects in a specific S3 bucket, use the StartsWith operator, and include only the bucket ARN as the matching value.
The trailing slash is intentional; do not exclude it. Replace the text between less than and greater than symbols (<>) with resource-specific information.
• arn:<partition>:s3:::<bucket_name>/
• arn:<partition>:s3:::<bucket_name>/<object_path>/
When resources.type equals AWS::S3::AccessPoint, and the operator is set to Equals or NotEquals, the ARN must be in one of the following formats. To log events on all objects in an S3 access point, we recommend that you use only the access point ARN, don’t include the object path, and use the StartsWith or NotStartsWith operators.
• arn:<partition>:s3:<region>:<account_ID>:accesspoint/<access_point_name>
• arn:<partition>:s3:<region>:<account_ID>:accesspoint/
<access_point_name>/object/<object_path>
When resources.type equals AWS::Lambda::Function, and the operator is set to Equals or NotEquals, the ARN must be in the following format:
• arn:<partition>:lambda:<region>:<account_ID>:function:<function_name>
When resources.type equals AWS::DynamoDB::Table, and the operator is set to Equals or NotEquals, the ARN must be in the following format:
• arn:<partition>:dynamodb:<region>:<account_ID>:table/<table_name>
When resources.type equals AWS::S3Outposts::Object, and the operator is set to Equals or NotEquals, the ARN must be in the following format:
• arn:<partition>:s3-outposts:<region>:<account_ID>:<object_path>
When resources.type equals AWS::ManagedBlockchain::Node, and the operator is set to Equals or NotEquals, the ARN must be in the following format:
• arn:<partition>:managedblockchain:<region>:<account_ID>:nodes/<node_ID>
When resources.type equals AWS::S3ObjectLambda::AccessPoint, and the operator is set to Equals or NotEquals, the ARN must be in the following format:
• arn:<partition>:s3-object-lambda:<region>:<account_ID>:accesspoint/
<access_point_name>
When resources.type equals AWS::EC2::Snapshot, and the operator is set to Equals or NotEquals, the ARN must be in the following format:
• arn:<partition>:ec2:<region>::snapshot/<snapshot_ID>
When resources.type equals AWS::DynamoDB::Stream, and the operator is set to Equals or
Contents
• arn:<partition>:dynamodb:<region>:<account_ID>:table/<table_name>/
stream/<date_time>
When resources.type equals AWS::Glue::Table, and the operator is set to Equals or NotEquals, the ARN must be in the following format:
• arn:<partition>:glue:<region>:<account_ID>:table/<database_name>/
<table_name>
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1000.
Pattern: [\w|\d|\.|_]+
Required: Yes NotEndsWith
An operator that excludes events that match the last few characters of the event record field specified as the value of Field.
Type: Array of strings
Array Members: Minimum number of 1 item.
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern: .+
Required: No NotEquals
An operator that excludes events that match the exact value of the event record field specified as the value of Field.
Type: Array of strings
Array Members: Minimum number of 1 item.
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern: .+
Required: No NotStartsWith
An operator that excludes events that match the first few characters of the event record field specified as the value of Field.
Type: Array of strings
Array Members: Minimum number of 1 item.
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern: .+
Required: No StartsWith
An operator that includes events that match the first few characters of the event record field specified as the value of Field.
See Also
Type: Array of strings
Array Members: Minimum number of 1 item.
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern: .+
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
DataResource
DataResource
The Amazon S3 buckets, AWS Lambda functions, or Amazon DynamoDB tables that you specify in your event selectors for your trail to log data events. Data events provide information about the resource operations performed on or within a resource itself. These are also known as data plane operations. You can specify up to 250 data resources for a trail.
NoteThe total number of allowed data resources is 250. This number can be distributed between 1 and 5 event selectors, but the total cannot exceed 250 across all selectors.
If you are using advanced event selectors, the maximum total number of values for all conditions, across all advanced event selectors for the trail, is 500.
The following example demonstrates how logging works when you configure logging of all data events for an S3 bucket named bucket-1. In this example, the CloudTrail user specified an empty prefix, and the option to log both Read and Write data events.
1. A user uploads an image file to bucket-1.
2. The PutObject API operation is an Amazon S3 object-level API. It is recorded as a data event in CloudTrail. Because the CloudTrail user specified an S3 bucket with an empty prefix, events that occur on any object in that bucket are logged. The trail processes and logs the event.
3. A user uploads an object to an Amazon S3 bucket named arn:aws:s3:::bucket-2.
4. The PutObject API operation occurred for an object in an S3 bucket that the CloudTrail user didn't specify for the trail. The trail doesn’t log the event.
The following example demonstrates how logging works when you configure logging of AWS Lambda data events for a Lambda function named MyLambdaFunction, but not for all Lambda functions.
1. A user runs a script that includes a call to the MyLambdaFunction function and the MyOtherLambdaFunction function.
2. The Invoke API operation on MyLambdaFunction is an Lambda API. It is recorded as a data event in CloudTrail. Because the CloudTrail user specified logging data events for MyLambdaFunction, any invocations of that function are logged. The trail processes and logs the event.
3. The Invoke API operation on MyOtherLambdaFunction is an Lambda API. Because the CloudTrail user did not specify logging data events for all Lambda functions, the Invoke operation for
MyOtherLambdaFunction does not match the function specified for the trail. The trail doesn’t log the event.
Contents
Type
The resource type in which you want to log data events. You can specify the following basic event selector resource types:
• AWS::S3::Object
• AWS::Lambda::Function
• AWS::DynamoDB::Table
The following resource types are also availble through advanced event selectors. Basic event selector resource types are valid in advanced event selectors, but advanced event selector resource types are not valid in basic event selectors. For more information, see AdvancedFieldSelector:Field (p. 111).
• AWS::S3Outposts::Object
• AWS::ManagedBlockchain::Node
See Also
An array of Amazon Resource Name (ARN) strings or partial ARN strings for the specified objects.
• To log data events for all objects in all S3 buckets in your AWS account, specify the prefix as arn:aws:s3:::.
NoteThis also enables logging of data event activity performed by any user or role in your AWS account, even if that activity is performed on a bucket that belongs to another AWS account.
• To log data events for all objects in an S3 bucket, specify the bucket and an empty object prefix such as arn:aws:s3:::bucket-1/. The trail logs data events for all objects in this S3 bucket.
• To log data events for specific objects, specify the S3 bucket and object prefix such as
arn:aws:s3:::bucket-1/example-images. The trail logs data events for objects in this S3 bucket that match the prefix.
• To log data events for all Lambda functions in your AWS account, specify the prefix as arn:aws:lambda.
NoteThis also enables logging of Invoke activity performed by any user or role in your AWS account, even if that activity is performed on a function that belongs to another AWS account.
• To log data events for a specific Lambda function, specify the function ARN.
Note
Lambda function ARNs are exact. For example, if you specify a function ARN
arn:aws:lambda:us-west-2:111111111111:function:helloworld, data events will only be logged for arn:aws:lambda:us-west-2:111111111111:function:helloworld. They will not be logged for arn:aws:lambda:us-west-2:111111111111:function:helloworld2.
• To log data events for all DynamoDB tables in your AWS account, specify the prefix as arn:aws:dynamodb.
Type: Array of strings Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
Event
Event
Contains information about an event that was returned by a lookup request. The result includes a representation of a CloudTrail event.
Contents
AccessKeyId
The AWS access key ID that was used to sign the request. If the request was made with temporary security credentials, this is the access key ID of the temporary credentials.
Type: String Required: No CloudTrailEvent
A JSON string that contains a representation of the event returned.
Type: String Required: No EventId
The CloudTrail ID of the event returned.
Type: String Required: No EventName
The name of the event returned.
Type: String Required: No EventSource
The AWS service to which the request was made.
Type: String Required: No EventTime
The date and time of the event returned.
Type: Timestamp Required: No ReadOnly
Information about whether the event is a write event or a read event.
Type: String Required: No
See Also
Resources
A list of resources referenced by the event returned.
Type: Array of Resource (p. 129) objects Required: No
Username
A user name or role name of the requester that called the API in the event returned.
Type: String Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
EventDataStore
EventDataStore
A storage lake of event data against which you can run complex SQL-based queries. An event data store can include events that you have logged on your account from the last 90 to 2555 days (about three months to up to seven years). To select events for an event data store, use advanced event selectors.
Contents
AdvancedEventSelectors
The advanced event selectors that were used to select events for the data store.
Type: Array of AdvancedEventSelector (p. 110) objects Required: No
CreatedTimestamp
The timestamp of the event data store's creation.
Type: Timestamp Required: No EventDataStoreArn
The ARN of the event data store.
Type: String
Length Constraints: Minimum length of 3. Maximum length of 256.
Pattern: ^[a-zA-Z0-9._/\-:]+$
Required: No MultiRegionEnabled
Indicates whether the event data store includes events from all regions, or only from the region in which it was created.
Type: Boolean Required: No Name
The name of the event data store.
Type: String
Length Constraints: Minimum length of 3. Maximum length of 128.
Pattern: ^[a-zA-Z0-9._\-]+$
Required: No OrganizationEnabled
Indicates that an event data store is collecting logged events for an organization.
Type: Boolean
See Also
Required: No RetentionPeriod
The retention period, in days.
Type: Integer
Valid Range: Minimum value of 7. Maximum value of 2555.
Required: No Status
The status of an event data store. Values are ENABLED and PENDING_DELETION.
Type: String
Valid Values: CREATED | ENABLED | PENDING_DELETION Required: No
TerminationProtectionEnabled
Indicates whether the event data store is protected from termination.
Type: Boolean Required: No UpdatedTimestamp
The timestamp showing when an event data store was updated, if applicable. UpdatedTimestamp is always either the same or newer than the time shown in CreatedTimestamp.
Type: Timestamp Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
EventSelector
EventSelector
Use event selectors to further specify the management and data event settings for your trail. By default, trails created without specific event selectors will be configured to log all read and write management events, and no data events. When an event occurs in your account, CloudTrail evaluates the event selector for all trails. For each trail, if the event matches any event selector, the trail processes and logs the event. If the event doesn't match any event selector, the trail doesn't log the event.
You can configure up to five event selectors for a trail.
You cannot apply both event selectors and advanced event selectors to a trail.
Contents
DataResources
CloudTrail supports data event logging for Amazon S3 objects, AWS Lambda functions, and Amazon DynamoDB tables with basic event selectors. You can specify up to 250 resources for an individual event selector, but the total number of data resources cannot exceed 250 across all event selectors in a trail. This limit does not apply if you configure resource logging for all data events.
For more information, see Data Events and Limits in AWS CloudTrail in the AWS CloudTrail User Guide.
Type: Array of DataResource (p. 115) objects Required: No
ExcludeManagementEventSources
An optional list of service event sources from which you do not want management events to be logged on your trail. In this release, the list can be empty (disables the filter), or it can filter out AWS Key Management Service or Amazon RDS Data API events by containing kms.amazonaws.com or rdsdata.amazonaws.com. By default, ExcludeManagementEventSources is empty, and AWS KMS and Amazon RDS Data API events are logged to your trail. You can exclude management event sources only in regions that support the event source.
Type: Array of strings Required: No
IncludeManagementEvents
Specify if you want your event selector to include management events for your trail.
For more information, see Management Events in the AWS CloudTrail User Guide.
By default, the value is true.
The first copy of management events is free. You are charged for additional copies of management events that you are logging on any subsequent trail in the same region. For more information about CloudTrail pricing, see AWS CloudTrail Pricing.
Type: Boolean Required: No ReadWriteType
Specify if you want your trail to log read-only events, write-only events, or all. For example, the EC2 GetConsoleOutput is a read-only API operation and RunInstances is a write-only API operation.
See Also
By default, the value is All.
Type: String
Valid Values: ReadOnly | WriteOnly | All Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Java V2