AWS CloudTrail with Control Tower - Existing Trail

This manual setup guide is for those who have an existing trail that includes Control Tower available for use in their CloudTrail service.

This topic assumes you are using the default service control policies. If you encounter problems during setup, contact Support for help.

Prerequisites

1. You must already have an AWS Control Tower with Landing Zone.
2. You must have Administrator privileges in the AWS Control Tower management and Log Archive accounts.
3. You must download the attachment found at the end of this article, which includes the code blocks you need to complete this process.
4. If you use AWS Organizations, make sure you have your AWS Account ID.
5. If your organization centralizes CloudTrail logs from multiple subsidiaries into a single S3 bucket, make sure you know the AWS Organizational Unit (OU) ID for the subsidiary.
6. This is an optional prerequisite that enables us to filter logs so that only the relevant data is sent to each subsidiary's Workbench instance, preventing data overlap.

If you need help finding any of these values, see this Reference section.

Before You Begin

ControlTowerTemplates.zip

archive · 5KB

Open

Before you begin, download a zip file that contains all necessary JSON snippets you will need to complete this guide.

Step 1: Set Up Expel IAM Role and Policy

In this step you will create a permissions policy to assign to the IAM Role. For AWS Control Tower, the primary Expel role is created within the organization’s Log Archive account where the CloudTrail S3 log bucket exists.

The role and policy must be replicated across all the other accounts in the organization to allow Expel to perform investigative actions within your AWS environment. The policy replicated to the other non-Log Archive sub-accounts can be modified to exclude the policy elements providing access permissions to the S3 resources if necessary.

1. Create an IAM role and policy in the management account.

   • Navigate to the CloudFormation > Stacks service portal.
   • Select Create Stack (with new resources) and choose Upload a template file as the source.
   • Upload the ControlTowerTemplate_Step1.json file (found in the zip file you downloaded in Step 1).
   • Provide a relevant name for the stack, such as "ExpelIAMStack".
   • In the WorkbenchExternalID parameter field, enter your Workbench GUID, then click Next.
   • You can leave all defaults for configuring the stack options and click Next.
   • Verify the stack details, then check the acknowledgement and click Submit.
   • The new IAM role and attached policy should exist for Expel within the management account on completion of the stack.
2. Create IAM Role and Policy in all sub accounts.

   • Navigate to the CloudFormation > Stacksets service portal.
   • Select Create StackSet and choose Upload a template file as the source.
   • Follow the same process to fill out the stackset details as was done in deploying the stack above (Step 1.1).

If your organization centralizes CloudTrail logs from multiple subsidiaries into a single S3 bucket, you will need to either edit this IAM Role to add two additional permissions for Expel, or create a separate IAM role with those permissions.

The two additional permissions are:

• organizations:ListAccountsForParent
• organizations:ListOrganizationalUnitsForParent

If you wish to create a separate IAM Role with the two permissions, make sure to save that IAM Role ARN as your AWS OU Role ARN. You will need it when you set up the security device in Workbench.

Step 2: Update CloudTrail CMK Policy If Applicable

If your CloudTrail is not configured to encrypt the S3 logs using CMK, skip these steps and go directly to Step 3. Otherwise, you must update the key policy to provide Workbench with the kms:Decrypt permission so that we can properly get objects from the S3 bucket containing the CloudTrail logs.

• You can determine if this step applies to you by navigating to Services > CloudTrail > Trails and then selecting the trail created by Control Tower in your management account. In the General details section you see a value under Log file SSE-KMS encryption and an associated AWS KMS key populated as well.

1. Navigate to the CMK key used to encrypt the CloudTrail logs.

   • You can find the specific key arn by looking for AWS KMS Key in the General details section of the CloudTrail.
2. Select the Key policy tab and then choose Edit to change it.
3. Add the decrypt permission to the existing list of policy statements. You can find that code in ControlTowerTemplate_Step2.json file (found in the zip file you downloaded in Step 1).

Make sure to update the principal value with the correct ARN path to the Expel Role created in the Log Archive account as a result of Step 1.2 via the StackSet.

1. Select Save changes.

Step 3: Confirm S3 Log Bucket ACL Settings

This step (through Step 8) must be performed from within your AWS Control Tower Log Archive account. See the AWS documentation for any clarification.

Amazon S3 access control lists allow you to manage access to buckets and any objects contained within. We want to confirm that the S3 bucket created in your log archive account allows the bucket owner (Log Archive) and Expel by extension through the deployed role read permissions for the objects within.

1. Navigate to Services > S3 > Buckets > [Your S3 Log Bucket] (usually follows the naming scheme “aws-controltower-logs-”.
2. Select the Permissions tab, then look at the Object Ownership section to confirm the current ACL setting.
3. If you keep ACLs enabled on the bucket, then confirm the current Object Ownership is set to Bucket owner preferred.

AWS recommends that you disable ACLs on S3 for a majority of modern use cases, which will then delegate ownership to the bucket owner account (source).

Step 4: Set Up SNS Topic for S3 Notifications

Option 1: Use CloudFormation (Recommended)

1. Navigate to Services > CloudFormation > Stacks and select Create stack (with new resources).
2. In the Specify template section, select Upload a template file, and upload the ControlTowerTemplate_Step4Option1.json file. Then click Next.
3. Enter a name for the stack.
4. Enter the following required parameters:

   • S3LogBucketARN - the ARN associated with the S3 Bucket in your Log Archive account that retains the CloudTrail logs.
   • CloudTrailKeyARN - the ARN for the customer-managed kms key configured on your CloudTrail (in your management account).
5. Proceed through the rest of the wizard keeping the defaults, then select Submit to initiate the stack.
6. After the stack creation completes, make note of all values returned in the Outputs tab of the stack console. You need these returned values to complete setup in Workbench.

   • RoleARN - the IAM Role created in the log archive account needed to complete setup in Workbench.
   • SqsURL - the SQS url path needed to complete setup of in Workbench.
7. Skip to Step 8: Enable S3 event notifications to SNS topic.

Option 2: Manual Setup

Make sure to create the SNS topic in the same region that the S3 bucket CloudTrail events are being sent to.

1. Navigate to Services > Simple Notification Service > Topics and select Create Topic.
2. On the next screen, select Standard as the Type and create a Topic Name.
3. Under Access Policy, select Advanced.
4. In the JSON editor, paste the contents of the ControlTowerTemplate_Step4Option2.json file, substituting the YOUR_TOPIC_ARN and YOUR_S3_ARN fields with your values. This policy allows S3 to publish notifications to the topic for your CloudTrail bucket.
5. Select Create Topic.

Step 5: Set Up SQS Queue for SNS Notification

In this step, you will create a new SQS queue for the S3 notifications. Workbench polls notifications from this queue in order to know when new CloudTrail data is added.

Make sure you create the SQS queue in the same region as the SNS topic and S3 bucket.

1. Navigate to Services > Simple Queue Service > Queues and select Create queue.
2. On the next screen, select Standard Queue and enter a name for the new queue.
3. Set up the queue as follows:

   1. Visibility timeout - 30 Seconds.
   2. Message retention period - 7 days.
   3. Delivery delay - 0 Seconds.
   4. Maximum message size - 256 KB.
   5. Receive message wait time - 0 Seconds.
4. Under Access Policy, select Advanced.
5. In the JSON editor, paste the contents of the ControlTowerTemplate_Step5.json file, substituting the YOUR_SQS_QUEUE_ARN and YOUR_SNS_TOPIC_ARN fields with your values.

Step 6: Subscribe SQS to the SNS Topic

Now that you have created an SNS topic and SQS queue, you need to configure SNS to send events to the SQS queue.

1. Navigate to Services > Simple Notification Service > Subscriptions and select Create subscription.
2. On the next screen, configure the required fields to complete the subscription.

Field	Value
Topic ARN	Your SNS Topic ARN
Protocol	Select Amazon SQS
Endpoint	Your SNS Queue ARN
Enable raw message delivery	Selecting enable raw message delivery makes sure SNS does not add extra metadata headers to the message when it sends to SQS. Make sure you select this.

1. Select Create subscription.

Step 7: Set Up KMS Encryption for SNS and SQS

This step must be performed from within your AWS Control Tower Log Archive account.

1. Navigate to Services > Key Management Service (KMS) > Customer managed keys and select Create Key.
2. Retain the default configuration values as shown below, then select Next.
3. Fill in values for the alias and description for the key, then select Next.
4. Select any additional key administrators for the new key, then select Next until you get to the Review page.
5. Look for the Key policy generated for this key in the Review page, and add the policies to the statement list to give S3 and SNS the right permissions they need to decrypt with this key. You can find that code in the ControlTowerTemplate_Step7.json file.
6. Select Finish to complete the creation of the new key.
7. Enable Encryption on the SNS topic you created in Step 3 using the new key:

   • Navigate to Services > Simple Notification Service > Topics > YourTopic.
   • Select Edit, then select Encryption on.
   • In the Customer master key (CMK) selection, select the KMS key you created above.
   • Select Save changes.
8. Enable Encryption on the SQS topic you created in Step 4 using the new key:

   • Navigate to Services > Simple Queue Service > Queues > YourQueue.
   • Select Edit, then toggle the Encryption option on.
   • Set the Server-side encryption option to Enabled.
   • Set the Encryption key type to SSE-KMS.
   • In the Customer master key selection, select the KMS key you created above.
   • Select Save.

Step 8: Enable S3 Event Notifications to SNS Topic

In this step, you will configure the CloudTrail S3 bucket to send SNS notifications when CloudTrail adds logs to the bucket.

1. Navigate to Services > S3 > Your S3 CloudTrail Bucket.
2. Open Properties for your S3 bucket and navigate to Event notifications.
3. Select Create event notification.
4. On the next screen:

   • Enter a name for your notification rule.
   • Select All object create events from the Event types section.
   • Select SNS topic from the Destination section.
   • Select your SNS topic created in Step 3.
   • Select Save changes.

Step 9: Grant the Expel IAM Role Necessary Access

If you set up the Expel resources using CloudFormation in Step 4, skip these steps and go to Step 10.

At this point you have configured S3 notifications → SNS topic → SQS queue. The final step involves granting the existing ExpelIAM Role the necessary access to poll events from the SQS queue and the S3 bucket.

1. Navigate to Services > IAM > Roles.
2. Create and add a new inline policy to the Expel Role that was propagated to the Log Archive account as part of Step 1. You can use the code provided in the ControlTowerTemplate_Step9.json file. The policy grants the permissions.

If you used the provided code, name it "ExpelAssumeRole".

Step 10: Add AWS CloudTrail as a Security Device in Workbench

Now, you can add a security device in Workbench to complete the integration.

Before you begin, make sure you have your IAM Role ARN and SQS URL. If you use AWS Organizations, you will also need your AWS Account ID as well as the subsidiary's AWS Organizational Unit (OU) ID (the OU ID is only necessary if you use a single S3 bucket for multiple subsidiaries) and OWS OU Role ARN.

If you need help finding any of these values, see this Reference for detailed instructions.

1. Log in to Workbench.
2. In the side menu, navigate to Organization Settings > Security Devices.
3. Select Add Security Device.
4. In the search box, enter “AWS” and then select the AWS CloudTrail with Control Tower integration.
5. Select the bullets as follows:

   • “Are you using AWS organizations?” - AWS Organizations should leave it as Yes; single accounts should select No.
   • “Do you have an existing CloudTrail that you want Expel to reuse?” - leave it as Yes.
   • “How would you like to connect?” - select Manual connection.
6. Select Save.
7. On the next screen, complete the fields as follows:

   • Name - enter a name that might help you more easily identify this integration, such as “CompanyName CloudTrail”; this name will display in Workbench under the Name column, and is a text string that you can filter on.
   • Location - enter the location of your integration, for example “cloud” or “AWS cloud” or “on prem;” this is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations.
   • Role ARN - enter the IAM Role ARN you saved earlier. Format: arn:aws:iam::123456789012:role/RoleName
   • Role session name - enter a text string to label your IAM role session, such as "orgname-expel-trail-session".
   • AWS region - choose the AWS region where you created your configuration in AWS.
   • SQS URL - enter the SQS URL you copied and saved in a previous step.
   • Organization management account - If you use AWS Organizations, input your AWS Account ID; single account users can leave this field blank.
   • AWS OU ID - if you use AWS Organizations to centralize CloudTrail logs from multiple subsidiaries into a single S3 bucket, enter the AWS OU ID for the relevant subsidiary (format: ou-abc1-defghi2j); otherwise, leave this field blank. This field tells our system to filter the logs based on that ID, ensuring that each subsidiary's Workbench instance only ingests and analyzes the logs relevant to its own accounts, which helps prevent any overlap of data.

     AWS OU ID - if you use AWS Organizations to centralize CloudTrail logs from multiple subsidiaries into a single S3 bucket, enter the AWS OU ID for the relevant subsidiary (format: ou-abc1-defghi2j); otherwise, leave this field blank. This field tells our system to filter the logs based on that ID, ensuring that each subsidiary's Workbench instance only ingests and analyzes the logs relevant to its own accounts, which helps prevent any overlap of data.
   • AWS OU Role ARN - if you entered an AWS OU ID, you will also need to enter the IAM Role ARN that contains the appropriate permissions. If you chose to add these permissions to your existing IAM Role, enter the IAM Role ARN again here. If you chose to create a new IAM Role with those permissions, enter your AWS OU Role ARN. Otherwise, leave this field blank.
8. Select Save.

Your device should be created successfully within a few seconds. A few reminders:

• After your connection is healthy, it will take some time for your device to begin polling and receiving data.
• To check on the status, select the downward arrow for your device in the first column and choose View details.
• Polling will happen first; data will be received after that. You must refresh the page to see updates.
• If your device does not begin polling within 15 minutes, and does not begin receiving data within 30 minutes, contact our support team for help.
• To check if alerts are coming through, navigate to Dashboards > Alert Analysis. Scroll to the device you want to check, and select the Expel Alerts tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we tune your device.

Reference

Permissions Description and Explanation

Expel requires these permissions when connecting to AWS CloudTrail. These permissions are set to Read, except as shown below.

Permission	What it Does	Notes
ec2:DescribeRegions	Dynamically list all enabled regions for a customer account
ec2:DescribeInstances	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
ec2:DescribeSecurityGroups	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
iam:List*	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
iam:Get*	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
lambda:GetFunction	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
rds:DescribeDBInstances	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
rds:ListTagsForResource	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
eks:DescribeCluster	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
eks:ListClusters	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
ecs:ListContainerInstances	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
ecs:DescribeContainerInstances	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
ecs:DescribeClusters	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
ecs:ListClusters	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
s3:GetBucketNotification	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
s3:GetEncryptionConfiguration	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
cloudtrail:GetTrail	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
cloudtrail:DescribeTrails	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
cloudtrail:GetTrailStatus	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
cloudtrail:ListTrails	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
organizations:ListAccounts	Enumerate accounts in an org
sqs:DeleteMessage	Remove Processed messages from the queue	Requires Write permission.
sqs:ReceiveMessage	Read messages
s3:GetObject	Download cloudtrail log files
ec2:DescribeVolumes	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
ecs:DescribeTaskDefinition	Inventory
ecs:ListTaskDefinitions	Inventory
config:ListDiscoveredResources	Inventory
config:GetDiscoveredResourceCounts	Inventory
lambda:ListFunctions	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
lightsail:GetInstances	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
lightsail:GetRegions	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
s3:ListAllMyBuckets	Cloud investigative actions and inventory	Allows SOC analysts to triage issues and get additional content for the environment.
kms:Decrypt	Decrypt S3 buckets
organizations:DescribeOrganization	Organization information	Retrieves information about the organization the user's account belongs to.