InsightCloudSec Docs

Welcome to the InsightCloudSec Docs!

InsightCloudSec by Rapid7 (formerly DivvyCloud) is a Cloud-Native Security Platform that provides real-time analysis and automated remediation for continuous security and compliance for your multi-cloud environment.

For questions reach out to us through [email protected].

Take Me to the Docs!    Release Notes

AWS Cloud Setup (Single Cloud Account)

Integrating a single AWS account with InsightCloudSec

For users looking to harvest data from a single cloud account, InsightCloudSec requires a bit of configuration within AWS. After you've finished with this set of instructions, you'll have added an AWS account to InsightCloudSec and your environment's services and data will be harvested.

If you need to add multiple accounts grouped under an AWS organization, review AWS Cloud Setup (Organizations).

Create the InsightCloudSec User & Assume Role Policies

Before configuring the role and/or user that InsightCloudSec will use to harvest your AWS data, first two policies will need to be created: one to access the AWS services that InsightCloudSec supports harvesting for and one to allow InsightCloudSec to assume a role within your AWS environment. These policies will be used throughout AWS Cloud Setup.

User Policies

🚧

Prerequisites

Before continuing on to configure AWS for a new policy, the following items must be addressed:

  • Decide which IAM policy InsightCloudSec will use to harvest your data; we recommend leaving this page open in another browser tab
  • Optionally, enable any Opt-in Regions

Additionally, if AWS GuardDuty is enabled, you must Trust InsightCloudSec first

1. Login as an Admin to the AWS account you would like to harvest and access the Identity & Access Management (IAM) service.

  • This service can be found on the Services main page under Security, Identity, & Compliance. You can also enter "IAM" into the search bar.
  • Once at the IAM dashboard, click "Policies".
IAM PoliciesIAM Policies

IAM Policies

2. Click "Create Policy".

Create PolicyCreate Policy

Create Policy

3. Click "JSON".

JSON Policy TabJSON Policy Tab

JSON Policy Tab

4. Add the desired policy.

  • Select the existing JSON and delete it.
  • Copy and paste the policy into the JSON text window.
    • The example in the picture is the supplemental AWS-Managed Standard (Read-Only) Policy.
  • Click "Next: Tags".
Read Only Policy AdditionRead Only Policy Addition

Read Only Policy Addition

5. Optionally, add tags to help identify, organize, or search for the policy.

  • Click "Add tag".
  • Provide a "Key" and optional "Value".
  • Click "Next: Review" when finished adding tags.

6. Review and create the policy.

  • Name your policy something meaningful to you. We recommend something like InsightCloudSec-Supplemental-AWSManaged-ReadOnly-Policy or InsightCloudSec-Power-User-Policy. Note: you cannot have spaces in the policy name.
  • Optionally, add a policy description to help clarify for what the policy will be used.
  • If everything looks good, click "Create Policy".
Create PolicyCreate Policy

Create Policy

🚧

Using Standard (Read-Only) Policy -- Customer-Managed

If using the fully-enumerated Customer-Managed Standard (Read-Only) Policy, you will need to create three separate policies to accommodate the three parts of the policy. Repeat steps 2-6 to create policies for each part.

Assume Role Policy

Repeat the steps above to create the following policy. This policy will need to be added to your AWS environment regardless of the desired Assume Role authentication method to be used:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Resource": "arn:aws:iam::*:role/*"
        },
        {
            "Action": "sts:GetCallerIdentity",
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

📘

AWS GovCloud Users

If using AWS GovCloud, update arn:aws:iam::*:role/* to arn:aws-us-gov:iam::*:role/* in the policy above.

Setup an Assume Role Authentication Type

To properly harvest data from AWS, InsightCloudSec relies on an assume role method of authentication, which means you'll need to create a user and/or role within your account that InsightCloudSec can assume to securely access the data. There are two types of assume role methods: Instance Assume Role and Secure Token Service Assume Role.

🚧

Prerequisites

Before continuing on to setup an Assume Role authentication method, the following items must be addressed:

Instance

When deploying InsightCloudSec on to one or more virtual private servers within Amazon Web Services (AWS), then we strongly recommend using the Instance Assume Role method. Authentication using this mechanism leverages temporary API credentials that are rotated every 60 minutes.

The steps below describe how to configure Instance Assume Role for your AWS-hosted InsightCloudSec instances. At the end of this section, you'll have configured an EC2 service role with IAM user and assume role policies so that the EC2 instance hosting InsightCloudSec can securely harvest AWS account data.

Instance Assume Role - End StateInstance Assume Role - End State

Instance Assume Role - End State

Note: If InsightCloudSec is hosted somewhere else other than AWS, we recommend using the Secure Token Service (STS) instructions instead.

1. Login as an Admin to the AWS account you would like to harvest (where InsightCloudSec is/will be deployed) and access the Identity & Access Management (IAM) service.

  • This service can be found on the Services main page under Security, Identity, & Compliance. You can also enter "IAM" into the search bar.
  • Once at the IAM dashboard, click "Roles".
IAM RolesIAM Roles

IAM Roles

2. Click "Create role".

3. Select the trusted entity and use case for the role.

  • Leave "AWS service" selected for the trusted entity.
  • Click "EC2" for the use case.
  • Click "Next: Permissions".
Trusted Entity & Use Case - ServiceTrusted Entity & Use Case - Service

Trusted Entity & Use Case - Service

4. Attach the IAM user and Assume Role policy you created in the previous sections.

❗️

Read Only

If you decided to use the AWS-managed supplemental policy, do not forget to also attach the standard AWS ReadOnlyAccess policy as well!

  • Type into the search bar or use the filter functionality to search for the policies you created.
  • Select the checkbox next to each of the two policies to attach them to the role.
  • Click "Next: Tags".
Attach PoliciesAttach Policies

Attach Policies

5. Optionally, add tags to help identify, organize, or search for the role.

  • Provide a "Key" and optional "Value".
  • Click "Next: Review" when finished adding tags.

6. Review and create the role.

  • Name the role something meaningful to you. We recommend something like InsightCloudSec-Instance-Assume-Role. Note: you cannot have spaces in the role name.
  • Optionally, update the role description to help clarify for what the role will be used.
  • Confirm both policies are attached.
  • If everything looks good, click "Create role".
Review RoleReview Role

Review Role

7. After successful creation of the role, search for it and click the name.

Search for a RoleSearch for a Role

Search for a Role

8. Copy the Role ARN and save it for later use. You will use this Amazon Resource Name (ARN) to configure InsightCloudSec and connect to your AWS account.

Role ARNRole ARN

Role ARN

9. Either during launch or after, assign the role you just created to the EC2 instance(s) that are running InsightCloudSec.

  • We recommend an instance with at least 4 cores, 8GB of memory, and 30 GB of disk space
  • Review the AWS documentation for information on attaching an IAM role to an instance after it's been launched.
New Instance IAM RoleNew Instance IAM Role

New Instance IAM Role

After the role has been assigned, the account is ready to be harvested. Continue on to Add Cloud Account to InsightCloudSec.

Secure Token Service (STS)

When deploying InsightCloudSec somewhere outside of AWS, then we strong recommend using the Secure Token Service method. Like Instance Assume Role, Secure Token Service uses an authentication mechanism that leverages temporary API credentials that are rotated every 60 minutes or less. The steps below describe how to configure Secure Token Service for your AWS accounts to be connected to your InsightCloudSec platform and harvested. At the end of this section, you'll have configured a AWS user with an assume role policy, an AWS account role with an IAM user policy, and a trust relationship established between them so that whatever is hosting InsightCloudSec can securely harvest AWS account data.

STS Assume Role - End StateSTS Assume Role - End State

STS Assume Role - End State

Note: If InsightCloudSec is hosted within AWS, we recommend using the Instance instructions instead.

Create a User for InsightCloudSec to Assume

1. Login as an Admin to the AWS account you would like to harvest and access the Identity & Access Management (IAM) service.

  • This service can be found on the Services main page under Security, Identity, & Compliance. You can also enter "IAM" into the search bar.
  • Once at the IAM dashboard, click "Users".
IAM UsersIAM Users

IAM Users

2. Click "Add user".

3. Set user details.

  • Name the user something meaningful to you. We recommend something like InsightCloudSec-STS-User.
  • Select the "Programmatic access" checkbox.
  • Click "Next: Permissions".
Add User - DetailsAdd User - Details

Add User - Details

4. Set permissions.

  • Select "Attach existing policies directly".
  • Search for and attach the Assume Role policy you created in the previous section.
  • Click "Next: Tags".
Add User - PermissionsAdd User - Permissions

Add User - Permissions

5. Optionally, add tags to help identify, organize, or search for the user.

  • Provide a "Key" and optional "Value".
  • Click "Next: Review" when finished adding tags.

6. Review and create the user.

  • Confirm the correct access type is set and policy is attached.
  • If everything looks good, click "Create user".
  • Copy the username and save it for later use. You will use this username to configure AWS trust relationships later.

7. Save the user's credentials.

  • You should receive a Success message from the console at this point. Assuming that you have, you will see your user listed along with an Access key ID and Secret access key.
  • Do not close out this screen until you have saved your Access key ID and Secret access key.
  • Save your keys by clicking "Download .csv" and copying & pasting the values from the file, or click "Show" under Secret access key column and copy both the Access key ID and Secret access key from this page before clicking "Close".

❗️

Save Your Credentials

You will need these API credentials for each additional cloud that you onboard, so make sure to save them in a safe place after you create your initial account.

Save Your CredentialsSave Your Credentials

Save Your Credentials

Create a Role for the InsightCloudSec User

1. Login as an Admin to the AWS account you would like to harvest and access the Identity & Access Management (IAM) service.

  • This service can be found on the Services main page under Security, Identity, & Compliance. You can also enter "IAM" into the search bar.
  • Once at the IAM dashboard, click "Roles".

2. Click "Create role".

3. Select the trusted entity and use case for the role.

  • Select "Another AWS account" for the trusted entity.
  • Provide the Account ID for the AWS account that contains the user you just created in the previous section.
  • Optionally, select the "Require external ID" checkbox and provide an external ID for additional security. Note: While the External ID field is optional and only relevant if you are adding a trusted AWS account, we strongly recommend including an external ID to ensure additional security for this account.
  • Click "Next: Permissions".

4. Attach the IAM user policy (e.g., Power User, Standard (Read Only), etc.) you created first-hand.

❗️

Read Only

If you decided to use the AWS-managed supplemental policy, do not forget to also attach the standard AWS ReadOnlyAccess policy as well!

  • Type into the search bar or use the filter functionality to search for the policy you created.
  • Select the checkbox next to each of the two policies to attach them to the role.
  • Click "Next: Tags".

5. Optionally, add tags to help identify, organize, or search for the role.

  • Provide a "Key" and optional "Value".
  • Click "Next: Review" when finished adding tags.

6. Review and create the role.

  • Name the role something meaningful to you. We recommend something like InsightCloudSec-STS-Assume-Role. Note: you cannot have spaces in the role name.
  • Optionally, update the role description to help clarify for what the role will be used.
  • Confirm both policies are attached.
  • If everything looks good, click "Create role".

7. After successful creation of the role, search for it and click the name.

Search for a RoleSearch for a Role

Search for a Role

8. Copy the Role ARN and save it for later use. You will use this Amazon Resource Name (ARN) to configure InsightCloudSec and connect to your AWS account.

Role ARNRole ARN

Role ARN

7. Update the new role's trust relationships.

  • Click "Trust Relationships".
  • Click "Edit trust relationship".
  • Replace "root" in the Principal AWS value with the username of the user you created in the previous section, prefixed with user/. For example:
// Before
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123412341234:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "test-external-id"
        }
      }
    }
  ]
}

// After
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123412341234:user/InsightCloudSec-STS-User"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "test-external-id"
        }
      }
    }
  ]
}

Add Cloud Account to InsightCloudSec

One final step is required before InsightCloudSec can begin harvesting your AWS data: adding the cloud account information to InsightCloudSec. This is straightforward now that the user and/or role has been created and properly configured with the desired policies.

🚧

Prerequisites

Before continuing on to setup a cloud account within InsightCloudSec, the following values must be acquired via one of the previous sections:

  • (STS Only) API Key
  • (STS Only) Secret Key
  • Role ARN
  • (Optional) External ID

1. Login to your InsightCloudSec platform and click "Clouds" in the left-hand navigation menu.

  • Click "Add Cloud" in the top right-hand corner.
  • Click "Amazon Web Services".
Add CloudAdd Cloud

Add Cloud

2. Select an authentication type depending on what you setup above.

3. Provide account details.

  • Instance Assume Role
    a. Input a nickname for the cloud account. This name will only be surfaced in InsightCloudSec and can be used to differentiate between other cloud accounts.

    b. Input the Role ARN for the role you created above.

    c. Update the session name as desired. This name is only used for CloudTrail API audit purposes. We recommend InsightCloudSec.

    d. If you supplied an External ID in previous sections, provide that value.

    e. Optionally, select a Harvesting Strategies for this account.

  • STS Assume Role
    a. Input a nickname for the cloud account. This name will only be surfaced in InsightCloudSec and can be used to differentiate between other cloud accounts.

    b. Input the API and Secret Key for the user you created above.

    c. Optionally, update the session duration as desired. We recommend leaving this as the default value.

    d. Input the Role ARN for the role you created above.

    e. Update the session name as desired. This name is only used for CloudTrail API audit purposes. We recommend InsightCloudSec.

    f. If you supplied an External ID in previous sections, provide that value.

    g. Optionally, select a Harvesting Strategies for this account.

4. Click "Add Cloud".

What's Next

Now that you've successfully added an AWS account and begun the harvesting process, the process for adding additional accounts is streamlined. Review Adding Additional AWS Accounts for details.

If you're looking to add multiple accounts headed under an AWS organization, review AWS Cloud Setup (Organizations). Otherwise, you might be interested in AWS Additional Configuration or AWS Event-Driven Harvesting.

Updated 27 days ago

AWS Cloud Setup (Single Cloud Account)


Integrating a single AWS account with InsightCloudSec

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.