Connecting AWS Organizations to Self-Hosted InsightCloudSec

Once your InsightCloudSec instance is up and running the first thing you'll want to do is begin integrating your AWS organization(s) to take advantage of the security insights that apply to your entire cloud footprint. If you have any issues or questions with this setup, reach out to the support team through the Customer Support Portal.

Integration overview

For InsightCloudSec to securely access the information contained within your AWS Organization and its member accounts, you'll need to create and set up some roles, policies, and trust relationships using provided CloudFormation Templates (CFTs). If you're not familiar with this process we recommend that you review AWS' IAM documentation for more information on these concepts.

Prerequisites

Before you configure anything in your AWS environment, you'll need the following:

• Admin access to your AWS organization and the member accounts you want to harvest
• The unique Amazon Resource Name (ARN) for your InsightCloudSec instance. Your unique InsightCloudSec ARN could look something like this (if you used the default deployment values): arn:aws:iam::123456789123:role/DivvyCloud-Install-Role, with the 12-digit account ID value being replaced with the ID of the account where InsightCloudSec is hosted
  • If you followed the AWS - EC2 or ECS Fargate - Terraform deployment instructions, this role will be created automatically alongside the InsightCloudSec instance inside the desired account.
  • Domain Admin permissions within InsightCloudSec
• InsightCloudSec IAM CloudFormation Templates (CFTs) (see below) and the permissions to use & implement CFTs

We recommend that you review the documentation on AWS Additional Configuration, particularly the additional steps to support Opt-in regions.

CloudFormation Templates

Our team maintains the following templates to help automate policy and role setup across your organization management and member accounts:

• DivvyCloud-AWS-IAM-Harvest-Role-Org-CFT.yaml -- Deploys a role and policy to the organization management account that allows InsightCloudSec to harvest AWS organization data and information about member accounts
• DivvyCloud-AWS-IAM-Harvest-Role-Member-CFT.yaml -- Deploys a standard harvesting role and policy to the desired account(s) to harvest AWS resource data

Service Control Policies - Implementation & Known Issues

Within AWS, a Service Control Policy (SCPs) is a type of policy used to manage permissions at the organization level. Per AWS, "SCPs offer central control over the maximum available permissions for all accounts in your organization. SCPs help you to ensure your accounts stay within your organization’s access control guidelines.”

• Read more from AWS here on using SCPs.

Many organizations choose to implement SCPs for security purposes, while also providing the permissions required for InsightCloudSec to function with full visibility into their AWS accounts.

It is important to note that when implemented, many SCPs will block the required permissions InsightCloudSec needs to operate -- even when permissions have been explicitly granted via roles and policies.

• If this scenario applies to your environment, you will need to revise your SCP to ensure you have permitted the required InsightCloudSec permissions.
• This is normal SCP behavior as they are organization-wide policies. SCPs are configured within AWS to supersede other types of permissions.
• You can review our AWS IAM Policies for details, otherwise refer to the AWS documentation on SCPs.
• In more limited cases an SCP in conflict with an existing role/policy can also result in visibility issues.

Configure InsightCloudSec

Now that the AWS Organization and relevant member accounts have been configured for harvesting, it's time to enable harvesting within InsightCloudSec.

Prerequisites

Before you can successfully add an Organization to InsightCloudSec, you will need the following on hand:

• The ARN for the organization harvesting role
• The ARN for the standard harvesting role

Configure InsightCloudSec

1. Open the InsightCloudSec platform to the in-progress cloud account setup page.
2. Provide a nickname for the Organization. This creates a system Badge containing the nickname that can be searched or referenced throughout InsightCloudSec.
   Adding a Cloud Organization will replace the credentials of associated cloud accounts already in InsightCloudSec. Misconfiguration of the roles in member accounts will result in gaps in visibility.
3. Provide credentials for harvesting Organization data.
   1. Provide the Role ARN for the Organization Management Account role. For example: arn:aw:iam::123456789012:role/InsightCloudSec-Org-ListDesc-Role
   2. Provide a session name and duration. The session name will display in any CloudTrail logs and is useful for auditing purposes.
4. Provide credentials for harvesting Organization member accounts data.
   1. Provide the Role ARN suffix for the standard harvesting role. For example: InsightCloudSec-Org-Member-Role
   2. Provide a session name and duration. This will display in any CloudTrail logs and is useful for auditing purposes.
5. Configure the optional badging and scope-limiting settings.
   • Provide one or more prefixes to match accounts against. Any accounts with names that match those prefixes will be excluded.
   • to automatically remove suspended AWS accounts from InsightCloudSec, select Auto-remove suspended accounts. When enabled, a background process begins running and removes the accounts automatically as they're found.
   • To allow InsightCloudSec to automatically badge your incoming accounts based on AWS account tags, select Auto-Badge Accounts.
   • To only include nested accounts and OUs associated with a given ID (or set of IDs), select Limit Import Scope and provide Organizational Unit ID(s).
6. When you've completed all of the fields and details outlined above, click Add. After successful submission a background job is enqueued that will fetch and synchronize all of your accounts. Depending on the number of accounts this will take a few minutes. In this example walkthrough, 127 accounts took a little over 1 minute.

Expected Validation

When the form is submitted the form values are validated for formatting correctness. Next we test the Organization Management Role for the following and will reject submission if any of the following fail.

• Attempt to perform AssumeRole operation with Instance Role credentials.
• Test role permissions with iam:SimulatePrincipalPolicy to verify we can perform all necessary Organization harvesting. We test the policy for all actions documented above in the "Organization Management Role" section.

The member account roles are not validated at this point. Validation of member accounts is done during the syncing process and any failures are reflected in the Cloud account status on the Cloud Listing page.

Editing Organization Credentials

To make changes to any part of the credential configuration requires a complete resubmission of all fields due to all fields being encrypted in storage.

Filtering options can be updated independently by leaving all credential fields blank. If blank the existing credential configuration is left as is.

From the Organizations page, click the link for the number of accounts. This will redirect you to the Cloud Listing page filtered by the Cloud Organization using a badge associated with all member accounts.

Errors in permissions or failure to assume a role are represented by the cloud status.

Post-Setup Information

Congratulations on integrating your AWS Organization with InsightCloudSec. Below you'll find some key information about your new integration as well as managing it.

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

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.

Auto-badging

As an enhancement to support for provider-base 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.

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.