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:

{
  "Version": "2008-10-17",
  "Id": "__default_policy_ID",
  "Statement": [
    {
      "Sid": "RCPartnerAccessControl",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::1234567891011:root"
      },
      "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.

1. Select and grant Red Canary access to the following:
   - S3 Bucket
   - SNS topic
   - KMS

   

2. Click and open the Sample S3 bucket policy statement dropdown. Copy and then save the code. You’ll use this code in another step.

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

   

3. Click and open the Sample SNS access policy statement dropdown. Copy and then save the code. You’ll use this code in another step.

   

4. Click and open the Sample KMS key policy statement dropdown. Copy and then save the code. You’ll use this code in another step.

   

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.

7. Copy and then paste the following code into your existing Policy:

   {
     "Sid": "RCPartnerAccessControl",
     "Principal": {
       "AWS": "arn:aws:iam::1234567891011:role/rc-partner-access-control"
     },
     "Effect": "Allow",
     "Action": [
       "s3:ListBucket",
       "s3:GetObject",
       "s3:GetObjectAttributes",
       "s3:GetObjectVersion"
     ],
     "Resource": [
       "arn:aws:s3:::example-cloudtrail-logs-123456",
       "arn:aws:s3:::example-cloudtrail-logs-123456/*"
     ]
   }

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

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.

6. From the editor section, under the Statement line, enter the following lines of code:

   {
       "Sid": "LetRedCanaryDecryptLogs",
       "Effect": "Allow",
       "Principal": {
           "AWS": ["arn:aws:iam::1234567891011:role/rc-partner-access-control"]
       },
       "Action": [
                   "kms:Decrypt",
                   "kms:DescribeKey"
                 ],
       "Resource": "*"
   },

   

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

7. Click Save Changes.

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

Why does Red Canary need access for each action permission in our CloudFormation and Terraform templates?

The permissions are what we need from GuardDuty’s perspective for discovery inside your environment. NONE of these permissions edit, add, or delete your resources in any way. Below is a list of permissions we need for licensure. 

• For more information, see How Cloud Control Plane Licensing and Usage are Determined and Amazon Web Services ingest details. 

The permissions below are all used for License calculation purposes:

The permissions below are needed for the Cloudtrail integration:

We also ask for the following roles for the Red Canary Partner Access Role:

Do I need to have GuardDuty enabled?

Important Cost Notification

Before enabling GuardDuty, it’s essential to understand that it is a paid service that monitors for malicious activity and unauthorized behavior to protect your AWS resources. The service charges are based on the volume of AWS data it analyzes, such as logs and events. Ensure you review the pricing details on the GuardDuty page to understand the cost implications and budget accordingly before activation.

Red Canary strongly recommends turning on AWS GuardDuty. GuardDuty is a powerful ally that bolsters your security posture. It helps correlate and enrich the telemetry data we’re already analyzing with CloudTrail. By enabling GuardDuty, you're not just collecting data but empowering our systems to deliver deeper insights and more comprehensive security analysis.

GuardDuty and CloudTrail create a dynamic duo for Red Canary, enhancing our ability to detect and respond to potential threats more swiftly and effectively.

Finally, GuardDuty acts as an extra layer of intelligence, providing context to the footage by correlating different data points and highlighting activities that require closer inspection. Red Canary will be able to review what has been recorded while also understanding the bigger picture and respond more effectively to security incidents.

Is the 'rc-partner-access-control' role required for the CloudTrail integration, and what is its purpose?

The 'rc-partner-access-control' role is not required for the CloudTrail integration, but it is critical to scan the environment to obtain resource counts for the license usage page. 

Does the 'rc-partner-access-control' role need to be deployed to all AWS accounts, and how should it be configured in the system?

Yes. You must deploy the 'rc-partner-access-control' role to all AWS accounts for full coverage. This action enables Red Canary to fetch GuardDuty alerts from each account. This role is deployed to all accounts you want Red Canary to monitor. We suggest using CloudFormation to automate this deployment. Enter any IAM role ARN from one of the accounts in the configuration box. However, the account number may vary, and the role name remains consistent across all AWS accounts in your organization.

Can I use my current setup that stores GuardDuty logs in an S3 bucket for the GuardDuty integration?

Red Canary’s integration does not support fetching GuardDuty alerts from S3 buckets. We use polling via Security Token Service (STS), assuming the API role from the account was deployed using a CloudFormation StackSet or Terraform template. This method necessitates deploying the role in each account, as we use the same pattern to access accounts for Resource Scanning and GuardDuty.

If I already have access control lists (ACL) enabled, what must I do and how?

You’ll need to access the ACL and turn off everything other than the Bucket Owner Checks. Otherwise the following error may be thrown when turning off the bucket ownership:

As demonstrated in the image below, this is what the ACL should look like before we go back to Object Ownership and try to disable the object ACL:

What are some common issues with the AWS Cloudformation stack set and deploying the CloudFormation template?

By default, the management account will not have the stack set applied. For more information, see Working with AWS CloudFormation StackSets.

Note: The rc-partner-access-role won’t appear on this account. However, you can force it by including the account name during the stack set account creation, which shows up only if you select the self-service permissions.

Instead of creating individual Amazon GuardDuty integrations, can I make a unified AWS CloudTrail and GuardDuty integration?

Yes! You can integrate AWS CloudTrail and GuardDuty at the same time. If you previously integrated Guard Duty with Red Canary, you can decommission this and use the new unified integration.

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.

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.