Understanding CloudTrail events - AWS CloudTrail

Understanding CloudTrail events

An event in CloudTrail is the record of an activity in an AWS account. This activity can be an action taken by an IAM identity, or service that is monitorable by CloudTrail. CloudTrail events provide a history of both API and non-API account activity made through the AWS Management Console, AWS SDKs, command line tools, and other AWS services.

There are three types of CloudTrail events:

By default, trails and event data stores log management events, but not data or Insights events.

All event types use a CloudTrail JSON log format. The log contains information about requests for resources in your account, such as who made the request, the services used, the actions performed, and parameters for the action. The event data is enclosed in a Records array.

For information about CloudTrail event record fields, see CloudTrail record contents.

Management events

Management events provide information about management operations that are performed on resources in your AWS account. These are also known as control plane operations. Example management events include:

  • Configuring security (for example, AWS Identity and Access Management AttachRolePolicy API operations).

  • Registering devices (for example, Amazon EC2 CreateDefaultVpc API operations).

  • Configuring rules for routing data (for example, Amazon EC2 CreateSubnet API operations).

  • Setting up logging (for example, AWS CloudTrail CreateTrail API operations).

Management events can also include non-API events that occur in your account. For example, when a user signs in to your account, CloudTrail logs the ConsoleLogin event. For more information, see Non-API events captured by CloudTrail. For a list of management events that CloudTrail logs for AWS services, see CloudTrail supported services and integrations.

The following example shows a single log record of a management event. In this event, an IAM user named Mary_Major ran the aws cloudtrail start-logging command to call the CloudTrail StartLogging action to start the logging process on a trail named myTrail.

{ "eventVersion": "1.09", "userIdentity": { "type": "IAMUser", "principalId": "EXAMPLE6E4XEGITWATV6R", "arn": "arn:aws:iam::123456789012:user/Mary_Major", "accountId": "123456789012", "accessKeyId": "AKIAIOSFODNN7EXAMPLE", "userName": "Mary_Major", "sessionContext": { "attributes": { "creationDate": "2023-07-19T21:11:57Z", "mfaAuthenticated": "false" } } }, "eventTime": "2023-07-19T21:33:41Z", "eventSource": "cloudtrail.amazonaws.com", "eventName": "StartLogging", "awsRegion": "us-east-1", "sourceIPAddress": "192.0.2.0", "userAgent": "aws-cli/2.13.5 Python/3.11.4 Linux/4.14.255-314-253.539.amzn2.x86_64 exec-env/CloudShell exe/x86_64.amzn.2 prompt/off command/cloudtrail.start-logging", "requestParameters": { "name": "myTrail" }, "responseElements": null, "requestID": "9d478fc1-4f10-490f-a26b-EXAMPLE0e932", "eventID": "eae87c48-d421-4626-94f5-EXAMPLEac994", "readOnly": false, "eventType": "AwsApiCall", "managementEvent": true, "recipientAccountId": "123456789012", "eventCategory": "Management", "tlsDetails": { "tlsVersion": "TLSv1.2", "cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256", "clientProvidedHostHeader": "cloudtrail.us-east-1.amazonaws.com" }, "sessionCredentialFromConsole": "true" }

In this next example, an IAM user user named Paulo_Santos ran the aws cloudtrail start-event-data-store-ingestion command to call the StartEventDataStoreIngestion action to start ingestion on an event data store.

{ "eventVersion": "1.09", "userIdentity": { "type": "IAMUser", "principalId": "EXAMPLEPHCNW5EQV7NA54", "arn": "arn:aws:iam::123456789012:user/Paulo_Santos", "accountId": "123456789012", "accessKeyId": "(AKIAIOSFODNN7EXAMPLE", "userName": "Paulo_Santos", "sessionContext": { "attributes": { "creationDate": "2023-07-21T21:55:30Z", "mfaAuthenticated": "false" } } }, "eventTime": "2023-07-21T21:57:28Z", "eventSource": "cloudtrail.amazonaws.com", "eventName": "StartEventDataStoreIngestion", "awsRegion": "us-east-1", "sourceIPAddress": "192.0.2.0", "userAgent": "aws-cli/2.13.1 Python/3.11.4 Linux/4.14.255-314-253.539.amzn2.x86_64 exec-env/CloudShell exe/x86_64.amzn.2 prompt/off command/cloudtrail.start-event-data-store-ingestion", "requestParameters": { "eventDataStore": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/2a8f2138-0caa-46c8-a194-EXAMPLE87d41" }, "responseElements": null, "requestID": "f62a3494-ba4e-49ee-8e27-EXAMPLE4253f", "eventID": "d97ca7e2-04fe-45b4-882d-EXAMPLEa9b2c", "readOnly": false, "eventType": "AwsApiCall", "managementEvent": true, "recipientAccountId": "123456789012", "eventCategory": "Management", "tlsDetails": { "tlsVersion": "TLSv1.2", "cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256", "clientProvidedHostHeader": "cloudtrail.us-east-1.amazonaws.com" }, "sessionCredentialFromConsole": "true" }

Data events

Data events provide information about the resource operations performed on or in a resource. These are also known as data plane operations. Data events are often high-volume activities.

Example data events include:

The following table shows the data event types available for trails and event data stores. The Data event type (console) column shows the appropriate selection in the console. The resources.type value column shows the resources.type value that you would specify to include data events of that type in your trail or event data store using the AWS CLI or CloudTrail APIs.

For trails, you can use basic or advanced event selectors to log data events for Amazon S3 buckets and bucket objects, Lambda functions, and DynamoDB tables (shown in the first three rows of the table). You can use only advanced event selectors to log the data event types shown in the remaining rows.

For event data stores, you can use only advanced event selectors to include data events.

AWS service Description Data event type (console) resources.type value
Amazon DynamoDB

Amazon DynamoDB item-level API activity on tables (for example, PutItem, DeleteItem, and UpdateItem API operations).

Note

For tables with streams enabled, the resources field in the data event contains both AWS::DynamoDB::Stream and AWS::DynamoDB::Table. If you specify AWS::DynamoDB::Table for the resources.type, it will log both DynamoDB table and DynamoDB streams events by default. To exclude streams events, add a filter on the eventName field.

DynamoDB

AWS::DynamoDB::Table

AWS Lambda

AWS Lambda function execution activity (the Invoke API).

Lambda AWS::Lambda::Function
Amazon S3

Amazon S3 object-level API activity (for example, GetObject, DeleteObject, and PutObject API operations) on buckets and objects in buckets.

S3 AWS::S3::Object
AWS AppConfig

AWS AppConfig API activity for configuration operations such as calls to StartConfigurationSession and GetLatestConfiguration.

AWS AppConfig AWS::AppConfig::Configuration
AWS B2B Data Interchange

B2B Data Interchange API activity for Transformer operations such as calls to GetTransformerJob and StartTransformerJob.

B2B Data Interchange AWS::B2BI::Transformer
Amazon Bedrock Amazon Bedrock API activity on an agent alias. Bedrock agent alias AWS::Bedrock::AgentAlias
Amazon Bedrock API activity on a knowledge base. Bedrock knowledge base AWS::Bedrock::KnowledgeBase
Amazon CloudFront

CloudFront API activity on a KeyValueStore.

CloudFront KeyValueStore AWS::CloudFront::KeyValueStore
AWS Cloud Map AWS Cloud Map API activity on a namespace. AWS Cloud Map namespace AWS::ServiceDiscovery::Namespace
AWS Cloud Map API activity on a service. AWS Cloud Map service AWS::ServiceDiscovery::Service
AWS CloudTrail

CloudTrail PutAuditEvents activity on a CloudTrail Lake channel that is used to log events from outside AWS.

CloudTrail AWS::CloudTrail::Channel
Amazon CodeWhisperer Amazon CodeWhisperer API activity on a customization. CodeWhisperer customization AWS::CodeWhisperer::Customization
Amazon CodeWhisperer API activity on a profile. CodeWhisperer AWS::CodeWhisperer::Profile
Amazon Cognito

Amazon Cognito API activity on Amazon Cognito identity pools.

Cognito Identity Pools AWS::Cognito::IdentityPool
Amazon DynamoDB

Amazon DynamoDB API activity on streams.

DynamoDB Streams AWS::DynamoDB::Stream
Amazon Elastic Block Store

Amazon Elastic Block Store (EBS) direct APIs, such as PutSnapshotBlock, GetSnapshotBlock, and ListChangedBlocks on Amazon EBS snapshots.

Amazon EBS direct APIs AWS::EC2::Snapshot
Amazon EMR Amazon EMR API activity on a write-ahead log workspace. EMR write-ahead log workspace AWS::EMRWAL::Workspace
Amazon FinSpace

Amazon FinSpace API activity on environments.

FinSpace AWS::FinSpace::Environment
AWS Glue

AWS Glue API activity on tables that were created by Lake Formation.

Note

AWS Glue data events for tables are currently supported only in the following regions:

  • US East (N. Virginia)

  • US East (Ohio)

  • US West (Oregon)

  • Europe (Ireland)

  • Asia Pacific (Tokyo) Region

Lake Formation AWS::Glue::Table
Amazon GuardDuty

Amazon GuardDuty API activity for a detector.

GuardDuty detector AWS::GuardDuty::Detector
AWS HealthImaging

AWS HealthImaging API activity on data stores.

Medical Imaging data store AWS::MedicalImaging::Datastore
AWS IoT

AWS IoT API activity on certificates.

IoT certificate AWS::IoT::Certificate

AWS IoT API activity on things.

IoT thing AWS::IoT::Thing
AWS IoT Greengrass Version 2

Greengrass API activity from a Greengrass core device on a component version.

Note

Greengrass doesn't log access denied events.

IoT Greengrass component version AWS::GreengrassV2::ComponentVersion

Greengrass API activity from a Greengrass core device on a deployment.

Note

Greengrass doesn't log access denied events.

IoT Greengrass deployment AWS::GreengrassV2::Deployment
AWS IoT SiteWise

IoT SiteWise API activity on assets.

IoT SiteWise asset AWS::IoTSiteWise::Asset

IoT SiteWise API activity on time series.

IoT SiteWise time series AWS::IoTSiteWise::TimeSeries
AWS IoT TwinMaker

IoT TwinMaker API activity on an entity.

IoT TwinMaker entity AWS::IoTTwinMaker::Entity

IoT TwinMaker API activity on a workspace.

IoT TwinMaker workspace AWS::IoTTwinMaker::Workspace
Amazon Kendra Intelligent Ranking

Amazon Kendra Intelligent Ranking API activity on rescore execution plans.

Kendra Ranking AWS::KendraRanking::ExecutionPlan
Amazon Keyspaces (for Apache Cassandra) Amazon Keyspaces API activity on a table. Cassandra table AWS::Cassandra::Table
Amazon Kinesis Amazon Kinesis API activity on video streams, such as calls to GetMedia and PutMedia. Kinesis video stream AWS::KinesisVideo::Stream
Amazon Managed Blockchain

Amazon Managed Blockchain API activity on a network.

Managed Blockchain network AWS::ManagedBlockchain::Network

Amazon Managed Blockchain JSON-RPC calls on Ethereum nodes, such as eth_getBalance or eth_getBlockByNumber.

Managed Blockchain AWS::ManagedBlockchain::Node
Amazon Neptune Graph

Data API activities, for example queries, algorithms, or vector search, on a Neptune Graph.

Neptune Graph AWS::NeptuneGraph::Graph
AWS Private CA

AWS Private CA Connector for Active Directory API activity.

AWS Private CA Connector for Active Directory AWS::PCAConnectorAD::Connector
Amazon Q Business

Amazon Q Business API activity on an application.

Amazon Q Business application AWS::QBusiness::Application

Amazon Q Business API activity on a data source.

Amazon Q Business data source AWS::QBusiness::DataSource

Amazon Q Business API activity on an index.

Amazon Q Business index AWS::QBusiness::Index

Amazon Q Business API activity on a web experience.

Amazon Q Business web experience AWS::QBusiness::WebExperience
Amazon RDS

Amazon RDS API activity on a DB Cluster.

RDS Data API - DB Cluster AWS::RDS::DBCluster
Amazon S3

Amazon S3 API activity on access points.

S3 Access Point AWS::S3::AccessPoint

Amazon S3 Object Lambda access points API activity, such as calls to CompleteMultipartUpload and GetObject.

S3 Object Lambda AWS::S3ObjectLambda::AccessPoint
Amazon S3 on Outposts

Amazon S3 on Outposts object-level API activity.

S3 Outposts AWS::S3Outposts::Object
Amazon SageMaker Amazon SageMaker InvokeEndpointWithResponseStream activity on endpoints. SageMaker endpoint AWS::SageMaker::Endpoint

Amazon SageMaker API activity on feature stores.

SageMaker feature store AWS::SageMaker::FeatureGroup

Amazon SageMaker API activity on experiment trial components.

SageMaker metrics experiment trial component AWS::SageMaker::ExperimentTrialComponent
Amazon SNS

Amazon SNS Publish API operations on platform endpoints.

SNS platform endpoint AWS::SNS::PlatformEndpoint

Amazon SNS Publish and PublishBatch API operations on topics.

SNS topic AWS::SNS::Topic
Amazon SQS

Amazon SQS API activity on messages.

SQS AWS::SQS::Queue
AWS Supply Chain

AWS Supply Chain API activity on an instance.

Supply Chain AWS::SCN::Instance
Amazon SWF

Amazon SWF API activity on domains.

SWF domain AWS::SWF::Domain
AWS Systems Manager Systems Manager API activity on control channels. Systems Manager AWS::SSMMessages::ControlChannel
Systems Manager API activity on managed nodes. Systems Manager managed node AWS::SSM::ManagedNode
Amazon Timestream Amazon Timestream Query API activity on databases. Timestream database AWS::Timestream::Database
Amazon Timestream Query API activity on tables. Timestream table AWS::Timestream::Table
Amazon Verified Permissions

Amazon Verified Permissions API activity on a policy store.

Amazon Verified Permissions AWS::VerifiedPermissions::PolicyStore
Amazon WorkSpaces Thin Client WorkSpaces Thin Client API activity on a Device. Thin Client Device AWS::ThinClient::Device
WorkSpaces Thin Client API activity on an Environment. Thin Client Environment AWS::ThinClient::Environment
AWS X-Ray

X-Ray API activity on traces.

X-Ray trace AWS::XRay::Trace

Data events are not logged by default when you create a trail or event data store. To record CloudTrail data events, you must explicitly add the supported resources or resource types for which you want to collect activity. For more information, see Creating a trail and Create an event data store for CloudTrail events with the console.

Additional charges apply for logging data events. For CloudTrail pricing, see AWS CloudTrail Pricing.

The following example shows a single log record of a data event for the Amazon SNS Publish action.

{ "eventVersion": "1.09", "userIdentity": { "type": "AssumedRole", "principalId": "EX_PRINCIPAL_ID", "arn": "arn:aws:iam::123456789012:user/Bob", "accountId": "123456789012", "accessKeyId": "AKIAIOSFODNN7EXAMPLE", "sessionContext": { "sessionIssuer": { "type": "Role", "principalId": "AKIAIOSFODNN7EXAMPLE", "arn": "arn:aws:iam::123456789012:role/Admin", "accountId": "123456789012", "userName": "ExampleUser" }, "attributes": { "creationDate": "2023-08-21T16:44:05Z", "mfaAuthenticated": "false" } } }, "eventTime": "2023-08-21T16:48:37Z", "eventSource": "sns.amazonaws.com", "eventName": "Publish", "awsRegion": "us-east-1", "sourceIPAddress": "192.0.2.0", "userAgent": "aws-cli/1.29.16 md/Botocore#1.31.16 ua/2.0 os/linux#5.4.250-173.369.amzn2int.x86_64 md/arch#x86_64 lang/python#3.8.17 md/pyimpl#CPython cfg/retry-mode#legacy botocore/1.31.16", "requestParameters": { "topicArn": "arn:aws:sns:us-east-1:123456789012:ExampleSNSTopic", "message": "HIDDEN_DUE_TO_SECURITY_REASONS", "subject": "HIDDEN_DUE_TO_SECURITY_REASONS", "messageStructure": "json", "messageAttributes": "HIDDEN_DUE_TO_SECURITY_REASONS" }, "responseElements": { "messageId": "0787cd1e-d92b-521c-a8b4-90434e8ef840" }, "requestID": "0a8ab208-11bf-5e01-bd2d-ef55861b545d", "eventID": "bb3496d4-5252-4660-9c28-3c6aebdb21c0", "readOnly": false, "resources": [{ "accountId": "123456789012", "type": "AWS::SNS::Topic", "ARN": "arn:aws:sns:us-east-1:123456789012:ExampleSNSTopic" }], "eventType": "AwsApiCall", "managementEvent": false, "recipientAccountId": "123456789012", "eventCategory": "Data", "tlsDetails": { "tlsVersion": "TLSv1.2", "cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256", "clientProvidedHostHeader": "sns.us-east-1.amazonaws.com" } }

The next example shows a single log record of a data event for the Amazon Cognito GetCredentialsForIdentity action.

{ "eventVersion": "1.08", "userIdentity": { "type": "Unknown" }, "eventTime": "2023-01-19T16:55:08Z", "eventSource": "cognito-identity.amazonaws.com", "eventName": "GetCredentialsForIdentity", "awsRegion": "us-east-1", "sourceIPAddress": "192.0.2.4", "userAgent": "aws-cli/2.7.25 Python/3.9.11 Darwin/21.6.0 exe/x86_64 prompt/off command/cognito-identity.get-credentials-for-identity", "requestParameters": { "logins": { "cognito-idp.us-east-1.amazonaws.com/us-east-1_aaaaaaaaa": "HIDDEN_DUE_TO_SECURITY_REASONS" }, "identityId": "us-east-1:1cf667a2-49a6-454b-9e45-23199EXAMPLE" }, "responseElements": { "credentials": { "accessKeyId": "ASIAIOSFODNN7EXAMPLE", "sessionToken": "aAaAaAaAaAaAab1111111111EXAMPLE", "expiration": "Jan 19, 2023 5:55:08 PM" }, "identityId": "us-east-1:1cf667a2-49a6-454b-9e45-23199EXAMPLE" }, "requestID": "659dfc23-7c4e-4e7c-858a-1abce884d645", "eventID": "6ad1c766-5a41-4b28-b5ca-e223ccb00f0d", "readOnly": false, "resources": [{ "accountId": "111122223333", "type": "AWS::Cognito::IdentityPool", "ARN": "arn:aws:cognito-identity:us-east-1:111122223333:identitypool/us-east-1:2dg778b3-50b7-565c-0f56-34200EXAMPLE" }], "eventType": "AwsApiCall", "managementEvent": false, "recipientAccountId": "111122223333", "eventCategory": "Data" }

Insights events

CloudTrail Insights events capture unusual API call rate or error rate activity in your AWS account by analyzing CloudTrail management activity. Insights events provide relevant information, such as the associated API, error code, incident time, and statistics, that help you understand and act on unusual activity. Unlike other types of events captured in a CloudTrail trail or event data store, Insights events are logged only when CloudTrail detects changes in your account's API usage or error rate logging that differ significantly from the account's typical usage patterns.

Examples of activity that might generate Insights events include:

  • Your account typically logs no more than 20 Amazon S3 deleteBucket API calls per minute, but your account starts to log an average of 100 deleteBucket API calls per minute. An Insights event is logged at the start of the unusual activity, and another Insights event is logged to mark the end of the unusual activity.

  • Your account typically logs 20 calls per minute to the Amazon EC2 AuthorizeSecurityGroupIngress API, but your account starts to log zero calls to AuthorizeSecurityGroupIngress. An Insights event is logged at the start of the unusual activity, and ten minutes later, when the unusual activity ends, another Insights event is logged to mark the end of the unusual activity.

  • Your account typically logs less than one AccessDeniedException error in a seven-day period on the AWS Identity and Access Management API, DeleteInstanceProfile. Your account starts to log an average of 12 AccessDeniedException errors per minute on the DeleteInstanceProfile API call. An Insights event is logged at the start of the unusual error rate activity, and another Insights event is logged to mark the end of the unusual activity.

These examples are provided for illustration purposes only. Your results may vary depending on your use case.

To log CloudTrail Insights events, you must explicitly enable Insights events on a new or existing trail or event data store. For more information about creating a trail, see Creating a trail. For more information about creating an event data store, see Create an event data store for CloudTrail Insights events with the console.

Additional charges apply for Insights events. You will be charged separately if you enable Insights for both trails and event data stores. For more information, see AWS CloudTrail Pricing.

There are two events logged to show unusual activity in CloudTrail Insights: a start event and an end event. The following example shows a single log record of a starting Insights event that occurred when the Application Auto Scaling API CompleteLifecycleAction was called an unusual number of times. For Insights events, the value of eventCategory is Insight. An insightDetails block identifies the event state, source, name, Insights type, and context, including statistics and attributions. For more information about the insightDetails block, see CloudTrail Insights insightDetails element.

{ "eventVersion": "1.08", "eventTime": "2023-07-10T01:42:00Z", "awsRegion": "us-east-1", "eventID": "55ed45c5-0b0c-4228-9fe5-EXAMPLEc3f4d", "eventType": "AwsCloudTrailInsight", "recipientAccountId": "123456789012", "sharedEventID": "979c82fe-14d4-4e4c-aa01-EXAMPLE3acee", "insightDetails": { "state": "Start", "eventSource": "autoscaling.amazonaws.com", "eventName": "CompleteLifecycleAction", "insightType": "ApiCallRateInsight", "insightContext": { "statistics": { "baseline": { "average": 9.82222E-5 }, "insight": { "average": 5.0 }, "insightDuration": 1, "baselineDuration": 10181 }, "attributions": [{ "attribute": "userIdentityArn", "insight": [{ "value": "arn:aws:sts::123456789012:assumed-role/CodeDeployRole1", "average": 5.0 }, { "value": "arn:aws:sts::123456789012:assumed-role/CodeDeployRole2", "average": 5.0 }, { "value": "arn:aws:sts::123456789012:assumed-role/CodeDeployRole3", "average": 5.0 }], "baseline": [{ "value": "arn:aws:sts::123456789012:assumed-role/CodeDeployRole1", "average": 9.82222E-5 }] }, { "attribute": "userAgent", "insight": [{ "value": "codedeploy.amazonaws.com", "average": 5.0 }], "baseline": [{ "value": "codedeploy.amazonaws.com", "average": 9.82222E-5 }] }, { "attribute": "errorCode", "insight": [{ "value": "null", "average": 5.0 }], "baseline": [{ "value": "null", "average": 9.82222E-5 }] }] } }, "eventCategory": "Insight" }