Integrate Amazon Web Services (AWS) with Red Canary

As an AWS user you can select an organization or account when integrating with Red Canary. If your AWS accounts are organized under an AWS organization, it is easier to add a single Red Canary integration for the organization than a separate integration for each AWS account.

1. From your Red Canary homepage, click Integrations.

   

2. From the Integrations section, locate and then click Amazon Web Services.

   

3. Enter a name for your new AWS integration. 

4. Choose the scope of your integration by selecting either Organization or Account.
   Organization - Configure the integration to scan your AWS organization and its member accounts.
   Account - Configure the integration to scan a single AWS account.

Note: If you select Account, click here to continue the Account integration process.

Organization (Red Canary/AWS)

1. If you select Organization, enter your Organization ID. 

   1. To locate your Organization ID, navigate to AWS and then search for Organizations.

   2. Click Organizations.

      

2. Copy, and then paste the organization ID into Red Canary.

3. Enter any Excluded Accounts; this step is optional.

   1. Note: Excluded Accounts is a comma separated list of account ID(s) that will be excluded from the Red Canary scan. Additionally, Red Canary will not process excluded account data for CloudTrail, GuardDuty, and billable resources. 

4. From Red Canary, click Next.

Account (Red Canary/AWS)

1. If you selected Account, enter your Account ID. For more information, see Finding your AWS account ID.

   

2. From Red Canary, click Next.

Red Canary will read CloudTrail logs from an S3 bucket. If CloudTrail already logs to an S3 bucket, Red Canary can utilize an existing S3 bucket.

Once the SNS topic and SQS queues are functional, Red Canary needs to be able to copy the data from your S3 bucket into our ingestion bucket.

Note: Creating a new CloudTrail for RedCanary could increase your AWS bill. To avoid increased costs, we recommend using your pre-existing CloudTrail. For new CloudTrail users, your first CloudTrail is free. For more information, see Managing CloudTrail trail costs.

Locate the ARN of the S3 Bucket

1. To locate your S3 Bucket ARN, navigate to AWS and then search for CloudTrail.

2. Click CloudTrail.

3. Click on the active Trail name.

   

4. Click the Trail log location.

5. From the breadcrumbs section, click the CloudTrail location.

   

6. Click the Properties tab.

7. Copy and then paste the ARN of the S3 bucket containing the CloudTrail logs into Red Canary.

   

   

Locate/Create an SNS Topic for CloudTrail Logging bucket notifications 

1. To create your S3 Bucket ARN, navigate to AWS and then search for Simple Notification Service.

2. Click Simple Notification Service.

   

3. Enter a name for your new SNS topic.

   

4. Click Create Topic.

   

5. Copy and save the SNS Topic ARN. You’ll use this in a later step.

   

6. Click Edit.

7. From the Access Policy section, copy and then enter the code below:

   To get the Red Canary ARN from the Red Canary Integration Setup page:

   1. Click on Sample SNS access policy statement under Step 3b.

   2. Copy the ARN provided next to “AWS”:

{
  "Version": "2008-10-17",
  "Id": "__default_policy_ID",
  "Statement": [
    {
      "Sid": "RCPartnerAccessControl",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<INSERT RED CANARY ARN>"
      },
      "Action": "SNS:Subscribe",
      "Resource": "<INSERT SNS TOPIC ARN HERE>"
    },
    {
      "Sid": "__default_statement_ID",
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      },
      "Action": [
        "SNS:Publish",
        "SNS:RemovePermission",
        "SNS:SetTopicAttributes",
        "SNS:DeleteTopic",
        "SNS:ListSubscriptionsByTopic",
        "SNS:GetTopicAttributes",
        "SNS:AddPermission",
        "SNS:Subscribe"
      ],
      "Resource": "INSERT SNS TOPIC ARN HERE",
      "Condition": {
        "StringEquals": {
          "AWS:SourceArn": "<INSERT BUCKET ARN>"
        }
      }
    }
  ]
}

Note: If you have an existing SNS Topic in AWS, ensure that your Access Policy update for the integration contains the code below.

8. Within the Access Policy section, ensure that the Resource line contains the SNS Topic ARN. Additionally, change AWS:SourceOwner to AWS:SourceArn and then paste your S3 bucket ARN.

   

   Your access policy should look like the image below.

   

9. From Red Canary, enter the SNS topic ARN from Step 2.5.

   

10. Click Next.

Push notifications to your SNS topic from an S3 bucket

When data is put into an S3 bucket, messages can be pushed onto your SNS topic. SNS can then push notifications to any subscriber including the Red Canary SQS queue.

AWS

1. From the AWS homepage, type and select S3 in the search bar.

   

2. Click the AWS bucket you want to use to send data to Red Canary.

   

3. Click the Properties tab.

4. Scroll down to the Event notifications section, and then click Create event notification.

   

5. Enter an Event name for your event notification.

6. From the Event types section, select All object create events.

   

7. From the Destination section, select SNS topic.

8. From the SNS topic dropdown, select the SNS topic you updated in the previous section.

   

9. Click Save Changes.

   Note: Upon successful setup of the SNS topic, the topic should populate with two subscriptions (generally within 15 minutes).

   

Enable Red Canary to decrypt your AWS CloudTrail data in order to start sending alerts to Red Canary.

S3 bucket

1. To grant the required S3 bucket access, navigate to AWS. Type and then select CloudTrail in the search bar.

2. Click the Trail that you want Red Canary to have access to.

   

3. Click the Trail log location.

4. From the breadcrumbs section, click the CloudTrail location.

   

5. Click the Permissions tab.

6. From the Bucket Policy section, click Edit.

   Red Canary

7. On Step 3a of the integration setup in Red Canary, click and open the Sample S3 bucket policy statement dropdown. Copy and then paste the following code into your existing Policy:

   Note: You must replace the sample Resource ARN in the Red Canary provided code with your own personal Resource ARN.

   

8. From the Resource line (highlighted above), enter the ARN of the S3 Bucket from Step 2.5.

   S3 Bucket

9. Click Save Changes.

KMS

1. To grant the required KMS access, navigate to AWS. Type and then select CloudTrail in the search bar.

2. Click the Trail that you want Red Canary to have access to.

   

3. Click the AWS KMS key.

   

4. Copy and save the AWS KMS ARN address. You will use this in a later step.

   

5. Scroll down to the Key Policy section.

   Red Canary

6. Click and open the Sample KMS key policy statement dropdown. Copy the code shown:

   AWS

7. Paste the code into the Key Policy editor:

   

   Note: “Resource”: “*” refers to this KMS key only. Refer to Key Policy Elements for more information.

8. Click Save Changes.

Red Canary

1. Select and grant Red Canary access to the following by selecting the checkboxes next to each:

   • S3 Bucket

   • SNS topic

   • KMS
     

2. From Red Canary, click Next.

Use a Red Canary provided template to provision an IAM role in your environment for Red Canary access.

1. To use one of the provided templates to provision an IAM role in your environment for Red Canary access, click CloudFormation or Terraform to access the appropriate template.

2. Copy and paste your required template into a new file/document. Save this new file with your template. You’ll upload this file to AWS in a later step.

   

3. To provision an IAM role, navigate to AWS.

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

   Note: Using Terraform is dependent on your environment and we are not able to replicate the necessary steps at this time.

   For CloudFormation Stack (Account)

   a. Type and then select CloudFormation in the search bar.

   b. Click the Create stack dropdown, and then click With new resources (standard).

   

   c. From the Prerequisite section, select Choose an existing template.

   d. From the Specify template section, select Upload template file. 

   e. Click Choose file, and then select the file created in Step 4.2.

   

   f. Click Next.

   g. Enter a name for your new Stack.From AWS, type and then select CloudFormation in the search bar.

   

   h. Click Next.

   i. Click Next.

   

   j. From the Capabilities section, select the acknowledgment message.

   k. Click Submit.

   l. From the Search bar, type and then select IAM in the search bar.

   m. Click Roles.

   n. Select the stack you created in this step, and then copy the ARN for this role.

   

   o. Paste the ARN of the IAM Role into Red Canary.

   

5. From the Advanced Configuration section, Ingest GuardDuty Finding is selected by default. If you do not want Red Canary to ingest this type of data, deselect Ingest GuardDuty Finding.

   

Note: In order for Red Canary to have access to context, analysis, and improved insight into potential risks in your security environment, we recommend that you leave Ingest GuardDuty Finding enabled.

6. Click Save.

   StackSet (Organization)

   a. From AWS, type and then select CloudFormation in the search bar.
   b. Click StackSets in the navigation pane.

   

   c. Click Create StackSet.

   

   d. Enter a name for your IAM role.
      Note: We suggest using the name rc-partner-access-control.

   e. From the Prerequisite section, select Template is ready.
   f. From the Specify template section, select Upload template file.

   

   g. Click Choose file, and then select the file created in Step 4.2.

   

   h. Click Next.
   i. Enter a name for your new Stack.

   

   j. Click Next.

   k. Click Next.

   

   l. From the Specify regions section, select the region you want to deploy stacks to.

     Note: The Failure Tolerance section may need to be adjusted to address any potential failures.

   

   m. Click Next.

   n. From the Capabilities section, select the acknowledgment message.

   o. Click Submit.

   p. From the Search bar, type and then select IAM in the search bar.

   q. Click Roles.

   r. Select the stackset you created in this step, and then copy the ARN for this role.

   

   s. Paste the ARN of the IAM Role into Red Canary.

   

7. From the Advanced Configuration section, Ingest GuardDuty Finding is selected by default. If you do not want Red Canary to ingest this type of data, deselect Ingest GuardDuty Finding.

   Note: In order for Red Canary to have access to context, analysis, and improved insight into potential risks in your security environment, we recommend that you leave Ingest GuardDuty Finding enabled.

8. Click Save.

Red Canary ingests CloudTrail logs and GuardDuty findings from AWS environments. Red Canary also integrates with AWS to regularly scan the environment to discover new accounts and resources.

CloudTrail

AWS CloudTrail monitors and records account activity across your AWS infrastructure and generates CloudTrail logs. Red Canary monitors these logs for signs of suspicious activity or otherwise risky behavior. To ingest the data, Red Canary requires the CloudTrail logs to be stored in an S3 bucket. This makes the integration very flexible and can accommodate multiple AWS Accounts sending CloudTrail telemetry to a single S3 bucket. 

Permissions summary: The target AWS account must grant a external role within Red Canary permission to read data from the S3 bucket which stores the CloudTrail telemetry. The S3 bucket must publish S3 object write events to a SNS topic, and Red Canary must have permission to subscribe to that topic.

GuardDuty

Amazon GuardDuty is a threat detection service that continuously monitors AWS accounts, workloads, and data for malicious activity and delivers detailed security findings for visibility and remediation. Red Canary monitors these findings for signs of suspicious activity or otherwise risky behavior, and correlates them with CloudTrail telemetry. Red Canary will attempt to collect findings from every global AWS region for each account which is in scope for the integration. 

Permissions Summary: Red Canary infrastructure assumes a role within the target AWS environment, and uses available APIs to collect GuardDuty findings on a regular basis. The role must be created and granted the appropriate permissions for Red Canary to ingest GuardDuty findings successfully. If the role does not exist in all enabled AWS regions, we will flag it as an integration error failure.

To investigate GuardDuty alerts, Red Canary requires a successfully configured CloudTrail integration. If a CloudTrail integration isn’t active, GuardDuty alerts will be assigned back to your team for investigation.

Environment Scanning

Red Canary regularly scans the target AWS environment for newly created accounts and resources, ensuring that data is properly attributed and monitored as the environment grows and evolves. Red Canary makes read-only API calls to gather this scan data. 

Permissions Summary: Red Canary infrastructure assumes a role within the target AWS environment, and uses available APIs to collect scan data on a regular basis. If the role does not exist in all enabled AWS regions, we will flag it as an integration error failure.