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

If you're...

use this...

Notes

setting up new AWS CloudTrail

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

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

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.

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.

  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.

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.

  • 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

Note

Expel secures all login information our SOC analysts need about your devices in an 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.

Tip

This page was accurate at the time of writing, but changes happen. If you find the instructions are outdated, let us know via your engagement manager or account representative.