1. Expel Support Center
  2. Connect your technology
  3. Cloud integrations

AWS CloudTrail — New CloudTrail setup for Workbench

Sharon Burton
  • Updated

This article describes how to connect your new AWS CloudTrail to the Expel Workbench.

If you are connecting an existing CloudTrail, use the existing installation procedure instead.

If you are connecting an existing CloudTrail that includes Control Tower, use the Control Tower connection procedure instead.

Tip

This article was accurate at the time of writing, but changes happen. If you find the instructions are outdated, leave a description in the comment field below and let us know!

Before you start

You need:

  • Permissions to create and modify IAM policies and roles in each AWS account you want Expel to monitor.

  • An AWS Management Account ID or individual AWS Account ID(s) for each account you're going to onboard.

  • The AWS region in which you want to create an SQS queue to notify Expel of available CloudTrail data.

Server Side Encryption with AWS-KMS

AWS KMS (key management services) allows you to manage cryptographic keys to encrypt/decrypt data at-rest. Many AWS services offer server side encryption (SSE) where the service is responsible for encrypting/decrypting the data on a principal’s (user/service) behalf.

We are encrypting all the data at rest (CloudTrail logs, CloudTrail log bucket and SQS queue messages) using a custom managed AWS key. All the required permissions for the AWS services to encrypt/decrypt data are specified in the key policies. Additionally, the custom role that this integration assumes to monitor your AWS account is attached with a policy to decrypt the CloudTrail log S3 bucket using this key.

Manual onboarding for new AWS CloudTrails

Step 1: Configure a global CloudTrail

  1. Log in to the AWS console. If you have multiple AWS accounts and use AWS Organizations, log into your primary account.

  2. Ensure you are in the region you want to be the Home region for the new CloudTrail. The CloudTrail collects data from all regions, but it is stored in S3 in a specific region. You need to supply this region to Expel Workbench later in this process.

  3. Navigate to the CloudTrail service and create a new trail.

    image-0

  4. Select trail attributes.

    Important

    If you select an existing S3 bucket or KMS key, the integration doesn't work. Contact your engagement manager for help.

    • Name Trail: we recommend GlobalCloudTrail.

    • Select Create new S3 bucket and name bucket.

    • When creating a new trail, make sure that Enable for all accounts in my organization is selected if you are using AWS Organizations.

    • Enable Log file SSE-KMS encryption. Select New and type a KMS alias.

    • Enable Log file validation.

    • (Optional) If you are using SNS, select SNS Topic.

      mceclip0.png

  5. Leave the CloudWatch Logs and Tags sections blank and click Next.

    Screen_Shot_2021-03-04_at_9.27.40_AM.png

  6. Select log events.

    • Events: only select Management events. Leave the rest cleared.

    • Management events: select Read and Write. Leave Exclude AWS KMS events clear.

    • Click Next.

      Screen_Shot_2021-03-04_at_9.28.21_AM.png

  7. Verify Trail attributes and click Create Trail.

    mceclip1.png

Step 2: Enable SSE-KMS encryption in the log S3 bucket

To enable Server Side Encryption (SSE) in the Trail log bucket, you must edit the configuration of the trail log bucket.

  1. Navigate to S3 and select the S3 trail log bucket created in Step 1. Select the Properties tab and Edit the Default Encryption section.

    mceclip2.png

  2. Edit the Default Encryption as follows:

    mceclip3.png

    • Enable Server Side Encryption.

    • For Key Type, select AWS Key Management Service key (SSE-KMS).

    • For AWS KMS key, select Choose from your AWS KMS keys.

    • Type the key alias given in Step 1 and select it.

    • (Optional) Enable Bucket Key.

    • Note the Bucket ARN.

  3. Click Save changes.

Step 3: Create an SQS queue to receive S3 notifications

To consume CloudTrail events from the trail’s S3 bucket, Workbench must be notified when new event files are added to the S3 bucket. In this step, we create an SQS queue for these notifications.

Note

The SQS queue must be in the same account and region as the S3 bucket created in Step 1.

  1. Navigate to Simple Queue Service and click Get Started Now if this is the first SQS queue you created, or click Create New Queue if you already have other SQS Queues defined.

    Screen_Shot_2021-03-04_at_9.30.08_AM.png

  2. Create queue.

    • Details: Queue Name is filled in as ExpelMasterCloudTrailNotify. Select Standard Queue.

      Screen_Shot_2021-03-04_at_9.30.47_AM.png

    • Configuration:

      • Visibility timeout: 30 Seconds.

      • Message retention period: 7 days.

      • Delivery delay: 0 Seconds.

      • Maximum message size: 256 KB.

      • Receive message wait time: 0 Seconds.

  3. Access policy:

    • Select Advanced, change the Resource and aws:SourceArn sections of the following JSON then copy and paste to the text box.

      Note: Your SQS ARN is populated after you switch to the Advanced tab.

      {
 "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>"  
 }
 }
 }
 ]
}

  4. Enable Server Side Encryption and select AWS Key Management Service key (SSE-KMS) for Encryption key type. Type the key alias created in Step 1 and select the key.

    mceclip4.png

  5. Click Create Queue.

Step 4: Add key policies

Note

Adding this key policy is necessary to configure the S3 event notifications in the following step.

To enable trail log bucket to encrypt messages that are being sent to the SQS queue, you need to add key policies.

Navigate to the KMS key created in Step 1.

  1. Click Edit on the Key policy tab.

  2. Copy the following JSON key policy snippet and append it to the end of the existing key policies.

    ,
{ 
 "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>"
                }
            }
        }

  3. Save the key policy and note the KMS ARN.

    mceclip6.png

Step 5: Configure S3 notifications

  1. Navigate to the S3 bucket containing your CloudTrail logs created in Step 1.

  2. Navigate to Properties.

    Screen_Shot_2021-03-04_at_9.32.03_AM.png

  3. Select Create event notifications.

    Screen_Shot_2021-03-04_at_9.32.34_AM.png

  4. General configuration:

    • Event name: ExpelNotifyQueue.

    • Select All object create events under Event Types.

      Screen_Shot_2021-03-04_at_9.33.22_AM.png

  5. Destination:

    • Select SQS Queue under Destination.

    • Select Choose from your SQS queues and select the queue you created from the list. If you don't see your queue, you can select Enter SQS queue ARN and type the queue ARN in the field.

  6. Save your changes.

    Screen_Shot_2021-03-04_at_9.34.34_AM.png

Step 6: Create AWS IAM policy

In this step we create a permissions policy to assign to the IAM Role.

Important

If you use AWS organizations, the primary Expel role resides in the organization’s primary account where the CloudTrail, S3, and SQS queue were created for the integration.

The role and policy must be replicated across all the other accounts in the organization to perform AWS investigative actions. The policy in the sub-accounts can be changed to exclude the SQS and S3 resources.

  • Create AWS IAM Policy.

    • Navigate to the IAM service.

    • Go to Policies and click Create Policy.

      Screen_Shot_2021-03-04_at_9.35.20_AM.png

    • Select the JSON tab and add the following permissions using the JSON tab:

      {
"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:DescribeVolumes",
"ecs:DescribeTaskDefinition",
"ecs:ListTaskDefinitions",
"lambda:GetFunction",
"lambda:ListFunctions",
"lightsail:GetInstances",
"lightsail:GetRegions",
"s3:ListAllMyBuckets",
"cloudtrail:GetTrailStatus",
"cloudtrail:DescribeTrails",
"config:ListDiscoveredResources",
"config:GetDiscoveredResourceCounts",
"eks:DescribeCluster",
"eks:ListClusters",
"ecs:ListContainerInstances",
"ecs:DescribeContainerInstances",
"ecs:DescribeClusters",
"ecs:ListClusters"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"sqs:DeleteMessage",
"sqs:ReceiveMessage"
],
"Resource": "<YOUR_SQS_ARN>"
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": "<YOUR_S3_ARN>/*"
},
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": "<YOUR_KMS_KEY_ARN>"
}
]  
}

Tip

There should be “/*” at the end of your S3 ARN in the Resource section. This allows the role to access all of the sub-folders in your bucket.

Permissions List

Permission

Usage

ec2:DescribeRegions

Dynamically list all enabled regions for a customer account

ec2:DescribeInstances

Cloud investigative actions and inventory

ec2:DescribeSecurityGroups

iam:List*

iam:Get*

lambda:GetFunction

rds:DescribeDBInstances

rds:ListTagsForResource

eks:DescribeCluster

eks:ListClusters

ecs:ListContainerInstances

ecs:DescribeContainerInstances

ecs:DescribeClusters

ecs:ListClusters

organizations:ListAccounts

Enumerate accounts in an org

sqs:DeleteMessage

Remove Processed messages from the queue

sqs:ReceiveMessage

Read messages

s3:GetObject

Download cloudtrail log files

ec2:DescribeVolumes

Cloud investigative actions and inventory

ecs:DescribeTaskDefinition

Inventory

ecs:ListTaskDefinitions

config:ListDiscoveredResources

config:GetDiscoveredResourceCounts

lambda:ListFunctions

Cloud investigative actions and inventory

lightsail:GetInstances

lightsail:GetRegions

s3:ListAllMyBuckets

kms: Decrypt

Decrypt S3 buckets

  • Review and name the policy ExpelAPIPolicy.

Screen_Shot_2021-03-04_at_9.36.17_AM.png

Step 7: Create IAM Role

  1. From within the IAM service, navigate to Roles and click Create Role.

    Screen_Shot_2021-02-25_at_9.28.29_AM.png

  2. Select Another AWS account and fill out the required fields.

    Screen_Shot_2021-02-25_at_9.26.25_AM.png

    • Account ID: 012205512454 (the Expel AWS account ID).

    • External ID: this unique identifier is assigned to you by Expel. You can find it in your browser URL after navigating to Settings > My Organization in Workbench (see sample screenshot below). You can also find it while completing Step 5: Register AWS in Workbench. Reach out to your engagement manager if you are unable to locate this ID.

      mceclip5.png

  3. Attach the IAM policy from Step 1 to the Role.

    Screen_Shot_2021-02-25_at_9.30.25_AM.png

  4. Skip Add Tags.

  5. Review: Name the role ExpelServiceRole and create the Role. Important: all accounts roles must have the same name for the integration to work.

    Screen_Shot_2021-02-25_at_9.31.33_AM.png

  6. Navigate to the role you just created and copy the following information:

    • Role ARN.

    • External ID Value under the Trust relationships tab.

Step 8: Register AWS in Workbench

Now that we have the correct access configured and noted the credentials, we can integrate your tech with Workbench.

  1. Login to https://workbench.expel.io/settings/security-devices?setupIntegration=aws.

  2. Answer the questions, being sure to answer Yes to the second question, and then click Start.

    mceclip0.png

  3. Fill out the following fields:

    mceclip4.png

    • Role ARN: the Role ARN.

    • Role session name: use a unique name to identify the use of the role.

    • Region: the AWS region containing the trail S3 and SQS.

    • SQS URL: Queue URL.

  4. Click Save.

Note

External ID is automatically populated.

To check if alerts are coming through, navigate to Alerts on the console page. Click the icon in the upper right to switch to grid view, then check the list for device alerts.

  • Was this article helpful?

  • 0 out of 2 found this helpful

Related articles