> 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-govcloud-cloudtrail-manual-setup-new-trail.md).
# AWS GovCloud CloudTrail Manual Setup - New Trail
This setup guide takes you through all required manual configurations when creating a new trail in AWS, to allow Expel to access your S3 bucket securely via an API. It also shows you how to add GovCloud CloudTrail as a security device in Workbench, which completes your portion of the setup. We will then manually enable event ingestion for the integration.
## Scope and Limitations
When choosing to set up this integration, remember the following:
* AWS GovCloud must be onboarded manually. You cannot onboard via CloudFormation.
* This integration supports a single AWS GovCloud account (AWS organizations are not supported), so you must manually create your IAM policy.
* These steps are intended to show the necessary settings that must be configured in order for your Expel integration to work, with basic instructions for how to do so; they do not cover most of the optional settings or explain every possible option in AWS. There are a number of ways to customize your AWS configurations based on your own environment or protocols.
## Prerequisites
1. Using a GovCloud environment requires completing a **legal addendum** before Expel can enable event ingestion for this integration. Please [contact Support](/support/how-to-reach-us.md) for assistance in completing this addendum.
2. Verify you have the necessary permissions to create and modify IAM policies and roles for your AWS account.
3. Make sure you are in the proper AWS account if you manage more than one account.
4. Check the AWS GovCloud region in the top menu bar (i.e. us-gov-east-2, us-gov-west-1, etc.) and make sure you are in the GovCloud home region you want to be in; you must use the same GovCloud home region throughout the entire AWS configuration process, and you must later specify this region correctly in Workbench.
5. Make sure you can log into Workbench successfully, and are able to see your organization settings.
* This is a good time to copy and save your Workbench GUID, which is a unique alphanumeric value assigned by Expel to your organization and found in the My Organization page; see the [Reference](#workbench-guid) for detailed instructions.
6. Create a new file or other space to keep track of all of the names, ARNs, and other values from the AWS configuration as you go (a list of all needed values is below, and additional help is available in the [Reference](#reference)).
## Before You Begin
During the AWS configuration process, you will need to copy out and save a number of values as they are added by you (e.g. the AWS KMS Alias) or generated by AWS (e.g. the SQS Queue ARN). Knowing each of these values is necessary to successfully complete all AWS configuration steps and to also add AWS as a security device in Workbench.
{% hint style="info" %}
For examples of what some of these values look like or instructions on where to find them if you forget to save one of them, refer to the [Reference](#reference).
{% endhint %}
These include, in the order they are created or generated:
* Workbench GUID (if you do not have it yet, [get it now](#workbench-guid))
* AWS GovCloud Region
* S3 Bucket Name
* AWS KMS Alias
* S3 Bucket ARN
* SQS Queue ARN
* SQS URL
* AWS KMS Key ARN
* IAM Access Policy ARN
* IAM Role ARN
## Step 1: Create a New Trail
{% hint style="warning" %}
Before you begin, make sure you are in the GovCloud management console.
Also, check the top menu bar to be sure you are in the GovCloud home region you wish to set for the trail (e.g. us-gov-west-1). You will need to be in the same GovCloud home region throughout this guide, and also choose the correct region in Workbench in [Step 8](#step-8-add-aws-cloudtrail-as-a-security-device-in-workbench).
{% endhint %}
In this step, you will create a new trail, new S3 bucket, and new AWS KMS key within your chosen GovCloud home region.
1. Use the Search bar to quickly navigate to CloudTrail, or find it in the Services menu.
2. Select **Create trail**.
3. Enter a **trail name**, such as "GlobalCloudTrail".
4. **AWS Organizations only** - select the **Enable for all accounts in my organization** checkbox.
5. In Storage location, leave **Create new s3 bucket** selected.
* Use the default for the **Trail log bucket and folder**, or enter a new unique name. *Remember that if you choose to create your own name, it must be unique to ALL of AWS — not just to your instance — or the trail creation will fail. You can append your desired name with the alphanumeric values from the default name to ensure uniqueness.*
* Make a note of your **S3 bucket name**, as you will need it for a later step.
* Leave Log file SSE-KMS encryption as **Enabled**.
* Leave the **New** radio button selected.
* Enter an **alias name** for the AWS KMS Key.
* Make a note of your **AWS KMS Key alias**, as you will need it in later steps.
6. In Additional settings:
* Leave Log file validation as **Enabled**.
* Leave SNS notification delivery **unchecked**.
7. Leave the CloudWatch Logs and Tags section as is, unless you need to change them for your own protocols, and do not edit the Policy document.
8. Select **Next**.
9. Leave the Choose Log Events screen as is.
* It should have **Management Events** selected, and both **Read** and **Write** selected for API activity.
10. Select **Next**.
11. You can now review your trail's settings before creating it, if you wish.
12. Select **Create trail**.
13. You will be taken to the Trails list and should see your new trail.
## Step 2: Edit the S3 Bucket Encryption Settings
In this step, you will set your default S3 bucket encryption to server-side encryption with AWS Key Management Service keys (SSE-KMS), and instruct Amazon to use your AWS KMS key’s encryption policy for your log files instead of using SSE-S3 encryption (Amazon’s default).
{% hint style="info" %}
You will configure the key’s policy in a later step.
{% endhint %}
1. Use the Search bar to quickly navigate to S3, or find it in the Services menu.
2. Look for your new S3 bucket in the list and select it.
3. Select the **Properties** tab.
4. First, copy the ARN and save it to a safe place as your **S3 Bucket ARN** (you will need it for a later step). The format should look something like this: `arn:aws-us-gov:s3:::YourS3BucketName`
5. Next, scroll to Default encryption and select **Edit**.
6. Select **Server-side encryption with AWS Key Management Service keys (SSE-KMS)**.
7. Under AWS KMS key, select **Choose from your AWS KMS keys**.
8. Select the **AWS KMS key** you created in [Step 1](#step-1-create-a-new-trail) (the alias will display in small print below the key).
9. Leave the Bucket Key as **Enable**.
10. Select **Save changes**.
## Step 3: Create the SQS Queue
Next, we'll create a dedicated SQS queue to receive messages from the S3 bucket, and edit the access policy to allow the S3 bucket to send messages to it. Expel will use this queue to poll for notifications of new CloudTrail data, and then will update Workbench accordingly.
1. Use the Search bar to quickly navigate to Simple Queue Service (SQS), or find it in the Services menu.
2. Select **Create queue**.
3. In the Details section:
* Leave **Standard** as the type.
* Enter a **name** in the Name field.
4. In the Configuration section:
* Change the Message Retention period to **7 days**.
* Leave all other defaults.
5. In the Encryption section:
* Leave Server-side encryption as **Enabled**.
* Choose **AWS Key Management Service key (SSE-KMS)** as the encryption key type.
* Choose your **AWS KMS Alias** from the Customer master key dropdown.
* Leave the data key reuse period as the default.
6. In the Access policy section:
* Select **Advanced**.
* First, go to the Resource value and copy the ARN, then save it to a safe place as your **SQS Queue ARN** (you will need it for your new access policy).
* Highlight and delete the existing policy, and paste the below policy instead.
{% hint style="warning" %}
Make sure to use your SQS Queue ARN as the `Resource` value and your S3 Bucket ARN as the `aws:SourceARN` value.
{% endhint %}
```
{
"Version": "2012-10-17",
"Id": "__default_policy_ID",
"Statement": [
{
"Sid": "__owner_statement",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "SQS:SendMessage",
"Resource": "YOUR_SQS_QUEUE_ARN",
"Condition": {
"ArnLike": {
"aws:SourceArn": "YOUR_S3_BUCKET_ARN"
}
}
}
]
}
```
{% hint style="warning" %}
**Important:** Did you use your SQS Queue ARN and S3 Bucket ARN in the new code? Check to be sure before continuing.
{% endhint %}
7. Leave the remaining sections as is and select **Create queue**.
8. Before leaving the confirmation screen, copy the URL and save it to a safe place as your **SQS URL** (you will need it in a later step).
## Step 4: Edit the AWS KMS Key Policy
In an earlier step, you configured your S3 bucket to use your AWS KMS key for encryption. Now, you must append the key’s encryption policy to allow the S3 bucket and SQS queue to communicate securely via encryption.
1. Use the Search bar to quickly navigate to Key Management Service, or find it in the Services menu.
2. From the Customer Managed Keys list, select your **AWS KMS alias**.
3. First, copy the ARN and save it to a safe place as your **AWS KMS Key ARN** (you will need it in a later step). The format should look something like this: `arn:aws-us-gov:kms:us-west-2:123456789012:key/123a4567-890b-1234-c5d6-7ef89012g345`
4. In the Key policy section, select **Edit** and [append](#appending-json-code) these JSON objects to the code.
{% hint style="warning" %}
Make sure to use your S3 Bucket ARN as the `aws:SourceArn` value.
{% endhint %}
```
,
{
"Sid": "Allow cloudtrail bucket to encrypt/decrypt SQS",
"Effect": "Allow",
"Principal": {
"Service": "s3.amazonaws.com"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "*",
"Condition": {
"StringLike": {
"aws:SourceArn": "YOUR_S3_BUCKET_ARN"
}
}
}
```
{% hint style="warning" %}
**Important:** Did you use your S3 bucket ARN and SNS Topic ARN in the appended code? Check to be sure before continuing.
{% endhint %}
5. Select **Save changes**.
## Step 5: Enable S3 Event Notifications
Now that we've fully configured the communications between the S3 bucket and SQS queue, we can create an event notification. This notification will tell the S3 bucket to send certain events (we will specify which ones) to the SQS queue whenever CloudTrail adds event logs to the bucket.
1. Use the Search bar to quickly navigate to S3, or find it in the Services menu.
2. Select your S3 bucket.
3. Select **Properties**.
4. Go to the Event Notifications section and select **Create event notification**. Then:
* Enter an **event name**.
* In the Event types section, use the checkbox to enable **All object create events**. Leave the rest of the boxes unchecked.
* In the Destination section, select **SQS queue** and then choose your SQS queue from the dropdown.
5. Select **Save changes**.
## Step 6: Create the IAM Policy
Expel will be granted permissions to your AWS account(s) based on a corresponding IAM policy.
1. Use the Search bar to quickly navigate to IAM service, or find it in the Services menu.
2. Navigate to **Access Management > Policies**.
3. Select **Create policy**.
4. Select the **JSON** tab.
5. Remove the existing policy and copy this one in instead.
{% hint style="warning" %}
Make sure to replace the SQS Queue ARN, S3 Bucket ARN, and KMS Key ARN with your own.
{% endhint %}
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ec2:DescribeRegions",
"ec2:DescribeSecurityGroups",
"iam:List*",
"iam:Get*",
"rds:DescribeDBInstances",
"rds:ListTagsForResource",
"organizations:ListAccounts",
"ec2:Describe volumes",
"ecs:DescribeTaskDefinition",
"ecs:ListTaskDefinitions",
"lambda:GetFunction",
"lambda:ListFunctions",
"s3:ListAllMyBuckets",
"s3:GetBucketNotification",
"s3:GetEncryptionConfiguration",
"cloudtrail:GetTrailStatus",
"cloudtrail:DescribeTrails",
"cloudtrail:GetTrail",
"cloudtrail:ListTrails",
"config:ListDiscoveredResources",
"config:GetDiscoveredResourceCounts",
"eks:DescribeCluster",
"eks:ListClusters",
"ecs:ListContainerInstances",
"ecs:DescribeContainerInstances",
"ecs:DescribeClusters",
"ecs:ListClusters",
"organizations:DescribeOrganization"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"sqs:DeleteMessage",
"sqs:ReceiveMessage"
],
"Resource": "YOUR_SQS_QUEUE_ARN"
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": "YOUR_S3_BUCKET_ARN/*"
},
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": "YOUR_KMS_KEY_ARN"
}
]
}
```
{% hint style="warning" %}
**Important:** Did you use your SQS Queue ARN, S3 Bucket ARN, and KMS Key ARN in the new code? Check to be sure before continuing.
{% endhint %}
6. Select **Next**.
7. Enter "ExpelAccessPolicy" as the policy name.
8. Select **Create policy**.
## Step 7: Create the IAM Role
Expel will authenticate its credentials using an IAM Role. Before you begin, make sure you have your [Workbench GUID](#workbench-guid).
1. Use the Search bar to quickly navigate to IAM service, or find it in the Services menu.
2. Navigate to **Access Management > Roles**.
3. Select **Create Role**.
4. Select **Custom trust policy** as the trusted entity type.
5. Remove the existing policy and copy this one in instead.
{% hint style="warning" %}
Make sure to replace the Workbench GUID with your own.
{% endhint %}
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws-us-gov:iam::071857701673:user/ExpelCloudService"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "YOUR_WORKBENCH_GUID"
}
}
}
]
}
```
6. Select **Next**.
7. Locate your **IAM policy** (from [Step 6](#step-6-create-the-iam-policy); this should be the ExpelAccessPolicy) in the Permissions Policies section, and select the checkbox next to it.
8. Select **Next**.
9. Enter "ExpelAssumeRole" as the role name.
10. Select **Create Role**.
11. Before you leave the page, copy and save your **IAM Role ARN**, as you will need it in the next step.
## Step 8: Add AWS CloudTrail as a Security Device in Workbench
Now, we can add a security device in Workbench to complete the integration.
{% hint style="info" %}
Before you begin, make sure you have your IAM Role ARN, SQS URL, and AWS GovCloud region. If you need additional help finding any of these values, see the [Reference](#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 integration.
5. Select the bullets as follows:
* “Are you using AWS organizations?” - select **No**.
* “Do you have an existing CloudTrail that you want Expel to reuse?” - select **No**.
* “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 GovCloud”; 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;” 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** - paste in your IAM Role ARN.
* **Role session name** - enter a text string to label your IAM role session, such as "orgname-expel-trail-session".
* **AWS region** - select the AWS GovCloud region where your SQS queue resides.
* **SQS URL** - paste in your SQS URL.
* **Organization management account** - leave this field blank.
8. Select **Save**.
9. Select **Done** to close the window.
10. You must now [notify Support](/support/how-to-reach-us.md) to let us know you have completed these steps. If you have not yet completed the required legal addendum so that we can enable GovCloud ingestion of events, please also work with support on this task.
A few reminders about monitoring your security device after we have enabled ingestion:
* 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.
* 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).
## Troubleshooting
### S3 Event Notification Errors (Step 5)
This error is encountered when selecting **Save changes**. It generally displays for one of the following reasons:
1. You left one of your ARN values out of a JSON object in a prior step, put an ARN in the wrong location, or formatted an ARN incorrectly.
2. The JSON objects were copied, appended, or formatted incorrectly in a prior step.
3. You used an S3 bucket name that someone else in the AWS ecosystem is already using (even if nobody at your organization is using it).
4. You have forgotten to enable something, or have configured something incorrectly, in one of the prior steps.
* Examples include not choosing your AWS KMS key from the dropdown menu when setting up default encryption in [Step 2](#step-2-edit-the-s3-bucket-encryption-settings), or not using the same GovCloud region throughout your AWS configuration.
### S3 Bucket Naming
You must use an S3 bucket name that nobody else in the AWS ecosystem is using. You can avoid this problem by using the default name, or by appending your chosen name with the numerical values from the default name that is generated.
### Appending JSON Code
Make sure to put this JSON snippet in the correct place, using a comma, and make sure the final bracket is still there. Lines 82-99 of your JSON code should look like this (the appended part is highlighted, beginning with the `,`):
{
"Version": "2012-10-17",
"Id": "Key policy created by CloudTrail",
"Statement": [
{
"Sid": "Enable IAM User Permissions",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws-us-gov:sts::241008450902:assumed-role/AWSReservedSSO_AdministratorAccess_34826aa3e04a2a86/elizabeth.haynes@expel.io",
"arn:aws-us-gov:iam::241008450902:root"
]
},
"Action": "kms:*",
"Resource": "*"
},
{
"Sid": "Allow CloudTrail to encrypt logs",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": "kms:GenerateDataKey*",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:SourceArn": "arn:aws-us-gov:cloudtrail:us-east-1:241008450902:trail/echtrail070825"
},
"StringLike": {
"kms:EncryptionContext:aws-us-gov:cloudtrail:arn": "arn:aws-us-gov:cloudtrail:*:241008450902:trail/*"
}
}
},
{
"Sid": "Allow CloudTrail to describe key",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": "kms:DescribeKey",
"Resource": "*"
},
{
"Sid": "Allow principals in the account to decrypt log files",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": [
"kms:Decrypt",
"kms:ReEncryptFrom"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:CallerAccount": "241008450902"
},
"StringLike": {
"kms:EncryptionContext:aws:cloudtrail:arn": "arn:aws-us-gov:cloudtrail:*:241008450902:trail/*"
}
}
},
{
"Sid": "Enable cross account log decryption",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": [
"kms:Decrypt",
"kms:ReEncryptFrom"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:CallerAccount": "241008450902"
},
"StringLike": {
"kms:EncryptionContext:aws:cloudtrail:arn": "arn:aws-us-gov:cloudtrail:*:241008450902:trail/*"
}
}
},
{
"Sid": "Allow cloudtrail bucket to encrypt/decrypt SQS",
"Effect": "Allow",
"Principal": {
"Service": "s3.amazonaws.com"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "*",
"Condition": {
"StringLike": {
"aws:SourceArn": "arn:aws-us-gov:s3:::S3BucketName"
}
}
}
]
}
## Reference
### ARNs and URLs
This chart gives examples of ARNs and the SQS URL so you can check on the general formatting, and also tells you where to find any of the values if you’ve forgotten to copy and save them during the configuration process.
| Value | Where to Find | Example |
|---|
| S3 Bucket ARN | S3 > Buckets > bucket name > Properties | arn:aws-us-gov:s3:::MyS3BucketARN |
| AWS KMS Key ARN | Key Management Service > key alias > General configuration section | arn:aws-us-gov:kms:us-west-2:123456789012:key/123a4567-890b-1234-c5d6-7ef89012g345 |
| SQS Queue ARN | Simple Queue Service > queue name > Details section | arn:aws-us-gov:sqs:us-east-1:123456789012:MySQSQueueName |
| SQS URL | Simple Queue Service > queue name > Details section | https://sqs.us-west-1.amazonaws.com/123456789012/MySQSQueueName |
| IAM Role ARN | IAM > Access Management > Roles > role name > Summary section | arn:aws-us-gov:iam::123456789012:role/RoleName
(most users will look for the ExpelAssumeRole) |
### Workbench GUID
The Workbench GUID is a unique alphanumeric value assigned by Expel to your organization.
**Format**
`a123b456-7c89-0def-g1hi-2j3k45l6mn7o`
**Where to Find**
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.
{% hint style="info" %}
If you have multiple organizations, you must first select the organization name that will be associated with your integration to access the page with the Copy button. Or, you can stay on the page and highlight then copy the GUID shown for that organization in the GUID column.
{% endhint %}
---
# 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-govcloud-cloudtrail-manual-setup-new-trail.md?ask=&goal=
```
`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.