Investigate Amazon Connect API activity across your organization using AWS CloudTrail and Amazon Athena

Following AWS’s best practices on multi-account strategy, customers launch and maintain their Amazon Connect instances across multiple accounts and Regions depending upon their products, groups, departments, etc. This allows individual business owners, developers, engineers etc. to make changes to their own independent Amazon Connect environments. In such a scenario, customers need a central mechanism to simplify and manage investigations on user and resource activity across Amazon Connects environments.

To help customers track, record and analyze Amazon Connect public APIs in a multi account environment, Amazon Connect integrates with AWS CloudTrail, a service that records all public Amazon Connect API calls. AWS CloudTrail allows customers to collect logs across an AWS Organization and send them to a centralized Amazon Simple Storage Service (S3) bucket. Amazon Athena, a serverless interactive analytics service, provides functionality to query and analyze these centralized Amazon Connect logs.

In this blog post, we cover the steps necessary for you to record, view, query and analyze activities from your Amazon Connect instances across multiple AWS accounts and Regions. With this information, you will be able to understand your Amazon connect security posture and investigate any activities that deviate from the expected behavior.

Prerequisites

For this walk-through, you should have the following prerequisites:

Basic understanding of Amazon Connect public APIs
Access to management account
Ability to create an organizational Trail

Walkthrough

In this walk-through, we investigate Amazon Connect instances deleted across accounts and Regions. We start with checking how many Amazon Connect instances were deleted across an organization. We then identify users responsible for the deletion and examine their other activities.

To do this, we create an organization trail which upon creation starts logging Amazon Connect public API activities across organization and sending the CloudTrail logs to a centralized S3 bucket. We then query this centralized S3 bucket using Amazon Athena to analyze Connect activities across accounts and Regions. Figure 1 provides the graphical representation of this workflow.

Figure 1: Querying centralized CloudTrail logs

Step 1: Configure organizational Trail

For this exercise, you can use an existing organizational trail. If you do not have access to an existing organizational trail, please follow steps below. The first delivery of each management event for an account your Amazon Simple Storage Service (S3) bucket is free.

Navigate to CloudTrail console. From left hand pane, choose Trails and then from right hand pane select Create Trail.
On Choose Trail attribute page, provide a trail name such as cloudtrail-connect-example. Check the box for Enable for all accounts in my organization.
For simplicity, we have not enabled Log file SSE-KMS encryption. Keep the other options as default. Select Next.
On Choose log events page, keep everything as default, select Next. On Review and Create page, select Create Trail.
You should now see your trail created. Note the name of centralized S3 bucket under S3 bucket column.

Step 2: Configure an Athena table

Navigate to Athena Console, choose Explore the query editor. If this is your first-time logging using Athena you will see the below message:
Select Edit settings. Provide a S3 bucket for query results location.
To find your Organization ID, navigate to AWS Organization console. From left hand panel, copy the Organization ID.
Navigate back to Athena Console choose Explore the query editor. On right hand pane, you can use Query editor to enter and run queries.

Using the below query, create a table for querying your results. Please replace the S3 bucket name (noted earlier) and Organization ID (o-xxxxxxxxxx).

CREATE EXTERNAL TABLE cloudtrail_logs (
eventversion STRING,
useridentity STRUCT<
               type:STRING,
               principalid:STRING,
               arn:STRING,
               accountid:STRING,
               invokedby:STRING,
               accesskeyid:STRING,
               userName:STRING,
  sessioncontext:STRUCT<
    attributes:STRUCT<
               mfaauthenticated:STRING,
               creationdate:STRING>,
    sessionissuer:STRUCT<  
               type:STRING,
               principalId:STRING,
               arn:STRING, 
               accountId:STRING,
               userName:STRING>,
    ec2RoleDelivery:string,
    webIdFederationData:map<string,string>
  >
>,
eventtime STRING,
eventsource STRING,
eventname STRING,
awsregion STRING,
sourceipaddress STRING,
useragent STRING,
errorcode STRING,
errormessage STRING,
requestparameters STRING,
responseelements STRING,
additionaleventdata STRING,
requestid STRING,
eventid STRING,
resources ARRAY<STRUCT<
               arn:STRING,
               accountid:STRING,
               type:STRING>>,
eventtype STRING,
apiversion STRING,
readonly STRING,
recipientaccountid STRING,
serviceeventdetails STRING,
sharedeventid STRING,
vpcendpointid STRING,
tlsDetails struct<
  tlsVersion:string,
  cipherSuite:string,
  clientProvidedHostHeader:string>
)
ROW FORMAT SERDE 'org.apache.hive.hcatalog.data.JsonSerDe'
STORED AS INPUTFORMAT 'com.amazon.emr.cloudtrail.CloudTrailInputFormat'
OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat'
LOCATION 's3://ENTERNAMEOFS3BUCKET/AWSLogs/ENTERORGID/';

Note the table cloudtrail_logs created on the left panel Tables and views:
Now you need to add to your table. To do so, choose the plus (+) sign in Query editor to create a new tab for the new query:
```
ALTER TABLE cloudtrail_logs SET
LOCATION 's3://ENTERNAMEOFS3BUCKET/AWSLogs/ENTERORGID/'
```

Step 3: Investigate Amazon Connect activities across accounts and Regions

We simulate Amazon Connect activity by creating Amazon Connect instances in multiple accounts and Regions, and later deleting these instances. Please wait a few minutes for CloudTrail records to show up and enter these queries in new tab.

To check how many instances were deleted across accounts & Regions, navigate to Athena Console and run the below query:

SELECT eventName, count(eventName) AS NumberOfDeletedInstances, recipientaccountid, awsRegion
FROM cloudtrail_logs
Where eventname = 'DeleteInstance' AND eventsource = 'connect.amazonaws.com'
GROUP BY eventName, recipientaccountid, awsRegion

To identify users that deleted these instances, run the below query and copy useridentity.arn

SELECT
useridentity.arn,
recipientaccountid,
sourceipaddress,
eventtime,
awsRegion,
eventName,
requestParameters
FROM cloudtrail_logs
Where eventname = 'DeleteInstance' AND eventsource = 'connect.amazonaws.com'

To check the activity of the user who performed these deletions, run the below query:

SELECT
eventName,
recipientaccountid,
sourceipaddress,
eventtime,
awsRegion
FROM cloudtrail_logs
Where useridentity.arn = 'ENTERTHEUSERARN' AND eventsource = 'connect.amazonaws.com'

Following the above examples, you can now query your Amazon Connect CloudTrail logs across accounts/Regions. More information on the Amazon Connect log file entries is available in Amazon Connect API calls with AWS CloudTrail documentation.

Clean Up

If you were following the blog only to test the solution, please clean up your account to avoid recurring charges. If not, please do not proceed with cleanup. To clean up, please follow the steps below:

If you created CloudTrail Organization trail, as a part of this exercise, navigate to CloudTrail console, select the trail your created and choose Delete.
Navigate to S3 console. Delete the S3 bucket you created to store CloudTrail logs from all accounts.

Conclusion

In this blog post, we showed you how you can use an organizational trail to query Amazon Connect activities across multiple accounts & Regions. For more information on Amazon Connect, check out the Amazon Connect documentation.

AWS Contact Center