Integrate Amazon Web Services (AWS) with Red Canary

The first step is to add the new integration in Red Canary.

1. From your Red Canary homepage, go to the Integrations page then click Add Integration.
   

2. On the Add integration dialog, search for the Amazon Web Services integration then click Configure.
   

3. On the Add Integration page, enter a name for the integration.
   

Autodetect

For the AWS integration, you can optionally run Autodetect to scan your AWS environment and automatically fill out many of the integration parameters required in the steps below. Follow the instructions on the Autodetect your AWS configuration dialog to retrieve the values then click Use autodetected values to populate the fields on the configuration page.

If any of the values can’t be autodetected, or if you need to override any of the suggestions, you can still complete all the steps manually as described below.

You can choose to integrate a single account, or you can integrate multiple accounts simultaneously if they’re grouped under an AWS organization.

1. In the Choose the scope of integration section, select the scope:
   Organization - Scan your AWS organization and all its member accounts
   Account - Scan a single AWS account
   

Organization Scope

If you chose Organization scope:

1. If you don’t already know your AWS Organization ID and AWS Management Account ID, copy them from the AWS Organizations dashboard in your AWS Console.
   

2. Enter the AWS Organization ID and AWS Management Account ID into the Red Canary configuration page.
   

3. Select the accounts you want to include:

   All accounts in this organization - Scan every account. You can optionally enter a comma-separated list of account IDs that will be excluded from the scan.
   Only specific accounts - Enter a comma-separated list of the accounts you want to scan.

4. Click Next.

Account Scope

If you chose Account scope:

1. If you don’t already know your AWS Account ID, copy it from the Billing and Cost Management > Account page in your AWS Console.
   
   For additional help, see Finding your AWS account ID.

2. Enter the AWS Account ID into the Red Canary configuration page.
   

3. Click Next.

Red Canary reads your CloudTrail logs from an S3 bucket. In order to configure the integration, you’ll need to provide the ARN of the S3 bucket and (optionally) the KMS key used to encrypt the bucket.

Red Canary also needs to subscribe to an SNS topic in order to receive messages as data is added to the S3 bucket.

Note

Creating a new CloudTrail for Red Canary could increase your AWS bill. To avoid additional costs, we recommend using a pre-existing CloudTrail. For more information, see Managing CloudTrail trail costs.

Get the ARN of the CloudTrail Logs S3 Bucket

1. Navigate to the CloudTrail Dashboard in your AWS Console.

2. In the Trails panel, click on the active Trail name.
   

3. Click the Trail log location.
   

4. Click the CloudTrail location in the breadcrumbs section.
   

5. Go to the Properties tab and copy the Bucket ARN.
   

Get the ARN of the CloudTrail S3 Bucket KMS Encryption Key

Note

AWS doesn’t require encryption for the CloudTrail S3 bucket. If you’re not using encryption, you can skip this step.

1. Navigate to the Amazon S3 > General purpose buckets page in your AWS Console.

2. In the General purpose buckets panel, click on the bucket you’re using to send data to Red Canary.
   

3. Go to the Properties tab and copy the Encryption key ARN from the Default encryption panel.
   

Note

The Encryption key ARN won’t be displayed if KMS encryption isn’t enabled. To change the default encryption:

1. Click Edit.

2. Change Encryption type to “Server-side encryption with AWS Key Management Service keys (SSE-KMS)”

3. Choose an existing KMS key, or create a new one. The Key usage must be “Encrypt and decrypt.”

4. Save the changes then copy the resulting Encryption key ARN.

Enter the CloudTrail ARNs into Red Canary

1. In the Identify S3 bucket containing CloudTrail logs and SNS Topic section on the Red Canary configuration page, enter the Bucket ARN and Encryption key ARN.
   

Create an SNS Topic for CloudTrail Logging Bucket Notifications

You need to set up an SNS topic in AWS to receive event notifications when data is added to the CloudTrail logs S3 bucket.

1. Navigate to the Simple Notification Service page in your AWS Console.

2. Click Create topic.
   

3. Choose Standard as the topic type and enter a topic name.
   

4. Click Create topic.

5. Copy the SNS topic ARN.
   

6. Enter the SNS topic ARN on the Red Canary configuration page.

   Note

   If your SNS topic and KMS key belong to different AWS accounts, you’ll need to update the key policy in AWS to enable cross-account KMS access. The configuration page will auto-generate the JSON statement you can use to update the policy.

7. Click Next.

Send CloudTrail S3 Bucket Event Notifications to the SNS Topic

You need to configure the S3 bucket to send notifications to the SNS topic whenever a data event occurs.

1. Navigate to the Amazon S3 > General purpose buckets page in your AWS Console.

2. In the General purpose buckets panel, click on the bucket you’re using to send data to Red Canary.
   

3. Go to the Properties tab.

4. In the Event notifications panel, click Create event notification.

   

5. Enter a name for your event notification.

6. In the Event types panel, select All object create events.

   

7. In the Destination panel, select SNS topic and choose the topic you created earlier.

   

8. Click Save changes.

   If the topic is correctly set up, you should see it populate with two subscriptions after you finish and activate the integration.

   

Get the ARNs of the GuardDuty Alerts S3 Bucket and KMS Encryption Key

1. Navigate to the GuardDuty > Settings page in your AWS Console.

2. In the Findings export options panel, click Edit for the S3 bucket.
   

3. Copy the S3 Bucket ARN and the KMS Key ARN.
   

4. Click Cancel.

Enter the GuardDuty ARNs into Red Canary

1. In the Identify S3 bucket containing GuardDuty alerts and SNS Topic section on the Red Canary configuration page, enter the two ARNs for GuardDuty.
   

Create an SNS Topic for GuardDuty Alerts Bucket Notifications

You need to set up an SNS topic in AWS to receive event notifications when data is added to the GuardDuty alerts S3 bucket. The steps for creating the SNS topic are the same as for CloudTrail (see Create an SNS Topic for CloudTrail Logging Bucket Notifications).

1. After you’ve created the SNS topic in AWS, enter the ARN on the Red Canary configuration page.

   

2. Click Next.

Send GuardDuty S3 Bucket Event Notifications to the SNS Topic

The steps for setting up an SNS topic to receive GuardDuty event notifications are the same as for CloudTrail (see Send CloudTrail S3 Bucket Event Notifications to the SNS Topic).

You’ll use a Red Canary-provided template to provision an IAM role in your environment for Red Canary access.

Generate the Template in Red Canary

1. In the Provision an IAM role in the Account(s) Being Configured section on the Red Canary configuration page, select CloudFormation or Terraform to generate the appropriate template.
   

2. Copy and paste your required template into a new file/document and save it. You’ll upload this file to AWS later.

Provision the IAM Role in AWS

Apply the CloudFormation or Terraform template to all accounts in the AWS organization.

For CloudFormation

1. Navigate to the CloudFormation > Stacks page in your AWS Console.

2. Click Create stack and select With new resources (standard).
   

3. In the Prerequisite - Prepare Template panel, select Choose an existing template.

4. In the Specify template panel, select Upload template file.

5. Click Choose file to upload the template file you created earlier.
   

6. Click Next.

7. Enter a name for your new stack.
   

8. Click Next

9. In the Capabilities panel, accept the acknowledgment message.
   

10. Click Next.

11. Click Submit.

For Terraform

Terraform usage is dependent on your environment. If you need assistance with the Terraform template, please contact Red Canary Support.

Confirm the IAM Role in Red Canary

When you’ve finished provisioning the IAM role in AWS, check the Access granted box on the Red Canary configuration page.

Red Canary will attempt to scan all your AWS regions when performing our usage calculations. To avoid seeing errors on the Status Check page for any regions we’re unable to access, use the Advanced Configuration section to exclude any regions that aren’t enabled or that you’ve restricted via service control policy.

After you’ve completed the configuration, click Save to activate the integration.

The AWS integration is now live!

You should see AWS alerts start appearing in Red Canary within one hour.

After the AWS integration is active, you can make the following modifications to the configuration:

• Change the S3, SNS, and KMS ARNs

• Edit the list of included/excluded AWS accounts

• Add or remove GuardDuty

• Decommission the integration

To modify the configuration:

1. From your Red Canary homepage, go to the Integrations page then click on the name of the integration you want to modify.
   

2. After you’ve finished the editing the configuration, click Save to apply your changes.

Decommissioning the Integration

To remove the integration from Red Canary, click the button then click OK to confirm.

Important

If you decommission the integration, no new alerts will be sent to Red Canary. Although threats will be retained, all processed alerts will be deleted. This action cannot be undone.