Logging Amazon S3 API Calls by Using AWS CloudTrail

Amazon S3 is integrated with AWS CloudTrail, a service that provides a record of actions
taken by a user, role, or an AWS service in Amazon S3. CloudTrail captures a subset
of
API calls for Amazon S3 as events, including calls from the Amazon S3 console
and from code calls to the Amazon S3 APIs. If you create a trail, you can enable
continuous delivery of CloudTrail events to an Amazon S3 bucket, including events
for
Amazon S3. If you don't configure a trail, you can still view the most recent events
in the CloudTrail console in Event history. Using the information
collected by CloudTrail, you can determine the request that was made to Amazon S3,
the IP
address from which the request was made, who made the request, when it was made, and
additional details.

Amazon S3 Information in CloudTrail

CloudTrail is enabled on your AWS account when you create the account. When supported
event activity occurs in Amazon S3, that activity is recorded in a CloudTrail event
along with other AWS service events in Event history. You can
view, search, and download recent events in your AWS account. For more
information, see Viewing
Events with CloudTrail Event History.

For an ongoing record of events in your AWS account, including events for
Amazon S3, create a trail. A trail enables CloudTrail to deliver log files to an Amazon
S3
bucket. By default, when you create a trail in the console, the trail applies to all
regions. The trail logs events from all regions in the AWS partition and delivers
the log files to the Amazon S3 bucket that you specify. Additionally, you can configure
other AWS services to further analyze and act upon the event data collected in
CloudTrail logs. For more information, see:

You can store your log files in your bucket for as long as you want, but you can
also define Amazon S3 lifecycle rules to archive or delete log files automatically.
By
default, your log files are encrypted by using Amazon S3 server-side encryption
(SSE).

Amazon S3 Bucket-Level Actions
Tracked by CloudTrail Logging

By default, CloudTrail logs bucket-level actions. Amazon S3 records are written together
with other AWS service records in a log file. CloudTrail determines when to create
and
write to a new file based on a time period and file size.

The tables in this section list the Amazon S3 bucket-level actions that are
supported for logging by CloudTrail.

In addition to these API operations, you can also use the OPTIONS object object-level
action. This action is treated like a bucket-level action in CloudTrail logging
because the action checks the cors configuration of a bucket.

Amazon S3 Object-Level Actions
Tracked by CloudTrail Logging

You can also get CloudTrail logs for object-level Amazon S3 actions. To do this, specify
the Amazon S3 object for your trail. When an object-level action occurs in your
account, CloudTrail evaluates your trail settings. If the event matches the object
that you specified in a trail, the event is logged. For more information, see
How Do I Enable Object-Level Logging for an S3 Bucket with AWS CloudTrail Data Events?
in the Amazon Simple Storage Service Console User Guide and
Data Events in the AWS CloudTrail User Guide. The
following table lists the object-level actions that CloudTrail can log:

CloudTrail will not log keynames for the keys deleted using Delete Multiple Objects
operation

Object-Level Actions
in Cross-Account Scenarios

The following are special use cases involving the object-level API calls
in cross-account scenarios and how CloudTrail logs are reported. CloudTrail always
delivers logs to the requester (who made the API call). When setting up
cross-account access, consider the examples in this section.

Note

The examples assume CloudTrail logs are appropriately configured.

Example 1: CloudTrail
Delivers Access Logs to the Bucket Owner

CloudTrail delivers access logs to the bucket owner only if the bucket owner
has permissions for the same object API. Consider the following
cross-account scenario:

Account-A owns the bucket.

Account-B (the requester) attempts to access an object in that
bucket.

CloudTrail always delivers object-level API access logs to the requester. In
addition, CloudTrail also delivers the same logs to the bucket owner only if
the bucket owner has permissions for the same API actions on that
object.

Note

If the bucket owner is also the object owner, the bucket owner
gets the object access logs. Otherwise, the bucket owner must get
permissions, through the object ACL, for the same object API to get
the same object-access API logs.

Example 2: CloudTrail Does
Not Proliferate Email Addresses Used in Setting Object ACLs

The request gets the logs along with the email information. However,
the bucket owner—if they eligible to receive logs as in example
1—gets the CloudTrail log reporting the event. However, the bucket owner
doesn't get the ACL configuration information, specifically the grantee
email and the grant. The only information the log tells the bucket owner
is that an ACL API call was made by Account-B.

CloudTrail Tracking with Amazon S3 SOAP API
Calls

CloudTrail tracks Amazon S3 SOAP API calls. Amazon S3 SOAP support over HTTP is deprecated,
but it is still available over HTTPS. For more information about Amazon S3 SOAP
support, see Appendix A: Using the SOAP API.

Important

Newer Amazon S3 features are not supported for SOAP. We recommend that you use
either the REST API or the AWS SDKs.

You can use AWS CloudTrail logs together with server access logs for Amazon S3. CloudTrail
logs
provide you with detailed API tracking for Amazon S3 bucket-level and object-level
operations, while server access logs for Amazon S3 provide you visibility into
object-level operations on your data in Amazon S3. For more information about server
access logs, see Amazon S3 Server Access Logging.

You can also use CloudTrail logs together with CloudWatch for Amazon S3. CloudTrail
integration with CloudWatch
logs delivers S3 bucket-level API activity captured by CloudTrail to a CloudWatch
log stream in
the CloudWatch log group you specify. You can create CloudWatch alarms for monitoring
specific
API activity and receive email notifications when the specific API activity occurs.
For more information about CloudWatch alarms for monitoring specific API activity,
see the
AWS CloudTrail User Guide. For more information about
using CloudWatch with Amazon S3, see Monitoring Metrics with Amazon CloudWatch.

Example: Amazon S3 Log File
Entries

A trail is a configuration that enables delivery of events as log files to an
Amazon S3 bucket that you specify. CloudTrail log files contain one or more log entries.
An
event represents a single request from any source and includes information about the
requested action, the date and time of the action, request parameters, and so on.
CloudTrail log files are not an ordered stack trace of the public API calls, so they
do
not appear in any specific order.