Onboard an AWS Account

After InsightCloudSec is successfully installed, you're ready to start harvesting data from your Accounts, which requires configuring Amazon Web Services (AWS) to "talk" with InsightCloudSec securely. As your inventory grows and your cloud accounts are fully visible, you can then begin to leverage the rest of InsightCloudSec, including Insights, Bots, Layered Context, and more.

This page and the functionality detailed here refer to the provider-specific Accounts capability available under Cloud > Cloud Accounts. If you are looking to onboard an AWS Organization instead, see Onboard an AWS Organization.

Opening the Cloud Account Onboarding Interface

Before you can begin the onboarding process, you'll need to navigate to the Cloud Account Onboarding interface, which provides a different experience depending on the type of user you are:

UserDescriptionExperience
First-time UserInsightCloudSec is freshly deployed and this will be the first time a Cloud Service Provider (CSP) has been onboarded.Platform Users:
Onboarding wizard launched from Platform Home by clicking the InsightCloudSec tile.

InsightCloudSec Only Users:
The onboarding wizard appears automatically after logging in using your unique InsightCloudSec URL.
Returning UserInsightCloudSec has one or more CSPs already onboarded and you would like to add a new account.Launched from within InsightCloudSec. Not a wizard.
Admin UserYou can login to the cloud provider and have the appropriate access to grant InsightCloudSec access to your account(s).As an admin, you will need to complete some specific tasks within your Cloud Service Provider's (CSP) console to generate details needed for onboarding that either you or a non-admin user can input to InsightCloudSec.
Non-Admin UserYou can interact with InsightCloudSec and would like to onboard an account(s) but do not have the appropriate CSP access to grant InsightCloudSec access to your account(s).You will need to copy and send a message to the admin asking them to complete specific tasks and provide you with the information you need to complete onboarding.

Onboarding an AWS Account

A couple methods for onboarding your AWS Accounts are available depending on whether you're a non-admin or admin user.

Resuming cloud onboarding to InsightCloudSec

If you close the interface before completing Account onboarding, you can resume onboarding from the page you were on last.

Non-Admin User Instructions

Ask an admin for required information

As a non-admin user, you need to copy and send a message to the admin asking them to complete specific tasks and provide you with the information needed to complete onboarding.

First-time Users
  1. Login to InsightCloudSec using one of the methods below:
    • In the Insight Platform, click InsightCloudSec to launch the onboarding wizard.
    • Open a browser window to your unique InsightCloudSec URL and login. The onboarding wizard will appear automatically.
  2. On the Welcome screen, review key features and capabilities, then click Onboard a Cloud Account.
  3. On the Cloud Service Providers screen, select Amazon Web Services.
  4. Select No - Help me identify the details needed, then click Next.
  5. Click the Copy button in the Amazon Web Services Admin Instructions text box and share them with the admin.
Returning Users
  1. Login to InsightCloudSec using one of the methods below:
    • In the Insight Platform, click the InsightCloudSec tile.
    • Open a browser window to your unique InsightCloudSec URL and login.
  2. Navigate to Cloud > Cloud Accounts in the left-hand navigation menu.
  3. Click the + Add Cloud button in the top right corner.
  4. Click the Amazon Web Services button.
  5. Click Don't have admin access? in the bottom right corner of the window.
  6. Click the Copy button in the Amazon Web Services Admin Instructions text box and share them with the admin.

Connect the Account

When your admin has completed their steps and provided the information to you, you can now connect the Account.

First-time Users
  1. Return to InsightCloudSec using one of the methods below:
    • In the Insight Platform, click InsightCloudSec to launch the onboarding wizard.
    • Open a browser window to your unique InsightCloudSec URL and login. The onboarding wizard will appear automatically.
  2. The wizard should automatically return you to the Amazon Web Services Admin Instructions page.
  3. Enter the following information (provided by your admin):
    1. Select the AWS partition (Commercial, Government, China) in which the Account is located.
    2. Copy/paste the Role ARN.
    3. Copy/paste the Nickname for the Account. This is a unique value that will be used to search Accounts across the system based on an identifiable label.
    4. Select the authentication type.
      • If you chose Instance Profile, proceed to the next step.
      • If you chose IAM User via API Keys, copy/paste the Access Key and Secret Key.
    5. Optionally, adjust the Advanced Options:
      1. If your admin chose not to use the default Session Name, copy/paste the new value.
      2. If your admin chose not to use the default Duration, copy/paste the new value.
  4. Click Connect Account.
Returning Users
  1. Login to InsightCloudSec using one of the methods below:
    • In the Insight Platform, click the InsightCloudSec tile.
    • Open a browser window to your unique InsightCloudSec URL and login.
  2. Navigate to Cloud > Cloud Accounts in the left-hand navigation menu.
  3. Click the + Add Cloud button in the top right-hand corner.
  4. Click the Amazon Web Services button.
  5. Click Don't have admin access? in the bottom right-hand corner of the window.
  6. Enter the following information (provided by your admin):
    1. Select the AWS partition (Commercial, Government, China) in which the Account is located.
    2. Copy/paste the Role ARN.
    3. Copy/paste the Nickname for the Account. This is a unique value that will be used to search Accounts across the system based on an identifiable label.
    4. Select the authentication type.
      • If you chose Instance Profile, proceed to the next step.
      • If you chose IAM User via API Keys, copy/paste the Access Key and Secret Key.
    5. Optionally, adjust the Advanced Options:
      1. If your admin chose not to use the default Session Name, copy/paste the new value.
      2. If your admin chose not to use the default Duration, copy/paste the new value.
  7. Click Connect Account.
Admin User Instructions

As an admin, you must prepare your Account(s) for the connection with InsightCloudSec by deploying a custom role within AWS using a CloudFormation Template (CFT). For more information on the custom roles that InsightCloudSec provides, review AWS Overview & Support.

Providing details to a non-admin user?

If you are providing details to a non-admin user to onboard the Account, ensure that the credentials you share with the non-admin user will include the appropriate access and enable them to connect your AWS Account with InsightCloudSec successfully. We recommend using a secure file sharing system to provide credentials to your non-admin user.

AWS Admin Onboarding Prerequisites

CloudFormation Templates

All InsightCloudSec configuration parameters, users, roles, and policies are managed using CloudFormation Templates (CFTs). We use up to two CFTs in the onboarding process (depending on your selected AWS partition):

  • Rapid7 AWS IAM Roles CFT (All Partitions) -- We provide a standard CFT that is hosted and maintained with the latest permissions necessary for a full-featured experience. The CFT can be deployed to an Account as a single Stack.
  • Rapid7 AWS Authenticating Principal CFT (GovCloud/China Partitions Only) -- Authenticating across AWS Partitions (i.e., your InsightCloudSec instance in AWS commercial and your account in GovCloud/China) require that you create an IAM User once for the entire Partition. For your convenience, we provide a standard CloudFormation Template to deploy the IAM User and optionally create an AccessKey stored in Secrets Manager.

All the latest CFTs can be downloaded from the onboarding wizard. Proceed with the instructions below to find out how.

InsightCloudSec offers some features that require additional permissions/roles within AWS. It is easiest to perform this configuration while onboarding an account/organization, so our provided CFT can automatically do so (optionally) during general account onboarding. Review the links below to determine which features you'd like to use and we'll provide a reminder to select the relevant options later.

Prepare AWS for Onboarding

To onboard a single Account for AWS you need to complete the following set of instructions:

Multiple Browser Tabs/Windows Recommended

InsightCloudSec onboarding can proceed much more quickly and easily if you have both your InsightCloudSec instance and the relevant AWS console (Commercial, Government, China) open side-by-side in your preferred browser's windows/tabs. At this point, we highly recommend ensuring you're logged into AWS.

Manual Onboarding using the AWS console
Step 1: Setup an Authenticating Principal

InsightCloudSec utilizes an authenticating principal to securely harvest information from an Account. Because InsightCloudSec is often deployed in AWS Commercial, AWS GovCloud/China users will need to create an IAM user using an auto-generated CFT to facilitate this harvesting across partitions. AWS Commercial users will only need to copy their InsightCloudSec account's existing authenticating principal ID for later use.

In the InsightCloudSec Cloud Onboarding interface:

  1. Login to your InsightCloudSec instance and open the Cloud Onboarding interface.
    • First-time Users:
      1. On the Welcome screen, review key features and capabilities, then click Onboard a Cloud Account.
      2. On the Cloud Service Providers screen, select Amazon Web Services.
      3. Select Yes - I have sufficient permissions, then click Next.
    • Returning Users:
      1. Navigate to Cloud > Cloud Accounts in the left navigation menu.
      2. Click the + Add Cloud button in the top right corner.
      3. Click the Amazon Web Services button.
  2. Select Manual Steps for the connection journey.
  3. For 1. Authentication:
    1. Select the AWS Partition the account(s) you are trying to onboard are in (Commercial, Government, China).
    2. Select if your InsightCloudSec instance is deployed in the same AWS Partition as the accounts to be onboarded (yes/no).
      • If you are a SaaS customer, InsightCloudSec is deployed in AWS Commercial.
      • If you are self-hosted customer and you are unsure where InsightCloudSec is deployed, contact your Admin for this information.
    3. Select how to authenticate to the account (IAM Role/IAM User).
      • IAM Role is the default authentication method and should be used when possible.
      • If InsightCloudSec is in a different partition than the account you're attempting to onboard, you will have to authenticate using an IAM User.
IAM Role Authentication

In the InsightCloudSec Cloud Onboarding interface:

  1. Click Next to skip to 2. Roles.
IAM User Authentication

If you have not already, in a separate browser tab or window, login as an Admin to the relevant console (AWS Commercial, Government, China) for the Account you want to harvest.

In the InsightCloudSec Cloud Onboarding interface:

  1. If you have the appropriate permissions, click Deploy CFT (we recommend opening it in a new tab/window) to be taken directly to the CFT console inside AWS with the Rapid7 AWS Authenticating Principal CFT already loaded.

    Additional CFT Information Available

    Expand the What's included in the CloudFormation Template? drop-down to review details on what is inside the CFT and what it does. To review the CFT before deploying it, click Download CFT.

In the AWS GovCloud/China Console:

  1. Only update the default CFT parameter values if absolutely necessary. Review Getting Support if you have questions/concerns or need assistance.
  2. Select the I acknowledge that AWS CloudFormation might create IAM resources with custom names checkbox.
  3. Click Create Stack.
  4. Copy and save the Access Key and Secret Key for the IAM user in a secure place.

In the InsightCloudSec Cloud Onboarding interface:

  1. Copy and paste the Access Key and Secret Key.
  2. Click Next to proceed to 2. Roles.
Step 2: Deploy an IAM Role

InsightCloudSec utilizes an IAM role containing only the necessary permissions to harvest supported AWS services. Assuming this role is governed by an External ID. An External ID is generated for your specific InsightCloudSec organization when you initiate the process to add an AWS Account within InsightCloudSec. The External ID will be the same for every individual cloud account.

This process obeys AWS best practices and prevents the confused deputy problem from occurring. The confused deputy problem is a security issue where an entity that doesn't have permission to perform an action can coerce a more-privileged entity to perform the action.

In the InsightCloudSec Cloud Onboarding interface:

  1. For 2. Roles:
    1. Select Individual for Account selection.
    2. Click Deploy CFT as single Stack. This will open a new tab to the CloudFormation section of the Console for the AWS partition you selected earlier.

In the AWS Commercial/GovCloud/China Console:

  1. Only update the default CFT parameter values if absolutely necessary. Review Getting Support if you have questions/concerns or need assistance.

    Additional AWS-related InsightCloudSec Features

    By default, the CFT will configure the roles and policies necessary for the following features: AWS Event-Driven Harvesting, Cloud Vulnerability Management, AWS Least-Privileged Access (LPA). See those pages for additional configuration requirements; otherwise, disable the feature config by updating the corresponding drop-down menu to No.

  2. Select the I acknowledge that AWS CloudFormation might create IAM resources with custom names checkbox.
  3. Click Create Stack.
  4. Copy and save the ARN for the IAM role in a secure place.

In the InsightCloudSec Cloud Onboarding interface:

  1. Click Next to skip to 3. Finalize Connection.

Manual Onboarding instructions complete!

After completing these steps, you have completed the manual onboarding instructions for AWS. Jump to the Connect the Account in InsightCloudSec instructions.

Automated Onboarding using AWS CloudShell

The AWS onboarding process can be performed using a script that you can generate for your specific environment inside InsightCloudSec.

In the InsightCloudSec Cloud Onboarding interface:

  1. Login to your InsightCloudSec instance and open the Cloud Onboarding interface.
    • First-time Users:
      1. On the Welcome screen, review key features and capabilities, then click Onboard a Cloud Account.
      2. On the Cloud Service Providers screen, select Amazon Web Services.
      3. Select Yes - I have sufficient permissions, then click Next.
    • Returning Users:
      1. Navigate to Cloud > Cloud Accounts in the left navigation menu.
      2. Click the + Add Cloud button in the top right corner.
      3. Click the Amazon Web Services button.
  2. Select the AWS Partition the account(s) you are trying to onboard are in (Commercial, Government, China).
  3. Select if your InsightCloudSec instance is deployed in the same AWS Partition as the accounts to be onboarded (yes/no).
    • If you are a SaaS customer, InsightCloudSec is deployed in AWS Commercial.
    • If you are self-hosted customer and you are unsure where InsightCloudSec is deployed, contact your Admin for this information.
  4. Select how to authenticate to the account (IAM Role/IAM User).
    • IAM Role is the default authentication method and should be used when possible.
    • If InsightCloudSec is in a different partition than the account you're attempting to onboard, you will have to authenticate using an IAM User.
  5. Select Individual to denote you are only onboarding a single account.
  6. Update the Advanced Options as necessary:
    • Allow Eventbridge to Assume Egress Role -- Appends an IAM statement to the Rapid7 IAM Role's AssumeRolePolicyDocument allowing the EventBridge service to assume the Rapid7 role to publish events to target event buses. This avoids needing a dedicated IAM Role for Event Driven Harvesting (EDH) in each producer Account. Review the Event-Driven Harvesting Overview for more information.
    • Enable Automation Full Access Policy -- Enables the full access policy, which includes full wildcard permissions for relevant AWS services. This is useful for testing, and as such, is off by default.
    • Enable Container Vulnerability Assessment -- Enables the Container Vulnerability Assessment feature. Review Container Vulnerability Assessment for more information.
    • Enable Eventbridge Auto Provisioning -- Grants the Rapid7 IAM Role permission to create/manage EventBridge Rules/Targets and create/manage an SQS queue for consuming the Events. This is for Event-Driven Harvesting.
    • Enable Host Vulnerability Assessment -- Enables the Host Vulnerability Assessment feature. Review Host Vulnerability Assessment for more information.
    • Enable LPA Auto Provisioning -- Grants the Rapid7 IAM Role permission to access CloudTrail to create the necessary AWS Glue tables and to create/execute Athena queries with a s3 bucket for results. Review the AWS Least-Privileged Access (LPA) Overview for more information.
    • LPA Working Bucket -- If LPA is enabled, this is the name of the S3 bucket used for storing the results of the Athena query.
    • IAM Automation Policy Name -- If there is an existing automation policy in your account and you wish to grant Rapid7 access to it (for Bot Factory, Resource Management, etc.), this is the name of the policy. An IAM Policy with the provided name MUST exist within each Account the Stack is deployed to; otherwise, the deployment will fail.
  7. Click Generate & Download Script.
  8. In a separate browser tab or window, login as an Admin to the AWS Console for the primary account you want to onboard.

In the AWS Commercial/GovCloud/China Console:

  1. Click CloudShell in the top right corner of the AWS Console.
  2. Once the environment is finished loading, click the Actions drop-down menu, then click Upload File.
  3. Select the onboarding script from its downloaded location. The file will be uploaded to /home/cloudshell-user by default.
  4. Run the script (python3 onboard.py) and follow the prompts to create everything needed to onboard the Account. The script will not run with Python 2.
    • Provide a CFT stack name (or press Enter to use the default).
    • The configuration is complete. The necessary values are displayed.
  5. Copy the configuration information to a secure location.
IAM Role Authentication

In the InsightCloudSec Cloud Onboarding interface:

  1. Proceed to the next section of the documentation.
IAM User Authentication

In the InsightCloudSec Cloud Onboarding interface:

  1. Copy and paste the Access Key and Secret Key.

Automated Onboarding instructions complete!

After completing these steps, you have completed the automated onboarding instructions for AWS. Jump to the Connect the Account in InsightCloudSec instructions.

Connect the Account in InsightCloudSec

The AWS onboarding process is nearly complete; all that remains is to setup an account nickname and provide authentication information (and advanced options).

In the InsightCloudSec Cloud Onboarding interface:

  1. Provide the Role ARN for the new IAM role inside the Account.
  2. Provide the Nickname for the Account. This is a unique value that will be used to search Accounts across the system based on an identifiable label.
  3. Optionally, update the Advanced Options:
    • Role Session Name
    • Duration
  4. Click Connect Account.

Success! You onboarded an Account

Congratulations on successfully onboarding an AWS Account! InsightCloudSec will now detect the following:

  • If there are any missing permissions that could cause impaired visibility into your Account
  • For information about modifying an existing onboarded account, check out the Cloud Account Setup & Management page.