Amazon S3 resource types for data events Data governance: know who uses your data and how it changes Security: detect and investigate threats Compliance: prove your controls work Logging and excluding Amazon S3 lifecycle and authentication failure events

Logging CloudTrail S3 data events for data governance, security, and compliance

Amazon S3 often stores an organization's most sensitive data, such as customer records, financial reports, and intellectual property. CloudTrail data events record object-level activity on that data: who read it, who changed it, who deleted it, and when. Data events also record operations that Amazon S3 performs on your behalf, such as lifecycle expirations and storage class transitions. This gives you a complete record of how each object changed over time.

This section describes how you can use CloudTrail S3 data events to:

Govern your data – Know who uses your data and how it changes over its lifecycle.
Secure your data – Detect and investigate data exfiltration, destructive activity, and credential misuse.
Prove compliance – Show auditors evidence of access, retention, and deletion.

By default, trails don't log data events. Additional charges apply for data events. For more information, see AWS CloudTrail Pricing.

Amazon S3 resource types for data events
Data governance: know who uses your data and how it changes
Security: detect and investigate threats
Compliance: prove your controls work
Logging and excluding Amazon S3 lifecycle and authentication failure events

Amazon S3 resource types for data events

To log CloudTrail S3 data events, specify one or more of the following values for the resources.type field in your trail's advanced event selectors. For the full list of resource types, see Data events.

Resource type	resources.type value	Description
S3	`AWS::S3::Object`	Object-level activity in general purpose buckets. Includes Amazon S3 lifecycle events and authentication failure events.
S3 Access Point	`AWS::S3::AccessPoint`	Activity on objects accessed through access points for general purpose buckets.
S3 Express	`AWS::S3Express::Object`	Object-level activity in directory buckets.
S3 Express Access Point	`AWS::S3Express::AccessPoint`	Activity on objects accessed through access points for directory buckets.
S3 Object Lambda	`AWS::S3ObjectLambda::AccessPoint`	Activity on Amazon S3 Object Lambda access points.
S3 Outposts	`AWS::S3Outposts::Object`	Object-level activity on Amazon S3 on Outposts.
S3 table	`AWS::S3Tables::Table`	Activity on tables in Amazon S3 Tables.
S3 table bucket	`AWS::S3Tables::TableBucket`	Activity on table buckets in Amazon S3 Tables.
S3 vector index	`AWS::S3Vectors::Index`	Activity on vector indexes in Amazon S3 Vectors.
S3 vector bucket	`AWS::S3Vectors::VectorBucket`	Activity on vector buckets in Amazon S3 Vectors.

Identify who performed an action

Each CloudTrail S3 data event has an eventType value that tells you whether a person or application performed the action, or whether Amazon S3 performed it.

AwsApiCall: A principal, such as an IAM user, role, or application, made the request.
AwsServiceEvent: Amazon S3 performed the action on your behalf, for example because of a lifecycle rule or a replication configuration.

The following CloudTrail S3 data events are service-initiated (AwsServiceEvent) events.

Event source	Event names	What triggers the event
`s3lifecycle.amazonaws.com`	`ExpireObject`, `ExpireRestore`, `CreateDeleteMarker`, `DeleteUpload`, `TransitionObject`, `TransitionSIAObject`, `TransitionZIAObject`, `TransitionINTObject`, `TransitionGIRObject`, `TransitionGDAObject`	An Amazon S3 Lifecycle rule. For more information about Amazon S3 Lifecycle events, see Amazon S3 lifecycle events.
`s3.amazonaws.com`	`InitiateReplication`	Amazon S3 Replication starts to replicate an object.
`s3.amazonaws.com`	`S3ComputeChecksum`, `S3ComputeObjectChecksum`	Amazon S3 computes a checksum for an object.
`s3.amazonaws.com`, `s3express.amazonaws.com`	`DeleteObject`	Amazon S3 deletes an object on your behalf.

Data governance: know who uses your data and how it changes

Data governance requires visibility into which principals access your critical data stores, where your data comes from, and what happens to it over time. CloudTrail S3 data events help you answer the following questions.

Question	Data events that answer it
Who accessed this data?	`GetObject`, `HeadObject`, `GetObjectAttributes`, `SelectObjectContent`, `GetObjectTorrent`, `ListObjects`, `ListObjectVersions`, `GetVectors`, `QueryVectors`, `ListVectors`, `WriteGetObjectResponse`
Who updated or created this data?	`PutObject`, `CopyObject`, `CreateMultipartUpload`, `UploadPart`, `UploadPartCopy`, `CompleteMultipartUpload`, `RestoreObject`, `RenameObject`, `PutVectors`
How is this data classified?	`PutObjectTagging`, `GetObjectTagging`, `DeleteObjectTagging`
What happened to this data over its lifecycle?	All events with the `s3lifecycle.amazonaws.com` event source

Security: detect and investigate threats

When a security incident occurs, CloudTrail S3 data events show which objects were accessed, which principal accessed them, from which IP address or VPC endpoint, and at what time. Use the following events to detect and investigate common threats.

Scenario	Data events to analyze
Data exfiltration	High volumes of `GetObject`, `SelectObjectContent`, or `QueryVectors` from a single principal, IP address (`sourceIPAddress`), or VPC endpoint (`vpcEndpointId`)
Destructive or ransomware-like activity	`DeleteObject`, `DeleteObjects`, `DeleteVectors`, overwrites with `PutObject`, and `UpdateObjectEncryption`
Changes to object permissions	`PutObjectAcl`, `GetObjectAcl`
Credential misuse and probing	Events with the `s3-authn-errors.amazonaws.com` event source
Directory bucket session activity	`CreateSession`

Investigate authentication failures

Amazon S3 authentication failure events record requests that Amazon S3 rejected because the request couldn't be authenticated. These events use the s3-authn-errors.amazonaws.com event source.

A spike in authentication failures can indicate that someone is using stolen, expired, or guessed credentials against your buckets. Other failed requests, such as requests denied by a bucket policy (AccessDenied), are logged with their original event source and event name.

Determine whether a person or a lifecycle rule deleted an object

Check the eventType and eventSource fields of the event. If eventType is AwsServiceEvent and eventSource is s3lifecycle.amazonaws.com, a lifecycle rule removed the object. If eventType is AwsApiCall, the userIdentity element shows which principal deleted it.

Compliance: prove your controls work

Regulated industries must continuously prove who accessed what data, when, and whether that access was authorized. CloudTrail S3 data events provide this evidence at the API-call level, recorded by AWS rather than reported by your application.

Requirement	Data events and features
Proof of deletion or retention	`DeleteObject`, `DeleteObjects`, and lifecycle events such as `ExpireObject` and `CreateDeleteMarker`. These events show when each object was removed and whether a principal or a lifecycle rule removed it.
Data residency	`InitiateReplication` events show when Amazon S3 replicates objects, so you can confirm where copies of your data go.
Access reviews	Read events, such as `GetObject` and `HeadObject`, on in-scope buckets show who accessed regulated data.
Continuous monitoring of logging	Use AWS Config and AWS Security Hub CSPM to verify that CloudTrail S3 data event logging stays turned on. See the following section.

Verify that CloudTrail S3 data event logging is turned on

Use the following controls to check continuously that your accounts log CloudTrail S3 data events:

AWS Config: The cloudtrail-s3-dataevents-enabled managed rule checks whether at least one trail logs CloudTrail S3 data events for all buckets, or for the buckets that you specify.
AWS Security Hub CSPM: The S3.22 and S3.23 controls check whether your account logs object-level write events and read events for all general purpose buckets.

To protect the integrity of your logs, turn on log file integrity validation for your trails. For more information about log file integrity validation, see Validating CloudTrail log file integrity.

Logging and excluding Amazon S3 lifecycle and authentication failure events

CloudTrail logs two categories of CloudTrail S3 data events that aren't direct requests from your principals:

Lifecycle events record actions that Amazon S3 performs because of your Amazon S3 Lifecycle rules. These events use the s3lifecycle.amazonaws.com event source and the AwsServiceEvent event type.
Authentication failure events record requests that Amazon S3 rejected because they couldn't be authenticated. These events use the s3-authn-errors.amazonaws.com event source.

Both categories are logged for the AWS::S3::Object resource type (general purpose buckets). If your trail already logs AWS::S3::Object data events, you receive these events automatically. You don't need to change your configuration. These events are charged as data events.

Amazon S3 lifecycle events

Event name	Description	S3 server access logs operation
`ExpireObject`	A lifecycle rule permanently deleted an object.	`S3.EXPIRE.OBJECT`
`ExpireRestore`	A lifecycle rule expired the temporary copy of an object that was restored from an archive storage class.	`S3.EXPIRE.RESTORE`
`CreateDeleteMarker`	A lifecycle rule added a delete marker to an object in a versioned bucket.	`S3.CREATE.DELETEMARKER`
`DeleteUpload`	A lifecycle rule stopped an incomplete multipart upload and deleted its parts.	`S3.DELETE.UPLOAD`
`TransitionObject`	A lifecycle rule moved an object to S3 Glacier Flexible Retrieval.	`S3.TRANSITION.OBJECT`
`TransitionSIAObject`	A lifecycle rule moved an object to S3 Standard-IA.	`S3.TRANSITION_SIA.OBJECT`
`TransitionZIAObject`	A lifecycle rule moved an object to S3 One Zone-IA.	`S3.TRANSITION_ZIA.OBJECT`
`TransitionINTObject`	A lifecycle rule moved an object to S3 Intelligent-Tiering.	`S3.TRANSITION_INT.OBJECT`
`TransitionGIRObject`	A lifecycle rule moved an object to S3 Glacier Instant Retrieval.	`S3.TRANSITION_GIR.OBJECT`
`TransitionGDAObject`	A lifecycle rule moved an object to S3 Glacier Deep Archive.	`S3.TRANSITION_GDA.OBJECT`

Each lifecycle event includes the bucket name, object key, version ID, object size, and, for transitions, the destination storage class.

Considerations

To log only some of these events, or to exclude them, use advanced event selectors with a condition on the eventSource field. Basic event selectors can't filter on eventSource.
Trails can use either basic event selectors or advanced event selectors, but not both. If you apply advanced event selectors to a trail, they overwrite its existing basic event selectors.
A condition of eventType NotEquals AwsServiceEvent, or the Exclude AWS service initiated events log selector template in the console, excludes lifecycle events and all other service-initiated Amazon S3 events, such as InitiateReplication and checksum events. To exclude only lifecycle events, filter on eventSource instead.
When you specify more than one value for a NotEquals condition, CloudTrail excludes events that match any of the values. For more information, see How CloudTrail evaluates multiple conditions for a field.

Examples: Log Amazon S3 lifecycle and authentication failure events

Examples:

Example 1: Log all CloudTrail S3 data events, including lifecycle and authentication failure events
Example 2: Log only lifecycle events
Example 3: Log only authentication failure events
Example 4: Log lifecycle events for a specific bucket

Example 1: Log all CloudTrail S3 data events, including lifecycle and authentication failure events

The following AWS CLI command configures a trail to log all data events for objects in general purpose buckets. The trail logs object API activity, lifecycle events, and authentication failure events.


aws cloudtrail put-event-selectors \
--trail-name trailName \
--advanced-event-selectors \
'[
  {
    "Name": "Log all S3 data events",
    "FieldSelectors": [
      { "Field": "eventCategory", "Equals": ["Data"] },
      { "Field": "resources.type", "Equals": ["AWS::S3::Object"] }
    ]
  }
]'

Example 2: Log only lifecycle events

The following AWS CLI command configures a trail to log only Amazon S3 lifecycle events. You can use a dedicated trail that delivers to a separate S3 bucket to give auditors evidence of retention and deletion without giving them access to your other activity.


aws cloudtrail put-event-selectors \
--trail-name trailName \
--advanced-event-selectors \
'[
  {
    "Name": "Log only S3 lifecycle events",
    "FieldSelectors": [
      { "Field": "eventCategory", "Equals": ["Data"] },
      { "Field": "resources.type", "Equals": ["AWS::S3::Object"] },
      { "Field": "eventSource", "Equals": ["s3lifecycle.amazonaws.com"] }
    ]
  }
]'

Example 3: Log only authentication failure events

The following AWS CLI command configures a trail to log only Amazon S3 authentication failure events. You can send these events to a trail that your security team monitors for credential misuse.


aws cloudtrail put-event-selectors \
--trail-name trailName \
--advanced-event-selectors \
'[
  {
    "Name": "Log only S3 authentication failure events",
    "FieldSelectors": [
      { "Field": "eventCategory", "Equals": ["Data"] },
      { "Field": "resources.type", "Equals": ["AWS::S3::Object"] },
      { "Field": "eventSource", "Equals": ["s3-authn-errors.amazonaws.com"] }
    ]
  }
]'

Example 4: Log lifecycle events for a specific bucket

The following AWS CLI command configures a trail to log lifecycle events for objects in one bucket. Replace amzn-s3-demo-bucket with the name of your bucket.


aws cloudtrail put-event-selectors \
--trail-name trailName \
--advanced-event-selectors \
'[
  {
    "Name": "Log S3 lifecycle events for one bucket",
    "FieldSelectors": [
      { "Field": "eventCategory", "Equals": ["Data"] },
      { "Field": "resources.type", "Equals": ["AWS::S3::Object"] },
      { "Field": "eventSource", "Equals": ["s3lifecycle.amazonaws.com"] },
      { "Field": "resources.ARN", "StartsWith": ["arn:aws:s3:::amzn-s3-demo-bucket/"] }
    ]
  }
]'

Examples: Exclude Amazon S3 lifecycle and authentication failure events

If you don't need these events, you can exclude them to reduce costs while you continue to log all other CloudTrail S3 data events.

Examples:

Example 5: Exclude lifecycle events
Example 6: Exclude authentication failure events
Example 7: Exclude both lifecycle and authentication failure events
Example 8: Exclude lifecycle storage class transitions only
Exclude lifecycle events by using the console

Example 5: Exclude lifecycle events

The following AWS CLI command configures a trail to log all CloudTrail S3 data events except lifecycle events. The trail continues to log all requests made by your principals.


aws cloudtrail put-event-selectors \
--trail-name trailName \
--advanced-event-selectors \
'[
  {
    "Name": "Log S3 data events but exclude lifecycle events",
    "FieldSelectors": [
      { "Field": "eventCategory", "Equals": ["Data"] },
      { "Field": "resources.type", "Equals": ["AWS::S3::Object"] },
      { "Field": "eventSource", "NotEquals": ["s3lifecycle.amazonaws.com"] }
    ]
  }
]'

Example 6: Exclude authentication failure events

The following AWS CLI command configures a trail to log all CloudTrail S3 data events except authentication failure events. The trail continues to log all other CloudTrail S3 data events, including other failed requests such as AccessDenied errors.


aws cloudtrail put-event-selectors \
--trail-name trailName \
--advanced-event-selectors \
'[
  {
    "Name": "Log S3 data events but exclude authentication failure events",
    "FieldSelectors": [
      { "Field": "eventCategory", "Equals": ["Data"] },
      { "Field": "resources.type", "Equals": ["AWS::S3::Object"] },
      { "Field": "eventSource", "NotEquals": ["s3-authn-errors.amazonaws.com"] }
    ]
  }
]'

Example 7: Exclude both lifecycle and authentication failure events

The following AWS CLI command configures a trail to log all CloudTrail S3 data events except lifecycle and authentication failure events.


aws cloudtrail put-event-selectors \
--trail-name trailName \
--advanced-event-selectors \
'[
  {
    "Name": "Log S3 data events but exclude lifecycle and authentication failure events",
    "FieldSelectors": [
      { "Field": "eventCategory", "Equals": ["Data"] },
      { "Field": "resources.type", "Equals": ["AWS::S3::Object"] },
      { "Field": "eventSource", "NotEquals": ["s3lifecycle.amazonaws.com", "s3-authn-errors.amazonaws.com"] }
    ]
  }
]'

Example 8: Exclude lifecycle storage class transitions only

Storage class transitions are often the highest-volume lifecycle events. The following AWS CLI command logs all CloudTrail S3 data events, including lifecycle expirations, delete markers, and incomplete multipart upload cleanups, but excludes storage class transitions. The example uses two selectors: the first logs all non-lifecycle events, and the second logs lifecycle events whose names don't start with Transition.


aws cloudtrail put-event-selectors \
--trail-name trailName \
--advanced-event-selectors \
'[
  {
    "Name": "Log S3 data events except lifecycle events",
    "FieldSelectors": [
      { "Field": "eventCategory", "Equals": ["Data"] },
      { "Field": "resources.type", "Equals": ["AWS::S3::Object"] },
      { "Field": "eventSource", "NotEquals": ["s3lifecycle.amazonaws.com"] }
    ]
  },
  {
    "Name": "Log S3 lifecycle events except transitions",
    "FieldSelectors": [
      { "Field": "eventCategory", "Equals": ["Data"] },
      { "Field": "resources.type", "Equals": ["AWS::S3::Object"] },
      { "Field": "eventSource", "Equals": ["s3lifecycle.amazonaws.com"] },
      { "Field": "eventName", "NotStartsWith": ["Transition"] }
    ]
  }
]'

Exclude lifecycle events by using the console

Open the CloudTrail console at https://console.aws.amazon.com/cloudtrail/.
In the navigation pane, choose Trails, and then choose the trail that you want to update.
In Data events, choose Edit.
For Resource type, select S3.
For Log selector template, select Custom.
Under Advanced event selectors, choose + Condition. For Field, select eventSource. For Operator, select does not equal. For Value, enter s3lifecycle.amazonaws.com.
To also exclude authentication failure events, add a second value of s3-authn-errors.amazonaws.com.
Choose Save changes.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Aggregating data events

Suppressing recursive events with recursive logging

Logging CloudTrail S3 data events for data governance, security, and compliance

Contents

Amazon S3 resource types for data events

Identify who performed an action

Data governance: know who uses your data and how it changes

Security: detect and investigate threats

Investigate authentication failures

Determine whether a person or a lifecycle rule deleted an object

Compliance: prove your controls work

Verify that CloudTrail S3 data event logging is turned on

Logging and excluding Amazon S3 lifecycle and authentication failure events

Amazon S3 lifecycle events

Considerations

Examples: Log Amazon S3 lifecycle and authentication failure events

Examples:

Example 1: Log all CloudTrail S3 data events, including lifecycle and authentication failure events

Example 2: Log only lifecycle events

Example 3: Log only authentication failure events

Example 4: Log lifecycle events for a specific bucket

Examples: Exclude Amazon S3 lifecycle and authentication failure events

Examples:

Example 5: Exclude lifecycle events

Example 6: Exclude authentication failure events

Example 7: Exclude both lifecycle and authentication failure events

Example 8: Exclude lifecycle storage class transitions only

Exclude lifecycle events by using the console