AWS Cloud - Onboarding

After InsightCloudSec is successfully installed, you're ready to start harvesting resources from your target accounts. This documentation provides details on configuring AWS to "talk" with InsightCloudSec securely for both admin and non-admin users and explains the different onboarding workflows you can expect for new and returning users.

Getting Started with Onboarding AWS

Before you can begin the AWS onboarding process, you'll need to login to InsightCloudSec and open the Cloud Account Onboarding Wizard, which provides a different experience depending on the type of user you are:

First-time User: InsightCloudSec is freshly deployed and this will be the first time a Cloud Service Provider (CSP) has been onboarded.
Returning User: InsightCloudSec has one or more CSPs already onboarded and you would like to add a new AWS account.
Admin User: You can login to the AWS console and have the appropriate access to grant InsightCloudSec access to your account(s).
Non-Admin User: You can interact with InsightCloudSec and would like to onboard an AWS account(s) but do not have the appropriate AWS access to grant InsightCloudSec access to your account(s).

In addition, we also provide instructions for:

Existing Cloud Accounts: For information about modifying an existing AWS account, check out the Cloud Account Setup & Management page.

📘
Need Support?
We are here to help! If you have questions or concerns reach out to us through the Customer Support Portal.

Configuration Information for AWS

AWS Details

There are several steps that must be taken within the AWS console to enable InsightCloudSec to get access to an account, and this page provides those steps.

Additional Resources on AWS include:

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); links to view the CFTs can be found below while the policies are contained on AWS Commercial Policies.

Rapid7 AWS IAM Roles CFT
Rapid7 AWS Authenticating Principal CFT (GovCloud/China)

👍
Additional AWS-related InsightCloudSec Features
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.

AWS Event-Driven Harvesting

Container Vulnerability Management

Host Vulnerability Management

AWS Least-Privileged Access (LPA)

Non-Admin Onboarding for AWS

If you've determined that you're not an Admin user or you're not sure, you will need to provide an Admin within your organization with the "Amazon Web Services Admin Instructions". Once the Admin has completed the instructions, they should be able to provide you with answers and/or content for the following required fields:

An AWS partition
A Role ARN
A Nickname
An authentication method and credentials

Steps for Non-Admin Onboarding

The steps to complete this process for both First-time Users and Returning Users are provided below. Step 2a and 2b provide specifics for the two user types.

1. Log in to your InsightCloudSec installation.

2-a. For first-time users a successful log in should launch the Onboard a Cloud Account workflow. You will need to select "Amazon Web Services" as your Cloud Service Provider, and then select "No - Help me identify the details needed". Click "Next" to start the onboarding process.

2-b. For returning users navigate to "Cloud --> Cloud Accounts" and select "Add Cloud". *You will need to select "Amazon Web Services" as your Cloud Service Provider, and then select the "Don't have admin access?" option at the bottom right of the window.

3. Copy the details from "Amazon Web Services Admin Instructions" and share them with your Admin.

4. Once your Admin has completed the setup, they can provide you with the required information to complete the configuration.

5. Return to the onboarding workflow, provide input to the required fields to finalize your AWS onboarding setup and click "Connect".

Admin Onboarding for AWS

For administrative users this section includes step-by-step instructions for the configuration required in both the Amazon Web Services portal and the InsightCloudSec Onboarding Wizard to connect.

If you are connecting to InsightCloudSec for the first time, you will be greeted by a workflow that shares some details around InsightCloudSec capabilities and allows you to select your Cloud Service Provider to start the onboarding process.
If you have connected to InsightCloudSec previously but are setting up AWS for the first time, you will need to navigate to "Cloud --> Cloud Accounts" and select the "Add Cloud" option to open the cloud onboarding.

Using either path above select "Amazon Web Services" as your CSP to get started with the admin onboarding.

Introduction (Step 1)

In the InsightCloudSec Onboarding Wizard

1. Select the AWS partition (Commercial, Government, China) in which the account is located.

If "Commercial":
- Copy the "Authenticating Principal ID" to a secure location.
If "Government":
- Click "Launch CFT" to open the AWS CloudFormation Console (in a new browser tab) and execute the CFT to create an IAM user.
If "China":
- Click "Launch CFT" to open the AWS CloudFormation Console (in a new browser tab) and execute the CFT to create an IAM user.

2. Click "Next" to go to 2. Role Deployment.

Role Deployment (Step 2)

In the InsightCloudSec Onboarding Wizard

1. Select if you're adding accounts from an organization or an individual account.

👍
Additional AWS-related InsightCloudSec Feature Configuration
The CFTs used below will include several drop-down menus under a "Feature Enablement" section. Depending on which feature(s) you wish to enable, select "Yes" from the associated drop-down menu.

If adding an organization:
- Select the "I acknowledge and accept the permissions outlined in the above CFT" checkbox.
- Click "Launch CFT" to open the AWS CloudFormation Console (in a new browser tab) and execute the CFT to onboard the Management Account.
- Deploy the same CFT to all member Accounts using a CloudFormation StackSet.
If adding an individual account:
- Select the "I acknowledge and accept the permissions outlined in the above CFT" checkbox.
- Click "Launch CFT" to open the AWS CloudFormation Console (in a new browser tab) and execute the CFT to onboard the account.

2. Click "Next" to go to 3. Finalize Connection.

Finalize Connection (Step 3)

In the InsightCloudSec Onboarding Wizard

1. Verify the Role ARN has automatically populated the field.

2. Provide a "Nickname" for the account.

3. Select how to authenticate:

If "Instance Profile" (Commercial):
- Click "Connect Account" to finalize your AWS setup.
If "IAM User via API Keys" (China/GovCloud):
- Provide the Access Key and Secret Key.
- Click "Connect Account" to finalize your AWS setup.

👍
Success!
Congratulations on successfully onboarding an AWS account! InsightCloudSec will now detect the following:

If there are any missing permissions which could cause impaired visibility into your account

If the account is an AWS Organization; if it is an Organization, you can enable Account Discovery. If Account Discovery is enabled, Rapid7 can onboard and collect information on AWS member accounts via the onboarded Organization. Click "Enable Auto Discovery" at the bottom of the window to start this process.

Organization Post-Onboarding Information

If you followed the instructions above and onboarded an AWS Organization, you should have at least your Organization account with full visibility in InsightCloudSec. Review the following sections for more information on augmenting your Organization onboarding experience or managing the Organization within InsightCloudSec.

Enabling Account Discovery

Once an Organization is onboarded to InsightCloudSec, we automatically detect the Organization and prompt you to enable Account Discovery. If you clicked the "Enable Auto Discovery" button within the onboarding wizard, you'll be taken to the Edit Organization Config window for the new Organization.

1. From the Edit Organization Config window, select the "Auto-Sync Accounts" checkbox.

2. Click "UPDATE".

Once enabled, Accounts are discovered via the API dynamically and configured with defaults you provide.

Modifying an Organization

After onboarding an AWS Organization, you can edit configuration information at any time.

1. From InsightCloudSec, click expand "CLOUD", then click "Cloud Accounts -> Organizations".

2. Next to the desired Organization, click the options button (hamburger icon), then click "Edit Organization".

3. Adjust the nickname or credentials values as necessary.

4. Adjust the scope/badging options as necessary:

"Member Accounts to Skip" -- Enter details for member accounts (ID’s or Names) to be skipped (e.g., you have a group of development accounts you are not interested in tracking)
"Auto-Sync Accounts" (checkbox) -- Select this box to add all accounts associated with the organization. Note: If not checked, each account must be added manually
"Auto-remove suspended accounts" (checkbox) -- Select this box to automatically remove suspended AWS accounts from InsightCloudSec. As soon as this checkbox is enabled, a background process will begin running and remove the accounts automatically as they are found
"Auto-Badge Accounts" (checkbox) -- Select this box to allow InsightCloudSec to automatically badge your incoming accounts based on AWS account tags
“Limit import scope” (checkbox) -- Select this box and provide Organizational Unit (OU) ID(s) to only include nested accounts and OUs associated with a given ID (or set of IDs)

5. Click "UPDATE".

Badging of Accounts

Accounts added via an AWS Organization will have a few Badges automatically associated to them:

cloud_org_path: shows the location of the account in the Organization tree
All tags associated with accounts are added as badges

Note: Despite not being listed explicitly, the system.cloud_organization:<cloud_org_id> badge is associated with all accounts in an Organization.

Changes to Credential Management

Because all accounts within the AWS Organization use the same credential configuration, they are considered as "managed" by the organization. This is reflected on the cloud settings page where the option to edit credentials and delete the account are not available.

1371 — Managing Organization Credentials

Auto-badging

As an enhancement to support for provider-based organizations InsightCloudSec includes auto badging capabilities. The purpose of auto-badging is to create a 1:1 map of AWS account-level tags to Badges in InsightCloudSec. This allows Clouds to be scoped to a badge that maps to the account tag.

Note: Once the tags and labels are harvested into InsightCloudSec as badges - you cannot delete them in InsightCloudSec - they must be deleted in AWS and the changes will propagate to InsightCloudSec.

Auto-badging takes place in two stages.

Periodically a process retrieves tags/labels from each account/project and compares them with ResourceTags associated with the corresponding cloud in the InsightCloudSec database.
- If there are any changes detected, the ResourceTags in the database are overwritten with the values from the account/project. This means that Cloud Account tags should not be locally modified since any local changes will be overwritten the next time the process runs. Additionally any local changes that are made to Cloud Account tags are not pushed back up to the cloud provider.
Periodically a process retrieves all ResourceTags from the local database that are associated with the accounts managed by an organization. For each cloud the list of tags for that cloud is compared with the current list of Badges and for each Key/Value pair of tags:
- Existing Badges with a Key prefix of system. are skipped.
- If the corresponding Badge with the Key/Value pair for that cloud does not already exist, it is created.
- If a tag Value changes, the Badge with the corresponding Key will be updated to that value.
- If a Badge no longer has a tag with a corresponding Key, it will be deleted.
- All Badges that have a corresponding tag will have their autogenerated column set to ‘true’ even if they were previously set to ‘false’.