AWS transfer: Document CloudWatch structured log destinations and IAM permissions
Summary
Adds guidance for delivering Transfer Family workflow execution logs to CloudWatch via a structured log destination or logging role, including required logs:* IAM permissions and updated log group/stream selection steps.
Security assessment
The diff documents a new structured CloudWatch log destination option and the logs:* IAM permissions needed to configure it, plus how to locate workflow log groups/streams. This is security-relevant logging/audit guidance but does not reference a specific vulnerability or incident.
Evidence
+To configure a structured log destination, the IAM policy for the principal that creates the workflow must contain the following permissions:
Diff
diff --git a/transfer/latest/userguide/cloudwatch-workflow.md b/transfer/latest/userguide/cloudwatch-workflow.md index defa557..b7cf946 100644 --- a//transfer/latest/userguide/cloudwatch-workflow.md +++ b//transfer/latest/userguide/cloudwatch-workflow.md @@ -16,0 +17,29 @@ CloudWatch provides consolidated auditing and logging for workflow progress and +AWS Transfer Family provides two ways to deliver managed workflow execution logs to Amazon CloudWatch: + + * **A log group that you specify (structured log destination)** – You specify a CloudWatch Logs log group as a structured log destination for the workflow, and Transfer Family delivers the workflow execution logs to that log group for you. This option does not require a logging role. To use it, provide the Amazon Resource Name (ARN) of a log group in the `StructuredLogDestinations` parameter when you create the workflow (see [StructuredLogDestinations](https://docs.aws.amazon.com/transfer/latest/APIReference/API_CreateWorkflow.html#TransferFamily-CreateWorkflow-request-StructuredLogDestinations) in the _AWS Transfer Family API Reference_). The log group must be in the same AWS account and AWS Region as the workflow. + +To configure a structured log destination, the IAM policy for the principal that creates the workflow must contain the following permissions: + + * `logs:CreateLogDelivery` + + * `logs:DeleteLogDelivery` + + * `logs:DescribeLogGroups` + + * `logs:DescribeResourcePolicies` + + * `logs:GetLogDelivery` + + * `logs:ListLogDeliveries` + + * `logs:PutResourcePolicy` + + * `logs:UpdateLogDelivery` + + * **A logging role** – You attach an IAM logging role to the server that the workflow is attached to. Transfer Family assumes the role to write the workflow execution logs to a log group named `/aws/transfer/`server-id``. For details, see [Configure CloudWatch logging role](./configure-cw-logging-role.html). + + + + +Both mechanisms write the same workflow execution log content in the same JSON format. The difference is only where the logs are delivered: to the log group that you specify, or to the `/aws/transfer/`server-id`` log group on the server by way of the logging role. + @@ -25 +54,5 @@ CloudWatch provides consolidated auditing and logging for workflow progress and - 4. Choose the log group that corresponds to your server. + 4. Choose the log group that contains your workflow logs. + + * If the workflow uses a structured log destination, choose the log group whose ARN you specified in the `StructuredLogDestinations` parameter of the workflow. + + * If the workflow uses a logging role on the server, choose the log group that corresponds to your server. For example, if your server ID is `s-1234567890abcdef0`, your log group is `/aws/transfer/s-1234567890abcdef0`. @@ -27 +60 @@ CloudWatch provides consolidated auditing and logging for workflow progress and -For example, if your server ID is `s-1234567890abcdef0`, your log group is `/aws/transfer/s-1234567890abcdef0`. + 5. On the log group details page, the most recent log streams are displayed. The log stream name for the workflow depends on which logging mechanism the workflow uses: @@ -29 +62 @@ For example, if your server ID is `s-1234567890abcdef0`, your log group is `/aws - 5. On the log group details page for your server, the most recent log streams are displayed. There are two log streams for the user that you are exploring: + * For a structured log destination, the workflow log stream is named ``workflowID`/`executionID``. For example: @@ -31 +64 @@ For example, if your server ID is `s-1234567890abcdef0`, your log group is `/aws - * One for each Secure Shell (SSH) File Transfer Protocol (SFTP) session. + w-abcdef01234567890/021345abcdef6789 @@ -33 +66 @@ For example, if your server ID is `s-1234567890abcdef0`, your log group is `/aws - * One for the workflow that is being executed for your server. The format for the log stream for the workflow is ``username`.`workflowID`.`uniqueStreamSuffix``. + * For a logging role, the server log group contains two log streams for the user that you are exploring: one for each Secure Shell (SSH) File Transfer Protocol (SFTP) session, and one for the workflow that is being executed. The format for the workflow log stream is ``username`.`workflowID`.`uniqueStreamSuffix``. @@ -47 +80 @@ The 16-digit alphanumeric identifiers listed in this example are fictitious. The -The **Log events** page for `mary-major-usa-east.1234567890abcdef0` displays the details for each user session, and the `mary.w-abcdef01234567890.021345abcdef6789` log stream contains the details for the workflow. +The **Log events** page for a workflow log stream contains the details for the workflow execution. If the workflow uses a logging role, the `mary-major-usa-east.1234567890abcdef0` stream displays the details for each user session, and the `mary.w-abcdef01234567890.021345abcdef6789` stream contains the details for the workflow. If the workflow uses a structured log destination, the `w-abcdef01234567890/021345abcdef6789` stream contains the details for the workflow.