This article describes how to connect your existing AWS CloudTrail with AWS Control Tower to the Expel Workbench.

If you're...

use...

Notes

connecting an existing CloudTrail that includes Control Tower

this article

You need the following to integrate a Control Tower environment with Workbench.

  • An AWS Control Tower with Landing Zone.

  • Administrator privileges in the AWS Control Tower management and Log Archive accounts.

setting up new AWS CloudTrails

the onboarding wizard

You can also use the manual connection procedure.

connecting an existing CloudTrail

the existing installation 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 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.

This process requires you to download the attachment, found at the end of this article. The attachment includes the code blocks you need to complete this process.

Note

This article assumes the default service control policies are in play. If you run into any issues during setup, contact your engagement manager for help.

Step 1: Setup ExpelIAM role and policy

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

Important

For AWS Control Tower the primary Expel role is created within the organization’s Log Archive account where the CloudTrail S3 Log Bucket exists.

The role and policy must be replicated across all the other accounts in the organization to allow Expel to perform investigative actions within your AWS environment. The policy replicated to the other non-Log Archive sub-accounts can be modified to exclude the policy elements providing access permissions to the S3 resources if necessary.

  1. Create IAM Role and Policy in management account.

    • Navigate to the CloudFormation > Stacks service portal.

    • Click Create Stack (with new resources) and select Upload a template file as the source.

    • Upload a JSON file containing the stack template. You can find that code in the attachment for this article in the Step 1 area.

    • Provide a relevant name to the stack, such as ExpelIAMStack.

    • In the WorkbenchExternalID parameter field, type in your Workbench GUID, then click Next.

      Note

      You can find this GUID by logging into Workbench and then navigating to https://workbench.expel.io/settings/organizations. The redirected URL contains the value to be used for this parameter.

      image4.jpg
    • You can leave all defaults for configuring the stack options and click Next.

    • Verify the stack details, then check the acknowledgement and click Submit.

    • The new IAM role and attached policy should exist for Expel within the management account on completion of the stack.

  2. Create IAM Role and Policy in all sub accounts.

    • Navigate to the CloudFormation > Stacksets service portal.

    • Click Create StackSet and select Upload a template file as the source.

    • Follow the same process to fill out the stackset details as was done in deploying the stack above (Step 1.1).

Step 2: Update CloudTrail CMK policy if applicable

Note

You can skip this step if your CloudTrail is not configured to encrypt the S3 logs using CMK. Otherwise, we need to update the key policy to provide Workbench with the kms:Decrypt permission so that we can properly get objects from the S3 bucket containing the CloudTrail logs.

You can determine if this step applies to you by navigating to Services > CloudTrail > Trails and then selecting the trail created by Control Tower in your management account. In the General details section you see a value under Log file SSE-KMS encryption and an associated AWS KMS key populated as well.

  1. Navigate to the CMK key used to encrypt the CloudTrail logs.

    • You can find the specific key arn by looking for AWS KMS Key in the General details section of the CloudTrail.

  2. Select the Key policy tab and then click Edit to change it.

  3. Add the decrypt permission to the existing list of policy statements. You can find that code in the attachment for this article in the Step 2 area.

    Note

    Make sure to update the principal value with the correct arn path to the Expel Role created in the Log Archive account as a result of Step 1.2 via the StackSet.

Important

The following steps (Steps 3 - 8) must be performed from within your AWS Control Tower Log Archive account. See the AWS documentation for any clarification on what that is.

Step 3: Confirm S3 log bucket ACL settings

Note

Amazon S3 access control lists allow you to manage access to buckets and any objects contained within. We want to confirm that the S3 bucket created in your log archive account allows the bucket owner (Log Archive) and Expel by extension through the deployed role read permissions for the objects within.

  1. Navigate to Services > S3 > Buckets > [Your S3 Log Bucket] (usually follows the naming scheme “aws-controltower-logs-”.

  2. Select the Permissions tab, then look at the Object Ownership section to confirm the current ACL setting.

  3. If you keep ACLs enabled on the bucket then confirm the current Object Ownership is set to Bucket owner preferred.

Important

AWS recommends that you disable ACLs on S3 for a majority of modern use-cases which then delegate ownership to the bucket owner account (source).

Step 4: Setup SNS topic for S3 notifications

Option 1: Using CloudFormation (recommended)

Important

If you choose this option, then you can skip to Step 8 when you’re done.

  1. Navigate to Services > CloudFormation > Stacks and click Create stack (with new resources).

  2. In the Specify template section select Upload a template file. Then upload a JSON file containing the stack template. Then click Next. You can find that code in the attachment for this article in the Step 4, Option 1 area.

  3. Fill in a name for the stack.

  4. Fill in the following required parameters.

    • S3LogBucketARN: the ARN associated with the S3 Bucket in your Log Archive account that retains the CloudTrail logs.

    • CloudTrailKeyARN: the ARN for the customer-managed kms key configured on your CloudTrail (in your management account).

  5. Proceed through the rest of the wizard keeping the defaults, then click Submit to initiate the stack.

  6. After the stack creation completes, make note of all values returned in the Outputs tab of the stack console. You need these returned values to complete setup in Workbench.

    • RoleARN: the IAM Role created in the log archive account needed to complete setup in Workbench.

    • SqsURL: the SQS url path needed to complete setup of in Workbench.

Important

You can now skip directly to Step 8.

Option 2: Manual setup

Caution

Make sure to create the SNS topic in the same region as the S3 bucket CloudTrail events are being sent to!

  1. Navigate to Services > Simple Notification Service > Topics and click Create Topic.

  2. On the next screen, select Standard as the Type and create a Topic Name.

  3. Under Access Policy, select Advanced.

    In the JSON editor, paste the below policy substituting the YOUR_TOPIC_ARN and YOUR_S3_ARN fields with your values. This policy allows S3 to publish notifications to the topic for your CloudTrail bucket. You can find that code in the attachment for this article in the Step 4, Option 2 area.

  4. Click Create Topic.

Step 5: Setup SQS queue for SNS notification

In this step, we create a new SQS queue for S3 notifications. Workbench polls notifications from this queue to know when new CloudTrail data is added.

Caution

Make sure you create the SQS queue in the same region as the SNS topic and S3 bucket!

  1. Navigate to Services > Simple Queue Service > Queues and click Create queue.

  2. On the next screen, select Standard Queue and name the new queue.

    • 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. Under Access Policy, select Advanced.

  4. In the JSON editor, paste the policy substituting the YOUR_SQS_QUEUE_ARN and YOUR_SNS_TOPIC_ARN fields with your values. You can find that code in the attachment for this article in the Step 5 area.

Step 6: Subscribe SQS to SNS topic

Now that we created an SNS topic and SQS queue, we need to configure SNS to send events to the SQS queue.

  1. Navigate to Services > Simple Notification Service > Subscriptions and click Create subscription.

  2. On the next screen, configure the required fields to complete the subscription.

    Field

    Value

    Topic ARN

    Your SNS Topic ARN

    Protocol

    Select Amazon SQS

    Endpoint

    Your SNS Queue ARN

    Enable raw message delivery

    Important

    Selecting enable raw message delivery makes sure SNS doesn’t add extra metadata headers to the message when it sends to SQS. Make sure you select this!

  3. Click Create subscription to finish this step.

Step 7: Setup KMS encryption for SNS and SQS

  1. Navigate to Services > Key Management Service (KMS) > Customer managed keys and click Create Key.

  2. Retain the default configuration values as shown below, then click Next.

  3. Fill in values for the alias and description for the key, then click Next.

  4. Select any additional key administrators for the new key, then click Next until you get to the Review page.

  5. Look for the Key policy generated for this key in the Review page and add the policies to the statement list to give S3 & SNS the right permissions they need to decrypt with this key. You can find that code in the attachment for this article in the Step 7 area.

  6. Click Finish to complete the creation of the new key.

  7. Enable Encryption on the SNS topic you created in Step 3 using the new key.

    • Navigate to Services > Simple Notification Service > Topics > YourTopic.

    • Click Edit, then click Encryption on.

    • In the Customer master key (CMK) selection, click the KMS key you created above.

  8. Enable Encryption on the SQS topic you created in Step 4 using the new key.

    • Navigate to Services > Simple Queue Service > Queues > YourQueue.

    • Click Edit, then toggle the Encryption option on.

    • Set the Server-side encryption option to Enabled.

    • Set the Encryption key type to SSE-KMS.

    • In the Customer master key selection, click the KMS key you created above.

Step 8: Enable S3 event notifications to SNS topic

In this step, we configure the CloudTrail S3 bucket to send SNS notifications when CloudTrail adds logs to the bucket.

  1. Navigate to Services > S3 > Your S3 CloudTrail Bucket.

  2. Open Properties for your S3 bucket and navigate to Event notifications. Click Create event notification.

  3. On the next screen:

    • Create a name for your notification rule.

    • Select All object create events from the Event types section.

    • Select SNS topic from the Destination section.

    • Select your SNS topic created in Step 3.

Step 9: Grant ExpelIAM Role necessary access

Tip

Skip this step if you onboarded the Expel resources with CloudFormation using Step 4, Option 1. You can go to Step 10.

At this point we configured S3 notifications → SNS topic → SQS queue. The final step involves granting the existing ExpelIAM Role the necessary access to poll events from the SQS queue and the S3 bucket.

  1. Navigate to Services > IAM > Roles.

  2. Create and add a new inline policy to the Expel Role that was propagated to the Log Archive account as part of Step 1.

    Tip

    Name it ExpelAssumeRole if you used the provided StackSet template. The policy grants the permissions. You can find that code in the attachment for this article in the Step 9 area.

Step 10: Complete Workbench setup

Congratulations! You configured S3 notifications to an SQS queue through SNS. Go to Step 10 of the AWS CloudTrail Manual Setup - New Trail page to add the integration as a security device in Workbench. Make sure to select Manual Connection for the connection type.

You require the following details to complete this step:

  • Role ARN: Expel Role ARN created in Step 1 specific to the Log Archive account.

  • SQS URL: the full URL path of the SQS created in Step 4.

  • Organization Management Account: the account ID of your AWS organization’s management account.

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!