> For the complete documentation index, see [llms.txt](https://docs.expel.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.expel.io/connect-your-technology/a-c-integrations/amazon-aws/aws-cloudtrail/aws-cloudtrail-with-control-tower-existing-trail.md).

# AWS CloudTrail with Control Tower - Existing Trail

{% hint style="info" %}
This topic assumes you are using the default service control policies. If you encounter problems during setup, [contact Support](/support/how-to-reach-us.md) for help.
{% endhint %}

## 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](/connect-your-technology/a-c-integrations/amazon-aws/aws-cloudtrail/aws-cloudtrail-manual-setup-new-trail.md#reference) section.

## Before You Begin

{% file src="/files/EOngB5eoXAvafdGs7F1U" %}

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.

{% hint style="info" %}
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.
{% endhint %}

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](#user-content-fn-1)[^1], 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).

{% hint style="warning" %}
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.
{% endhint %}

## Step 2: Update CloudTrail CMK Policy If Applicable

{% hint style="info" %}
If your CloudTrail is *not* configured to encrypt the S3 logs using CMK, skip these steps and go directly to [Step 3](#step-3-confirm-s3-log-bucket-acl-settings). 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.
  {% endhint %}

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).

{% hint style="warning" %}
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.
{% endhint %}

4. Select **Save changes**. 

## Step 3: Confirm S3 Log Bucket ACL Settings

{% hint style="warning" %}
This step (through Step 8) must be performed from within your **AWS Control Tower Log Archive** account. See the [AWS documentation](https://docs.aws.amazon.com/controltower/latest/userguide/accounts.html) for any clarification.
{% endhint %}

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**.

{% hint style="info" %}
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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html)).
{% endhint %}

## Step 4: Set Up SNS Topic for S3 Notifications

<details>

<summary>Option 1: Use CloudFormation (Recommended)</summary>

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](#step-8-enable-s3-event-notifications-to-sns-topic).

</details>

<details>

<summary>Option 2: Manual Setup</summary>

{% hint style="warning" %}
Make sure to create the SNS topic in the same region that the S3 bucket CloudTrail events are being sent to.
{% endhint %}

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**.

</details>

## 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.

{% hint style="warning" %}
Make sure you create the SQS queue in the same region as the SNS topic and S3 bucket.
{% endhint %}

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 perio**d - 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.

<table><thead><tr><th width="211.01171875">Field</th><th>Value</th></tr></thead><tbody><tr><td>Topic ARN</td><td>Your SNS Topic ARN</td></tr><tr><td>Protocol</td><td>Select Amazon SQS</td></tr><tr><td>Endpoint</td><td>Your SNS Queue ARN</td></tr><tr><td>Enable raw message delivery</td><td>Selecting enable raw message delivery makes sure SNS does not add extra metadata headers to the message when it sends to SQS. <strong>Make sure you select this.</strong></td></tr></tbody></table>

3. Select **Create subscription**.

## Step 7: Set Up KMS Encryption for SNS and SQS

{% hint style="warning" %}
This step must be performed from within your **AWS Control Tower Log Archive** account.
{% endhint %}

1. Navigate to S**ervices > 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](#step-3-confirm-s3-log-bucket-acl-settings) 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](#step-4-set-up-sns-topic-for-s3-notifications) 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**.&#x20;
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

{% hint style="warning" %}
If you set up the Expel resources using [CloudFormation](#option-1-use-cloudformation-recommended) in Step 4, skip these steps and go to [Step 10](#step-10-complete-workbench-setup).
{% endhint %}

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](#step-1-set-up-expel-iam-role-and-policy). You can use the code provided in the **ControlTowerTemplate\_Step9.json** file. The policy grants the permissions.

{% hint style="info" %}
If you used the provided code, name it "**ExpelAssumeRole**".&#x20;
{% endhint %}

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

Now, you can add a security device in Workbench to complete the integration.&#x20;

{% hint style="info" %}
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.&#x20;

If you need help finding any of these values, see this [Reference](/connect-your-technology/a-c-integrations/amazon-aws/aws-cloudtrail/aws-cloudtrail-manual-setup-new-trail.md#reference) for detailed instructions.
{% endhint %}

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
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:&#x20;
   * **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](/support/how-to-reach-us.md).
* 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](/workbench-reference/alerts/how-expel-alerts-work.md#device-tuning).

## Reference

### Permissions Description and Explanation

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

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

[^1]: 1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
    2. Go to **Organization Settings > My Organization**.
    3. On the organization's page, look for the Organization GUID and select the **Copy** button to copy the GUID.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.expel.io/connect-your-technology/a-c-integrations/amazon-aws/aws-cloudtrail/aws-cloudtrail-with-control-tower-existing-trail.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.