1. Expel Help Center
  2. Connect Your Technology
  3. A-C Integrations
  4. Amazon/AWS
  5. AWS CloudTrail

AWS GovCloud CloudTrail Manual Setup - New Trail

This setup guide is for those who wish to use the GovCloud CloudTrail service for their CloudTrail integration. The AWS setup described here is Expel’s recommended best practice.

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. Verify you have the necessary permissions to create and modify IAM policies and roles for your AWS account.
  2. Make sure you are in the proper AWS account if you manage more than one account.
  3. 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.
  4. Make sure you can log into Workbench successfully, and are able to see your organization settings.
    • Note: 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 this Reference topic for detailed instructions.
  5. 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 available in the Quick Links, and additional help is available in the Reference).
  6. Using a GovCloud environment requires completing a legal addendum before Expel can enable event ingestion for this integration. Please contact your Customer Success Manager (CSM) or Expel Support to assist you in completing the addendum.

Quick Links

Setup includes the following steps (select any step for detailed instructions):

  1. Create a new trail with a new S3 bucket and new AWS KMS key.
  2. Edit the S3 bucket’s default encryption settings to use your AWS KMS key.
  3. Create the SQS queue to receive messages from the S3 bucket.
  4. Edit the AWS KMS key’s encryption policy to enable communication.
  5. Enable S3 bucket event notifications to send certain events to the SQS queue.
  6. Create the IAM policy.
  7. Create the IAM role.
  8. Add AWS CloudTrail as a security device in Workbench.
  9. Troubleshooting
  10. Reference

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). These include, in the order they are created or generated:

  • Workbench GUID (to save time, get it now)
  • 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

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. 

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

Step 1: Create a New Trail

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.

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. 
    • Suggestion: 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 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 the next section.
    • 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). You will configure the key’s policy in a later section.

  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 the next section). The format should look something like this: arn:aws-us-gov:s3:::YourS3BucketName
  5. Next, scroll to Default encryption and select Edit.
    • Select Server-side encryption with AWS Key Management Service keys (SSE-KMS).
    • Under AWS KMS key, select Choose from your AWS KMS keys.
    • Select the AWS KMS key you created in Step 1 (the alias will display in small print below the key).
    • Leave the Bucket Key as Enable.
    • 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. Make sure to use your SQS Queue ARN as the Resource value and your S3 Bucket ARN as the aws:SourceARN value. 
{
  "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"
        }
      }
    }
  ]
}
  1. Important: Did you use your SQS Queue ARN and S3 Bucket ARN in the new code? Check to be sure before continuing.
  2. Leave the remaining sections as is and select Create queue.
  3. 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 section).

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 these JSON objects to the code. Make sure to use your S3 Bucket ARN as the aws:SourceArn value. 
,
{
  "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"
    }
  }
}

If you need help appending your policy, go to the Troubleshooting section. 

  1. Important: Did you use your S3 bucket ARN and SNS Topic ARN in the appended code? Check to be sure before continuing.
  2. 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. Make sure to replace the SQS Queue ARN, S3 Bucket ARN, and KMS Key ARN with your own. 
{
  "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"
    }
  ]
}
  1. 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.
  2. Select Next.
  3. Enter "ExpelAccessPolicy" as the policy name.
  4. 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.

  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. Make sure to replace the Workbench GUID with your own. 
{
    "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"
                }
            }
        }
    ]
}
  1. Select Next.
  2. Locate your IAM policy (from Step 6; this should be the ExpelAccessPolicy) in the Permissions Policies section, and select the checkbox next to it.
  3. Select Next.
  4. Enter "ExpelAssumeRole" as the role name.
  5. Select Create Role.
  6. Before you leave the page, copy and save your IAM Role ARN, as you will need it in the next section.

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

Now, we can add a security device in Workbench to complete the integration. 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 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. Select AWS CloudTrail (or search for it if you do not see it listed). Then 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.
    • Select Save.
  5. In 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.
    • Select Save.
  6. Select Done to close the window.
  7. You must now notify your CSM to let them know you have completed these steps. If you haven't already, please work with them to complete the required legal addendum so that Expel can enable GovCloud ingestion of events for this integration. If you are not sure who your CSM is, contact Support.

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.

Troubleshooting

S3 Event Notification Errors (Step 5)

This error is encountered when selecting Save changes. It generally displays for one of the following reasons:

  • 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.
  • The JSON objects were copied, appended, or formatted incorrectly in a prior step.
  • 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).
  • You have forgotten to enable something, or have configured something incorrectly, in one of the prior steps.
    • Examples: Not choosing your AWS KMS key from the dropdown menu when setting up default encryption in step 2, 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 in orange):

  {
	"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.
  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.

Note

If you have multiple organizations, you must first select the organization name that will be associated with your CloudTrail 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.

Related articles