AWS transfer documentation change
Summary
Added documentation for enabling S3 data event logging and detailed examples of data access logs including user attribution through Transfer Family sessions
Security assessment
The changes enhance audit capabilities by documenting how to track file operations (uploads/downloads/deletes) and attribute actions to specific Transfer Family users via the x-amz-onBehalfOf field. While not fixing a specific vulnerability, this improves security monitoring and forensic capabilities.
Diff
diff --git a/transfer/latest/userguide/cloudtrail-logging.md b/transfer/latest/userguide/cloudtrail-logging.md index 383877755..69a79b4a4 100644 --- a//transfer/latest/userguide/cloudtrail-logging.md +++ b//transfer/latest/userguide/cloudtrail-logging.md @@ -5 +5 @@ -Enabling CloudTrail loggingExample log entry for creating a server +Enabling CloudTrail loggingExample log entry for creating a serverData access logs @@ -59,0 +60,2 @@ To learn more about CloudTrail, see the [AWS CloudTrail User Guide](https://docs + * Data access log examples + @@ -70,0 +73,25 @@ The maximum length of the `RoleSessionName` is 64 characters. If the `RoleSessio +### Enabling Amazon S3 data events + +To track file operations performed through AWS Transfer Family on your Amazon S3 buckets, you need to enable data events for those buckets. Data events provide object-level API activity and are particularly useful for tracking file uploads, downloads, and other operations performed by AWS Transfer Family users. + +To enable Amazon S3 data events for your AWS Transfer Family server: + + 1. Open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/). + + 2. In the navigation pane, choose **Trails** , and then select an existing trail or create a new one. + + 3. Under **Data events** , choose **Edit**. + + 4. For **Data event type** , select **S3**. + + 5. Choose the Amazon S3 buckets to log data events for. You can log data events for all buckets or specify individual buckets. + + 6. Choose whether to log **Read** events, **Write** events, or both. + + 7. Choose **Save changes**. + + + + +After enabling data events, you can access these logs in the Amazon S3 bucket configured for your CloudTrail trail. The logs include details such as the user who performed the action, the action timestamp, the specific object affected, and the `onBehalfOf` field that helps trace the `userId` for actions performed through AWS Transfer Family. + @@ -137,0 +165,113 @@ The following example shows a CloudTrail log entry (in JSON format) that demonst +## Data access log examples + +When you enable Amazon S3 data events for your CloudTrail trail, you can track file operations performed through AWS Transfer Family. These logs help you monitor who accessed what data, when, and how. + +### Example log entry for successful data access + +The following example shows a CloudTrail log entry for a successful file download operation through AWS Transfer Family. + + + { + "eventVersion": "1.09", + "userIdentity": { + "type": "AssumedRole", + "principalId": "AROAEXAMPLEID:TransferSessionUser", + "arn": "arn:aws:sts::123456789012:assumed-role/TransferS3AccessRole/TransferSessionUser", + "accountId": "123456789012", + "accessKeyId": "ASIAEXAMPLEKEY", + "sessionContext": { + "sessionIssuer": { + "type": "Role", + "principalId": "AROAEXAMPLEID", + "arn": "arn:aws:iam::123456789012:role/TransferS3AccessRole", + "accountId": "123456789012", + "userName": "TransferS3AccessRole" + }, + "attributes": { + "creationDate": "2025-07-15T16:12:05Z", + "mfaAuthenticated": "true" + } + }, + "invokedBy": "transfer.amazonaws.com" + }, + "eventTime": "2025-07-15T16:15:22Z", + "eventSource": "s3.amazonaws.com", + "eventName": "GetObject", + "awsRegion": "us-east-1", + "sourceIPAddress": "transfer.amazonaws.com", + "userAgent": "transfer.amazonaws.com", + "requestParameters": { + "bucketName": "my-transfer-bucket", + "key": "users/john.doe/reports/quarterly-report-2025-Q2.pdf", + "Host": "my-transfer-bucket.s3.amazonaws.com", + "x-amz-request-payer": "requester" + }, + "responseElements": null, + "additionalEventData": { + "SignatureVersion": "SigV4", + "CipherSuite": "ECDHE-RSA-AES128-GCM-SHA256", + "bytesTransferredIn": 0, + "bytesTransferredOut": 2458732, + "x-amz-id-2": "EXAMPLE123456789+abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ=" + }, + "requestID": "EXAMPLE123456789", + "eventID": "example12-3456-7890-abcd-ef1234567890", + "readOnly": true, + "resources": [ + { + "type": "AWS::S3::Object", + "ARN": "arn:aws:s3:::my-transfer-bucket/users/john.doe/reports/quarterly-report-2025-Q2.pdf" + }, + { + "accountId": "123456789012", + "type": "AWS::S3::Bucket", + "ARN": "arn:aws:s3:::my-transfer-bucket" + } + ], + "eventType": "AwsApiCall", + "managementEvent": false, + "recipientAccountId": "123456789012", + "eventCategory": "Data", + "requestParameters": { + "x-amz-onBehalfOf": "john.doe.sessionid@s-abcd1234efgh5678" + } + } + +In this example, note the following important fields: + + * `eventName`: Indicates the S3 API operation that was performed (GetObject for a file download). + + * `requestParameters.bucketName` and `requestParameters.key`: Show which S3 object was accessed. + + * `additionalEventData.bytesTransferredOut`: Shows the size of the downloaded file in bytes. + + * `requestParameters.x-amz-onBehalfOf`: Contains the AWS Transfer Family username and session ID, allowing you to trace which AWS Transfer Family user performed the action. + + + + +The `x-amz-onBehalfOf` field is particularly important as it links the S3 API call back to the specific AWS Transfer Family user who initiated the action. This field follows the format `username.sessionid@server-id`, where: + + * `username` is the AWS Transfer Family username. + + * `sessionid` is a unique identifier for the user's session. + + * `server-id` is the ID of the AWS Transfer Family server. + + + + +### Common data access operations + +When monitoring data access through AWS Transfer Family, you'll typically see the following S3 API operations in your CloudTrail logs: + +Common S3 operations in AWS Transfer Family logs S3 API Operation | AWS Transfer Family Action | Description +---|---|--- +GetObject | File download | User downloaded a file from the server +PutObject | File upload | User uploaded a file to the server +DeleteObject | File deletion | User deleted a file from the server +ListObjects or ListObjectsV2 | Directory listing | User listed files in a directory +CopyObject | File copy | User copied a file within the server + +By monitoring these operations in your CloudTrail logs, you can track all file activities performed through your AWS Transfer Family server, helping you meet compliance requirements and detect unauthorized access. +