DivvyCloud

Welcome to the DivvyCloud Docs!

DivvyCloud is a Cloud Security Posture Management (CSPM) platform that provides real-time analysis and automated remediation across leading cloud and container technologies.

For questions about documentation reach out to us [email protected]

Take Me to the Docs!    Release Notes

Organizations (AWS)

Overview

In DivvyCloud, you can add multiple projects, known as "organizations". The Organizations feature is available from the Clouds page within DivvyCloud. This feature allows you to enable the automatic addition of all associated cloud accounts and badging by organizations or folder.

DivvyCloud Organizations Page

Learn more about AWS Organizations here.

Prerequisites

Before getting started with adding an AWS Organization in DivvyCloud you will need the following:

  • A functioning DivvyCloud platform installation.
  • One or more AWS Organizations.
  • Access to AWS Console and/or API.
  • Familiarity with STS Assume Role and cross-account Trust Relationships.
  • Please review the documentation on Configuring AWS particularly the additional steps to support Opt-in regions.
  • Permissions to create IAM Roles in ALL accounts within the Organization.
  • Permission to create "Trust Relationship" between Roles and Users.
  • Access and permission to use CloudFormation's StackSets for deploying Roles across all accounts.

๐Ÿ“˜

General Support

If you have questions or need information before you get started reach out to us at [email protected]

View Your Organization in the AWS Console

  1. From anywhere in the AWS console, select the dropdown in the upper right hand side with the current user session.

  2. Select "My Organization".

  • The default view lists all Account that are members of the Organization. This view is helpful for identifying individual Account numbers as well as which Account is designated as the Master account.
  1. Identify the Master account and note the Account ID.

AWS Organizations - Master Account

  1. From the three tabs "Accounts", "Organize Accounts", and "Policies" --> Select "Organize Accounts".

AWS Organizations - Organize Accounts

This view shows Organizational Units (OUs) as well as the Accounts within a particular OU. Accounts and OUs can be nested within another OU creating a rich file-tree like structure for organizing Accounts.

  • Each Account has a location in this Organization tree.
  • DivvyCloud uses the location to give contextual information about the Account. Later on this can be viewed as the cloud_org_path Badge associated with each Account.

๐Ÿ“˜

Saving the Organizational Unit ID for later

If you want to only sync Accounts within a particular OU, copy the OU's ID and save for later. See the high-lighted text in the above screenshot.

Next we need to setup all the credentials necessary to onboard Accounts using the Organization.

What Authentication Method is Used?

To authenticate against the Amazon (AWS) API, multiple IAM Roles must be provisioned. IAM Roles can only be defined at the Account level, which is an individual account within a company's Amazon's Organization.

All authentication is done via Amazon's Secure Token Service (STS) with an AssumeRole operation by the caller, an IAM User or ec2 instance Role, to the Role in the target account. There must be a trust relationship between the caller and the Role being assumed.

  • The AssumeRole operation returns a set of temporary session credentials that are used by DivvyCloud to perform harvesting.

  • An Instance Assume Role (AWS) is recommended when deploying to an Amazon environment.

๐Ÿšง

Opt-in Regions

DivvyCloud uses the Global STS endpoint for all STS operations. DivvyCloud includes support for AWS regions with a the "opt-in" classification. This requires an additional step of updating the STS Endpoint configuration to use longer session token in the account with the Caller Identity that will be performing the AssumeRole operation.

To do this, visit the AWS console here and modify the Global Endpoint option to allow larger session tokens to the global endpoint (https://sts.amazonaws.com).

For a guided experience, please see our guide. Configuring AWS

Deployment Recommendations

The manual setup of Roles, Policies, and trust relationships across all Accounts in an Organization can be tedious and error prone.

The recommended pattern for a reliable deployment is to use Amazon's native CloudFormation StackSets. These provide a way to define a set of Roles and Policies and deploy them across all Accounts in the Organization.

For questions on this process refer to the linked AWS documentation, or for additional assistance reach out to us through any of the options outlined on our Getting Support page.

Steps to deploy IAM Roles and Policies in Accounts

Task Specific Roles

DivvyCloud requires that a single Role be created in the master account for harvesting Organization data and a Role in each member account in the AWS Organization for general purpose harvesting.

Master Account Role

DivvyCloud makes the distinction between the task of harvesting information about the Organization and the traditional harvesting of cloud resources within the individual accounts.

Making a separate Role limits the permissions to ones only relevant to the Organization level data plane. Additionally, the organizations:ListTagsForResource endpoint, used for listing tags on Accounts, can only called from the master account.

The permissions for the master account Role are:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:SimulatePrincipalPolicy",
                "organizations:DescribeOrganization",
                "organizations:ListAccountsForParent",
                "organizations:ListOrganizationalUnitsForParent",
                "organizations:ListPolicies",
                "organizations:ListRoots",
                "organizations:ListTagsForResource",
                "organizations:ListTargetsForPolicy"
            ],
            "Resource": "*"
        }
    ]
}

The permissions specified above allow DivvyCloud to list all Account, Account tags, Organizational Units, Service Control Policies (SCPs), and their respective attachments.

With that in hand, DivvyCloud will be able to create an internal configuration for the Accounts and start harvesting with the credential configuration described below.

๐Ÿ“˜

Save Master Account Role Info

Write down the Role ARN, SessionDuration and optionally the ExternalID.

Member Account Roles

โ—๏ธ

Harvesting Roles

All general purpose harvesting Roles must use the same configuration. The form provides a single configuration that all member Accounts in the Organization must adhere to for harvesting to work.

For general purpose harvesting there needs to be a Role in every member Account of the AWS Organization with the exact same name and configuration. The IAM Policies attached to this Role should follow the standard Policy recommendations for harvesting. AWS Standard & Power User Policies

Using the same caller, IAM User with API/Secret key or Instance Role, we perform the STS AssumeRole operation on a Role ARN that we format dynamically with each of the Account Ids that we harvest from the organization.

# ARN pattern
arn:aws:iam::{account_id}:role/{RoleArnSuffix}

# Example after formatting
arn:aws:iam::123456789012:role/DivvyCloudReadOnlyRole

The RoleArnSuffix can be any valid Role name but it must be the same across all Accounts.

Additionally if the user wishes to use an ExternalId on the Role, this too must also be the same across all Accounts.

๐Ÿ“˜

Session Duration

The form allows you the set the requested duration of the temporary STS credentials to 43200 seconds, which is the maximum value that AWS allows. However the actual max value you can request is determined on a per Role basis.

Please set all of the Roles to have the same session duration and use that allowed value in the Duration Seconds form field.

See screenshot below of session duration in AWS console.

AWS Session Duration Example

Establishing Trust Relationships

Now that you have Roles deployed in all Accounts, those Roles must have a policy attached to them that grants an explicit Trust Relationship to a caller identity.

See our guide on using STS AssumeRole to setup trust relationships from the Roles in each member account to the caller identity. That documentation is available here --> Secure Token Service Assume Role (AWS)

The identity that's assuming the Role can be one of two things:

  1. An EC2 Instance Role
  • This is the preferred method when running inside of AWS since it uses the Instance credentials available from the Instance Metadata Service (IMDSv2) which reduces the complexity of creating and managing long term API credentials.
  • If using an Instance Role the role must be attached to the Instance Profile of all Instances of the DivvyCloud installation.

2. IAM User

  • If your DivvyCloud installation is running outside of AWS, you may use a set of Access/Secret API to perform the STS Assume Role operation.
  • To successfully assume the Role, there must be a trust relationship between the User and Role.

๐Ÿ“˜

Using an IAM User with Access/Secret API keys

If you are using an IAM user, store your API keys in a safe location. These will be needed when adding the Organization configuration.

AWS Setup Review

If you setup manually or with a CloudFormation StackSet, at this point the following IAM resources should exist.

Caller Identity that will Assume Roles

  • One EC2 Instance Role with permissions too perform the AssumeRole operation, attached to the instances used in the DivvyCloud install.
    OR
  • One IAM User with a policy to perform the AssumeRole operation with a set of long term credentials.

Other Roles

  • Two Roles in the master Account.
    • One Role with the specific policy for harvesting only Organization data.
    • One Role for standard harvesting (see next bullet).
  • One Role in ALL member accounts for standard harvesting with the exact same RoleName, SessionDuration, and ExternalID configuration.

Add AWS Organization to DivvyCloud

With the IAM Role and User configuration we gathered from the prerequisites in hand:

  1. Log into DivvyCloud with an admin user.
  2. Navigate to the Clouds section and open the "Organizations" tab.

Organizations View

๐Ÿšง

Cloud Organizations are Globally Unique

Note that a Cloud Organization cannot be added multiple times on the same DivvyCloud installation. If you attempt to add the same Organization twice the request will be rejected.

  1. Click 'Add Organization' button on top right corner of card.
  2. Select 'Amazon Web Services' from Cloud Type selection.

Adding an AWS Organization

โ—๏ธ

Note impact to existing AWS accounts already added to DivvyCloud

Adding a Cloud Organization will replace the credentials of associated cloud accounts already in DivvyCloud.

Misconfiguration of the Roles in member accounts will result in gaps in visibility.

  1. Gather the RoleArn, SessionDuration, and ExternalID configuration we saved from the Role created to harvest AWS Organization information. This is not the standard harvesting Role.
  2. Enter the RoleArn, SessionDuration and ExternalID.
  3. Choose a Session Name.
  • This is what will display in CloudTrail logs and is useful for auditing purposes.
  1. Gather configuration for standard harvesting for member accounts.
  • Enter Role name used in ALL accounts. Note description has an example ARN that will update to show what the dynamically formatted ARN will look like.
  1. Choose a Session Name.
  • This is what will display in CloudTrail logs and is useful for auditing purposes.
  • This will be the same for all member accounts.
  1. Optional: If using an IAM User, select the checkbox to enter long term credentials, enter credentials

**ADVANCED OPTIONS

  1. We offer two options for limiting the scope of Account onboarding in the form.

Optional: First is by providing one or more prefixes. Any accounts with names that match those prefixes will be excluded.

Optional: Second, an Organizational Unit ID can be provided and only nested Accounts and OUs will be included. To find the Organizational Unit's ID please reference the screenshot and callout at the beginning of this doc.

  1. Once you've completed all of the fields and details outlined above, click to "Submit form".

๐Ÿ“˜

Expected Validation

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

  • Attempt to perform AssumeRole operation with Instance Role or IAM User 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 "Master Account 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.

Contact [email protected] with questions.

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

โ—๏ธ

Note about Editing

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.

  1. 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 will all member accounts. As noted above, errors in permissions or failure to assume a Role are represented by the cloud status.

Badging of Accounts

Accounts added via an 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.
  • system.cloud_organization:<cloud_org_id>: is associated with all accounts in the Organization.

Badging

Changes to Credential Management

Because all Accounts within the 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 DivvyCloud includes auto badging capabilities. The purpose of auto badging is to create a 1:1 map of AWS account-level tags or GCP project-level labels to Badges in DivvyCloud. This allows Clouds to be scoped to a badge that maps to the account tag.

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 DivvyCloud 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 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โ€™.

Updated 2 months ago

Organizations (AWS)


Suggested Edits are limited on API Reference Pages

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