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

AWS CloudTrail: New CloudTrail setup for Workbench

  • Updated

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

If you're...

use this...

Notes

setting up new AWS CloudTrails

this article

To set up your device, 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.

connecting an existing CloudTrail

the existing installation steps

connecting an existing CloudTrail that includes Control Tower

the Control Tower connection steps

In this article

About connecting your device

Connecting your device to Workbench allows Workbench to ingest the logs. AWS logs include a great deal of information that can take hours to manually review. And not all AWS alerts need attention.

Expel collects data through direct API integrations with the AWS platform. Expel supports authentication with an IAM Role (recommended) or IAM User with a set of read-only permissions. To collect data, Expel communicates directly with AWS APIs (like AWS GuardDuty and Inspector) and pulls in CloudTrail data from S3.

Expel processes all product alerts with a library of Expel created rules focused on the MITRE attack framework. This makes it possible for a product alert that wouldn't be reviewed to be elevated to an Expel alert.

Before you start

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.

About console permissions in your devices

As you connect your devices to Workbench, you provide Workbench access to those devices through permissions in the devices. These permissions vary from 1 device technology to another, but we typically need at least Read access to your devices to pull in any logs from those devices into Workbench.

Without minimum permissions to your devices, the SOC analysts are limited in their insight into your technology. This can mean they surface more benign alerts to your team for further investigation, resulting in increasing the workload for your team, and resulting in alert fatigue.

If you grant Read access to your devices, we can investigate the device and the logs more deeply and surface relevant alerts to you in Workbench. Allowing Expel visibility into the console of your security devices helps our SOC analysts make better decisions on whether an alert is benign or malicious. It also allows our SOC analysts to perform health checks to make sure Workbench is not missing alerts from your security devices. Depending on what your organization purchased from Expel, the SOC analysts may even be able to contain and/or remediate the issues on your behalf.

Ultimately, the more permissions you can grant Workbench, the better and faster the SOC analysts can find and investigate alerts in your environment.

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.

  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.

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

  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.

  7. Verify Trail attributes and click Create Trail.

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.

  2. Edit the Default Encryption as follows:

    • 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. If this is the first SQS queue you created, click Get Started Now. If you already defined other SQS queues, click Create New Queue.

  2. Create queue.

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

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

  5. Click Create Queue.

Step 4: Add key policies

Note

You must add this key policy 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.

Step 5: Configure S3 notifications

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

  2. Navigate to Properties.

  3. Select Create event notifications.

  4. General configuration:

    • Event name: ExpelNotifyQueue.

    • Select All object create events under Event Types.

  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.

Step 6: Create AWSIAM 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 AWSIAM Policy.

    • Navigate to the IAM service.

    • Go to Policies and click Create Policy.

    • Select the JSON tab and add the following permissions on 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",
"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_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 description and explanation

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

This permission...

does this...

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

iam:List*

iam:Get*

lambda:GetFunction

rds:DescribeDBInstances

rds:ListTagsForResource

eks:DescribeCluster

eks:ListClusters

ecs:ListContainerInstances

ecs:DescribeContainerInstances

ecs:DescribeClusters

ecs:ListClusters

s3:GetBucketNotification

s3:GetEncryptionConfiguration

cloudtrail:GetTrail

cloudtrail:DescribeTrails

cloudtrail:GetTrailStatus

cloudtrail:ListTrails

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

config:ListDiscoveredResources

config:GetDiscoveredResourceCounts

lambda:ListFunctions

Cloud investigative actions and inventory

Allows SOC analysts to triage issues and get additional content for the environment.

lightsail:GetInstances

lightsail:GetRegions

s3:ListAllMyBuckets

kms:Decrypt

Decrypt S3 buckets

organizations:DescribeOrganization

Organization information

Retrieves information about the organization the user's account belongs to.

  • Review and name the policy ExpelAPIPolicy.

Step 7: Create role

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

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

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

      AWSNEWCloudtrailURL.png

  3. Attach the IAM policy from Step 1: Configure a global CloudTrail to the Role.

  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.

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

    • Role ARN.

    • External ID Value on 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.

Note

Expel secures all login information our SOC analysts need about your devices in a MFA password product. Access to this login information is protected using our internal MFA processes. To learn more about the IP addresses all Expel traffic comes from, go here.

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

  2. Answer the questions, being sure to answer No 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.

      Note

      External ID is automatically populated.

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

    • SQS URL: Queue URL.

  4. Click Save.

You can see if the device is healthy on the Security Devices page. It may take a few minutes to see the device listed as healthy.

To check if alerts are coming through, navigate to the Alerts Analysis page. Scroll to the device you want to check and click View alerts. Switch to grid view, then check the list for device alerts. It can take 36 to 72 hours for alerts to appear after setup, as we tune your device.

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!

  • Was this article helpful?

  • 1 out of 3 found this helpful

Related articles