Onboard an AWS Organization

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 and Organizations capability available under Cloud > Cloud Accounts (individual accounts are listed on the Listing page; Organizations are listed on the Organizations page). This functionality should not be confused with the InsightCloudSec-specific Organizations capability that allows for multi-tenant functionality available under System Administration > Organizations. If you are looking to onboard a single AWS Account instead, see Onboard an AWS Account.

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 Organization

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 custom roles 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 an 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 AWS console 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

These instructions must be performed in the Organization account and not in a member account underneath the Organization.

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 (Organization Account)

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 Organization for Account selection.
    2. Click Deploy CFT as single Stack (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. This CFT needs to be deployed inside the Management Account.

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.
Step 3: Deploy an IAM Role (Member Accounts)

This step is similar to Step 2 but instead of deploying the CFT as a Stack, you'll need to deploy the same CFT as a StackSet. This will allow the new IAM role to propagate to all of the member accounts that should to be harvested by InsightCloudSec.

In the InsightCloudSec Cloud Onboarding interface:

  1. Click Download CFT.
  2. Copy and save the Generated External ID and Authenticating Principal to a secure location.

In the AWS Commercial/GovCloud/China Console:

  1. Access the CloudFormation service and click StackSets in the left-hand menu.
  2. In the top right corner of the StackSets table, click Create StackSet.
  3. Choose a template.
    1. (Optional) Provide an IAM admin role to perform all the operations in the StackSet within your account(s) and adjust the IAM execution role name as necessary.
    2. Click Template is ready.
    3. Click Upload a template file.
    4. Click Choose file and select the CFT you just downloaded.
    5. Click Next.
  4. Specify the StackSet details.
    1. Enter a name and description for the StackSet.
    2. Edit the parameters.
      1. Provide the Authenticating Principal and External ID.
      2. Adjust the Feature Enablement drop-downs and configuration as necessary.

        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.

      3. Click Next.
  5. Configure StackSet options.
    1. Add tags or change the execution configuration as necessary.
    2. Click Next.
  6. Set deployment options.
    1. Click Deploy new stacks.
    2. Choose to either deploy to accounts or organizational units, then provide a comma-delimited list of accounts or organizational units (or upload a CSV file).
    3. Select us-east-1 to deploy the stack. Currently only single-region role deployment is supported.
    4. Click Next.
  7. Review and create the StackSet.
    1. Review the StackSet's configuration to ensure everything is accurate.
    2. Acknowledge the warning about IAM capabilities toward the bottom of the page.
    3. Click Create Submit.
    4. Verify the StackSet is created successfully.

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 Organization to denote you are onboarding an Organization.
  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). This is for the Management Account.
    • Provide a CFT stack set name (or press Enter to use the default). This is for the Member Accounts.
    • 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
  • Assuming you completed the Organization-related portion of the onboarding, if the Account is an AWS Organization Account, you can enable Account Discovery. If Account Discovery is enabled, Rapid7 can onboard and collect information on related AWS Organizations and Accounts via the onboarded Tenant. Click Enable Auto Discovery at the bottom of the window to start this process.
  • For information about modifying an existing onboarded account, check out the Cloud Account Setup & Management page.

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 Auto-Sync Accounts.
  2. Click UPDATE.

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

Modifying an AWS Organization in InsightCloudSec

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

  1. From InsightCloudSec, go to Cloud > 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: Select this box to add all accounts associated with the organization. If not checked, each account must be added manually.
    • Auto-remove suspended accounts: 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: Select this box to allow InsightCloudSec to automatically badge your incoming accounts based on AWS account tags
    • Limit import scope: 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.

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. Accounts added via an AWS Organization will also have a few InsightCloudSec-based Badges automatically associated to them:

  • cloud_org_path: shows the location of the account in the Organization tree
  • Despite not being listed explicitly, the system.cloud_organization:<cloud_org_id> badge is associated with all accounts in an Organization.

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

StageDescription
Retrieves tags and labels from each account and project and compares them with ResourceTags associated with the cloud account 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.
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’.

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.