Turbot DocsGetting StartedConceptsGuidesIntegrationsAWSImporting AccountsImporting GovCloudEvent HandlersServicesPermissionsSecurity HubDecommission TurbotAzureGCPBest PracticesMods7-minute LabsFAQsReferenceRelease NotesTurbot.comEnterprise

Importing an AWS account into Turbot

This section details the steps required to import an AWS Account into a Turbot Folder. Alternatively, you can use the aws_account_import baseline which automates this process.

Overview

AWS accounts can be imported to Turbot by one of the following ways:

  • IAM Role
  • IAM Role and User Access Key Pair

Supported AWS Partitions

There are three account partitions that AWS offers and Turbot supports. Valid partition names are:

  • aws - Public AWS partition (Commercial)
  • aws-cn - AWS China
  • aws-us-gov - AWS GovCloud

Consider Turbot is hosted in AWS commercial account:

  • We can import AWS commercial partition accounts directly by the IAM Role only.
  • To import AWS China or AWS GovCloud accounts we need User Access key Pair along with the IAM Role.

Prerequisites to import AWS Commercial Account

A few steps must be completed before an account can be imported into Turbot:

  • A cross-account IAM role in the managed account. Using AWS IAM Role Delegation allows you to grant access to Turbot without sharing security credentials like passwords or other secrets.
  • The aws mod installed. This mod holds the resource definition for an AWS Account. Additional mods may be desired. Remember that Mods enable Turbot to work in the cloud environment. Refer to the Recommended Starting Mods for more information.

What Permissions to Grant

What permissions you grant to the Turbot IAM role will depend on your use case(s). Turbot will use whichever role you specify and the permissions granted to it. If you instruct Turbot to perform some action but do not provide sufficient permissions to perform it, Turbot will get an "Access Denied" error. Identify then resolve these errors by either adjusting permissions on the Turbot IAM role, or by adjusting your policies. Below are some common permission sets that customers use. Choose a common permission set or construct one that conforms to your requirements.

  • Full Remediation

    • If you wish to take advantage of every AWS integration offered by Turbot, attach the Amazon Managed AdministratorAccess Policy:
    • arn:aws:iam::aws:policy/AdministratorAccess

  • Mixed Remediation

    • You may choose to remediate on a select set of services

    • Start with permissions required to manage event handling. Attach the AmazonSNSFullAccess, CloudWatchFullAccess, CloudWatchEventsFullAccess, and ReadOnlyAccess Amazon Managed Policies:

      • arn:aws:iam::aws:policy/ReadOnlyAccess
      • arn:aws:iam::aws:policy/AmazonSNSFullAccess
      • arn:aws:iam::aws:policy/CloudWatchEventsFullAccess

    • Add additional IAM policies as desired for the target AWS service. For example, one could add:

      • arn:aws:iam::aws:policy/AmazonEC2FullAccess
      • arn:aws:iam::aws:policy/AmazonRDSFullAccess
      • Or any other custom policy that meets your requirements.
    • When crafting custom policies, be aware of the AWS IAM service quotas on policy length

  • Read Only + Event Handlers

    • To get ReadOnly Access + Event Handlers, attach the AmazonSNSFullAccess, CloudWatchEventsFullAccess, and ReadOnlyAccess Amazon Managed Policies:

      • arn:aws:iam::aws:policy/ReadOnlyAccess
      • arn:aws:iam::aws:policy/AmazonSNSFullAccess
      • arn:aws:iam::aws:policy/CloudWatchEventsFullAccess

    • Or, to strictly limit Turbot's write access in the account to only event handling resources, build a role with the following permissions. A convenient CloudFormation template can be found below.

      • Attach the ReadOnlyAccess Amazon Managed Policies:

        • arn:aws:iam::aws:policy/ReadOnlyAccess

      • Create a custom policy that allows write-access to only Turbot event handling infrastructure.

        • CloudWatch Events matching:
        • arn:aws:events:*:${AccountId}:rule/turbot_aws_api_events*
        • SNS topics and subscriptions matching:
        • arn:aws:sns:*:${AccountId}:turbot_aws_api_handler
        • arn:aws:sns:*:${AccountId}:turbot_aws_api_handler:*

        • Note that the default resource prefix is turbot_. If changes are made to the "Event Rule Name Prefix" or "SNS Topic Name Prefix" policies, then the IAM policy must be updated to match. This is an uncommon requirement. See policy details below.

        • Adjust the partition from aws to aws-us-gov and aws-cn as required.

  • Budget Permissions

    • Grant permissions to allow the Budget control to get the cost usage and forecast data:
    • ce:getCostForecast
    • ce:GetCostAndUsage

Cross Account Trust

The role must grant cross-account access for the Turbot master AWS account to assume into your AWS account.

  • Turbot Cloud customers, you must allow the Turbot SaaS US AWS Account ID: 287590803701
  • Turbot Cloud EU customers, you must allow the Turbot SaaS EU AWS Account ID: 255798382450
  • Turbot Enterprise customers, enter the AWS Account ID of the Turbot Account where you have installed the Turbot Enterprise stacks.

External IDs

It is required that you set an External ID. There are two sources for the External ID:

  1. Turbot will suggest an auto-generated External ID that is unique to your Turbot Workspace (e.g. turbot:123456789012345:foo). This autogenerated external ID must be used when "External ID Protection" is enabled. You can use the generated ID for your IAM role to prevent the confused deputy problem. For more information, check out our FAQ titled What is Turbot AWS IAM External ID protection?
  2. You can set the external ID to any valid external ID you prefer.

Additional External ID Considerations

  • When you have External ID Protection enabled, (e.g. set to Protected), it will be required to use the protected format for the Workspace.
  • Make sure you leave Require MFA disabled on the role.
  • If you are setting your own external ID, be sure it follows AWS character limits.

Role Name

Give the role a meaningful name such as turbot-service-readonly (read only) or turbot-service-superuser (for full access), as well as an apt description.

Creating the Role

Using CloudFormation

To simplify setup, you can use the Turbot-provided CloudFormation template. For EU customers, use 255798382450.

Full AdministratorAccess

---
AWSTemplateFormatVersion: "2010-09-09"
Parameters:
  RoleName:
    Type: String
    Default: turbot-service-superuser
    Description: The role that Turbot uses to connect to this account

  TurbotAccountId:
    Type: String
    Default: 287590803701 
    Description: |
      The AWS Account ID where Turbot is installed.
      This will be added to the trust policy of the role to allow access for Turbot

  TurbotExternalId:
    Type: String
    NoEcho: True
    MinLength: 1
    Description: |
      The AWS External ID to add to the trust policy of the Turbot role

Resources:

  TurbotSuperuserRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          -
            Effect: Allow
            Principal:
              AWS: !Sub arn:aws:iam::${TurbotAccountId}:root
            Action:
              - sts:AssumeRole
            Condition:
              StringEquals:
                sts:ExternalId: !Ref TurbotExternalId
      Path: /turbot/core/
      ManagedPolicyArns:
        - "arn:aws:iam::aws:policy/AdministratorAccess"
      RoleName: !Ref RoleName

ReadOnly + Event Handlers

This represents the minimum privileges required for Turbot read all AWS resources and configure event handlers

AWSTemplateFormatVersion: 2010-09-09
Parameters:
  RoleName:
    Type: String
    Default: turbot-service-readonly
    Description: The role that Turbot uses to connect to this account
  PolicyName:
    Type: String
    Default: turbot-readonly-events-sns
    Description: The name for the policy for SNS and Events write access.
  TurbotAccountId:
    Type: String
    Default: 287590803701
    Description: >
      The AWS Account ID where Turbot is installed.
      This will be added to the trust policy of the role to allow access for Turbot
      Defaults to the Turbot US SaaS account
  TurbotExternalId:
    Type: String
    NoEcho: true
    MinLength: 1
    Description: |
      The AWS External ID to add to the trust policy of the Turbot role
Resources:
  TurbotReadOnlyRole:
    Type: 'AWS::IAM::Role'
    Properties:
      AssumeRolePolicyDocument:
        Version: 2012-10-17
        Statement:
          - Effect: Allow
            Principal:
              AWS: !Sub 'arn:aws:iam::${TurbotAccountId}:root'
            Action:
              - 'sts:AssumeRole'
            Condition:
              StringEquals:
                'sts:ExternalId': !Ref TurbotExternalId
      Path: /turbot/core/
      ManagedPolicyArns:
        - 'arn:aws:iam::aws:policy/ReadOnlyAccess'
      RoleName: !Ref RoleName
    Metadata:
      'AWS::CloudFormation::Designer':
        id: e66f3008-2c13-4544-bf72-2a69e5e5a4a9
  TurbotSNSEventsPolicy:
    Type: 'AWS::IAM::Policy'
    Properties:
      PolicyName: !Ref PolicyName
      Roles:
        - !Ref RoleName
      PolicyDocument:
        Version: 2012-10-17
        Statement:
          - Sid: TurbotEvents
            Effect: Allow
            Action:
              - 'events:PutEvents'
              - 'events:EnableRule'
              - 'events:DisableRule'
              - 'events:PutRule'
              - 'events:DeleteRule'
              - 'events:PutTargets'
              - 'events:RemoveTargets'
              - 'events:TagResource'
              - 'events:UntagResource'
            Resource:
              - !Sub 'arn:aws:events:*:${AWS::AccountId}:rule/turbot_aws_api_events*'
          - Sid: TurbotSNS
            Effect: Allow
            Action:
              - 'sns:TagResource'
              - 'sns:UntagResource'
              - 'sns:CreateTopic'
              - 'sns:DeleteTopic'
              - 'sns:SetTopicAttributes'
              - 'sns:Publish'
              - 'sns:Subscribe'
              - 'sns:ConfirmSubscription'
              - 'sns:AddPermission'
              - 'sns:RemovePermission'
              - 'sns:Unsubscribe'
            Resource:
              - !Sub 'arn:aws:sns:*:${AWS::AccountId}:turbot_aws_api_handler'
              - !Sub 'arn:aws:sns:*:${AWS::AccountId}:turbot_aws_api_handler:*'
    DependsOn:
      - TurbotReadOnlyRole

Using the AWS console

If you do not want to create the role with Cloudformation, you can create it manually:

  1. Login to AWS with a privileged account and navigate to IAM > Roles in the AWS IAM Console.

  2. Click the Create Role button.

    a. Select Another AWS account for the type of trusted entity.

    b. For Account ID, enter 287590803701 (Turbot's SaaS AWS account ID) if you are a SaaS customer. This means that you are granting Turbot access to your AWS account. If you are a Turbot Enterprise customer, enter the AWS Account ID of the Turbot Account where you have installed the Turbot Enterprise stacks.

    c. Check Require External ID and enter an External ID. You can choose any valid external ID. You will need this ID later, when you import the account into Turbot. Make sure you leave Require MFA disabled. Click Next: Permissions.

  3. Select the policies to be attached to the role:

    • To take advantage of every AWS integration offered by Turbot (recommended), attach the Amazon Managed AdministratorAccess Policy:

      • arn:aws:iam::aws:policy/AdministratorAccess

    • To enable readonly access for Turbot with event handler support:

      • Attach the AmazonSNSFullAccess, CloudWatchFullAccess, CloudWatchEventsFullAccess, and ReadOnlyAccess Amazon Managed Policies:

        • arn:aws:iam::aws:policy/ReadOnlyAccess
        • arn:aws:iam::aws:policy/AmazonSNSFullAccess
        • arn:aws:iam::aws:policy/CloudWatchEventsFullAccess

      • Create a policy to grant permissions to get the cost usage and forecast data, and attach it to the role:

        • ce:getCostForecast
        • ce:GetCostAndUsage
  4. Click Next: Tags.
  5. If desired, add tags, then click Next: Review.
  6. Give the role a meaningful name such as turbot-readonly (read only) or turbot-superuser (for full access), as well as an apt description. Click Create Role.

Install desired mods

The aws mod is required to import AWS accounts into Turbot. It must be installed before account imports can start. Ensure it is installed and the Mod installed control is in the green ok state. The aws-iam mod is highly recommended.

Installation of additional mods will depend on the organization's control objectives. If the organization doesn't have any control objectives on a given service, don't install that service's mod. Check out our Mods recommendation page for more info on suggested mods to install.

Recommended Mods (in order of installation):

  1. aws
  2. aws-iam
  3. aws-kms
  4. aws-ec2

  5. aws-vpc-*

  6. aws-sns
  7. aws-events
  8. aws-s3
  9. aws-cloudtrail
  10. aws-events

Importing an AWS Commercial account into a Turbot folder

Importing accounts into Folders offers increased flexibility and easier management over importing directly under the Turbot level. Define a Folder hierarchy prior to import.

Importing the account via the Turbot Console (UI)

  1. At the main Turbot screen after logging in with Turbot/Admin permissions, click the IMPORT card in the top right.
  2. Select AWS Account on the left.
  3. Use the Parent Resource dropdown menu to select where the AWS account will be imported to.
  4. Enter the Account ID in the field.
  5. Copy the IAM Role ARN that was created earlier and paste into the field. Do the same with the IAM Role External ID.
  6. Click import!
  7. CMDB and Discovery controls are enabled by default and Turbot will begin discovering the resources in your AWS account. Resources will start appearing right away, and resource discovery will continue to run in the background.

Importing the account via Terraform

#### Create the AWS > Account resource in Turbot
resource "turbot_resource" "account_resource" {
  parent = id-of-parent-folder
  type   = "tmod:@turbot/aws#/resource/types/account"
  metadata = jsonencode({
    "aws" : {
      "accountId" : "your aws account id",      "partition" : "aws"
    }
  })
  data = jsonencode({
    "Id" : "your aws account id"  })
}

#### Set the credentials (Role, external id) for the account via Turbot policies
# AWS > Account > Turbot IAM Role > External ID
resource "turbot_policy_setting" "turbotIamRoleExternalId" {
  resource   = turbot_resource.account_resource.id
  type       = "tmod:@turbot/aws#/policy/types/turbotIamRoleExternalId"
  value      = "external id for your turbot role"}

# AWS > Account > Turbot IAM Role
resource "turbot_policy_setting" "turbotIamRole" {
  resource   = turbot_resource.account_resource.id
  type       = "tmod:@turbot/aws#/policy/types/turbotIamRole"
  value      = "arn of your turbot role"}

Post Import Validation

There are a few things to check after importing an account.

  1. Check that the AWS > Account > CMDB policy has run
  2. Ensure that there are no policy values and controls in a tbd state. It's common to see thousands of controls in tbd shortly after account import. Commonly, all tbd controls will clear in less than 20 minutes. Exact times will depend on overall Turbot load and account size. The account should not be considered fully imported until the tbd control count goes to zero.
  3. If Event Handling has been enabled, ensure that the AWS > Turbot > Event Handler controls are in an ok state. If not using Event Handlers, ensure that the AWS > Turbot > Event Poller controls are in ok and have run in the lsat minute or two.
  4. If there are any controls or policy values in error, resolve them as quickly as possible.