How to onboard your AWS accounts in VMware Aria Automation for Secure Clouds

VMware Aria Automation for Secure Clouds uses a read-only cloud account role to scan the AWS configurations to create an interconnected cloud security model of your environment. The service also uses a CloudWatch logs event stream of API calls from AWS to trigger near real-time notifications of configuration violations. For AWS accounts, the events are generated by setting up an event rule in the CloudWatch service. A shell script is available to simplify the setup of the CloudWatch event stream.

Before you start

Before you set up an AWS cloud account, make sure you have the following requirements in place:

Know the ID of any AWS accounts you want to onboard.
Confirm access to the account in your AWS console.
Have permissions to create an IAM role via AWS console.
Have permissions to enable CloudWatch for your account.
Ensure you have bash configured in your environment (run bash –version in a command line terminal). The event stream setup scripts only only work in bash-supported environments.

Configure your AWS console

To onboard an AWS account, you must create an IAM role with an attached SecurityAudit Policy (granting read-only rights) for that account. You can also perform this action during the onboarding process.

From the AWS Management Console, select the IAM portal.
Select Roles in the sidebar.
Select Create role.
Make the following selections to add the VMware Aria Automation for Secure Clouds AWS account as a trusted entity. Contact customer service if you don't have the account ID.

Note
The External ID must match your Organization ID in VMware Aria Automation for Secure Clouds.
Select SecurityAudit from the AWS pre-configured policy list. This grants read-only access to your account.
Enter a name for the role, include any optional description or tags.
Click Create role.
From the Roles page, locate your new role in the list and select it.
Copy the ARN and External ID for use in the connect step while onboarding. The ARN is available under the Summary section, and the External ID can be found under the Trust relationships tab.

If you're onboarding multiple AWS accounts, you only need to perform this action for the AWS root account. VMware Aria Automation for Secure Clouds provides an onboarding script that automates this process for subsequent member AWS accounts.

Add inline policy for AWS Budgets and Cost Explorer (optional)

If you're using the AWS Budgets or Cost Explorer services and want to monitor these resources, you must add an inline policy to your IAM role with the necessary permissions.

To monitor resources in the AWS Budget service, add these permissions to an inline policy:

budgets:DescribeBudgetAction
budgets:DescribeBudgetActionsForBudget
budgets:ViewBudget

To monitor resources in the AWS Cost Explorer service, add these permissions to an inline policy:

ce:DescribeCostCategoryDefinition
ce:GetAnomalyMonitors
ce:GetAnomalySubscriptions
ce:GetCostCategories
ce:ListTagsForResource
ce:ListCostCategoryDefinitions

Add a single cloud account

Use this process when you want to onboard an individual AWS account into VMware Aria Automation for Secure Clouds. To begin the onboarding process:

Navigate to Settings > Cloud accounts.
Click the Add Account button.
Make the following selections:
- Provider - AWS.
- Onboarding Method - Single account.
- Account Type - Commercial.
Click Add.

Step one - General information

For this step, you must enter information needed to identify your cloud account:

Account name - Pick a name for your account in the service. You can enter any name as long as it's not already used by another cloud account.
Account ID - This should be the ID for for your AWS account.
Account type - Select Commercial if this is not a government account.
Project - If there is an existing project you want to add the cloud account to, select it here. Otherwise, you can leave it as the default value.
Environment - Select the appropriate environment for this account, if your organization makes use of them. A blank entry defaults to "None".
Account owner - Enter the name and email of the person or team responsible for the account. This field is optional, but it's good to have this information available when determining who is responsible for resolving a violation.
Account Tag - Add any tags you want to associate with this account. You can select from any tags assigned to previously added cloud accounts, or enter a new one.

When finished, click Next.

Step two - Account details

If you have already created an IAM role for your AWS account according to directions, enter the IAM Role ARN where prompted to establish a read-only connection between your AWS account and VMware Aria Automation for Secure Clouds.

If you have not created an IAM role in your AWS console, follow the instructions onscreen or in this guide to set one up.

Once you've entered your credentials, click Next to proceed.

Step three - Inbound integrations

Next, you can decide which inbound integrations to enable on this cloud account.

For AWS, the available integrations in this step are Amazon GuardDuty and Amazon Inspector, both of which import additional findings from the respective AWS service into VMware Aria Automation for Secure Clouds.

Note
Integrated services must be active on an AWS account for the integration to work. Choosing to enable the integration in this step does not activate the service in AWS, which must be done separately from the AWS management console.

After you make your selections, click Next.

Step four - Event stream

The final section details how to activate event monitoring for your account to receive real-time updates for security violations. Follow the onscreen instructions or see the event stream setup instructions in this article, then click Finish when done.

If you encounter any issues when trying to onboard a single AWS account, refer to the troubleshooting section of this document.

Note
Onboarding at the AWS Organization level is recommended over individual onboarding. If you have a large number of individual cloud accounts, follow the migration instructions to associate them with a root account.

Add multiple cloud accounts

Use this process when you want to onboard a group of AWS accounts into VMware Aria Automation for Secure Clouds at once. Be aware of the following:

All AWS accounts must belong to the same AWS organization.
You must have permissions to create an IAM role with the SecurityAudit Policy attached in the AWS organization root account per configuration instructions. This is necessary for VMware Aria Automation for Secure Clouds to scan information from all your member accounts when onboarding.
The IAM role used by the root account to access member account resources must be identical for all member accounts. This role is named OrganizationAccountAccessRole by default when you create a new member account. If you changed it, ensure it's named consistently across all member accounts.
You can onboard up to 100 AWS accounts in a single action, including the root account.
After initial onboarding, you can use the continuous onboarding feature to onboard more AWS accounts.

When you're ready to begin, do the following:

Navigate to Settings > Cloud accounts.
Click the Add Account button.
Make the following selections:
- Provider - AWS.
- Onboarding Method - Organization (Member Accounts).
Click Add.

Step one - General information

For this step, you must enter information needed to identify your root cloud account:

Account name - Pick a name for your account in the service. You can enter any name as long as it's not already used by another cloud account.
Account ID - This should be the ID for your root AWS account.
Account type - Select Commercial if this is not a government account.
Project - If there is an existing project you want to add the cloud account to, select it here. Otherwise, you can leave it as the default value.
Environment - Select the appropriate environment for this account, if your organization makes use of them. A blank entry defaults to "None".
Account owner - Enter the name and email of the person or team responsible for the account. This field is optional, but it's good to have this information available when determining who is responsible for resolving a violation.
Account Tag - Add any tags you want to associate with this account. You can select from any tags assigned to previously added cloud accounts, or enter a new one.

When finished, click Next.

Step two - Root account details

If you have already created an IAM role for your AWS root account according to directions, enter the IAM Role ARN where prompted to establish a read-only connection between your AWS account and VMware Aria Automation for Secure Clouds.

If you have not created an IAM role in your AWS console, follow the instructions onscreen or in this guide to set one up.

Once you've entered your credentials, click Next to proceed.

Step three - Accounts selection

The client now displays a list of all the member AWS accounts associated with the root AWS account ID you entered in the first screen. Select the accounts you would like to onboard and click Next.

Note
If you have existing member accounts under your organization that were onboarded through the single cloud account workflow, you can select them here to auto-link with the root account.

Step four - Accounts configuration

Run this script in your AWS CloudShell or AWS CLI environment to create read-only IAM roles in all your selected AWS member accounts:

curl https://api.securestate.vmware.com/download/onboarding/aws/bulk/vss_aws_bulk_account_assume_role.sh --output vss_aws_bulk_account_assume_role.sh && sh vss_aws_bulk_account_assume_role.sh <account ID 1>, <external ID 1>, <account ID 2>, <external ID 2>...

The script uses the AWS root account's permission to assume the OrganizationAccountAccessRole IAM role in member accounts to create the necessary roles and trail logs. The process may take a few minutes to complete depending on the number of member accounts you're onboarding.

Note
If OrganizationAccountAccessRole doesn't exist, the script fails. See the relevant troubleshooting section for steps to resolve this issue.

While the script runs, you can review your AWS member accounts and edit information for the name, project, environment, owner, and tag you want each to have in VMware Aria Automation for Secure Clouds.

After the script is finished running and you've review all information, click Next.

Step five - Inbound integrations

Next, you can decide which inbound integrations to enable for your cloud accounts.

Note
Integrated services must be active on an AWS account for the integration to work. Choosing to enable the integration in this step does not activate the service in AWS, which must be done separately from the AWS management console.

After you make your selections, click Next.

Step six - Event stream

If you encounter any issues when trying to onboard a single AWS account, refer to the troubleshooting section of this document.

Continuous onboarding

After onboarding your first batch of AWS accounts, you can use VMware Aria Automation for Secure Clouds's continuous onboarding feature to easily onboard any additional AWS accounts under the same root.

Navigate to Settings > Cloud accounts.
Locate one of the AWS cloud accounts you created and click the link in the Account Name field.
Click the Manage link in the Credential field.

This should take you to the Manage AWS Credential page, which features two lists. The first list contains AWS accounts that have already been onboarded, while the second list has accounts that are detected but not yet onboarded. You can select up to 100 accounts from the second list and click Add Account to begin onboarding them.

Migrate single cloud accounts to an AWS Organization

It's a best practice to onboard your AWS accounts at the AWS Organization level to leverage account discovery and bulk management features. If you have a large number of AWS accounts that were onboarded individually, you can re-onboard them from your AWS Organization with the following:

Onboard your AWS Organization's root account according to the bulk onboarding instructions.

Note
If the root account has already been onboarded individually, delete it and onboard it again.
Follow the rest of the bulk onboarding instructions. During step 3, you can select the member accounts that were onboarded individually. Complete the onboarding process to associate them with the root account.
To confirm your member accounts are now associated with the root account, go to Settings > Cloud accounts and locate the root account.
Select the root account to access the details page, then select Manage.
Verify all the member accounts you selected during onboarding are now listed under Onboarded accounts.

Associating your individual AWS accounts with a root account in this way provides maximum visibility into your security posture and reduces risk for all cloud accounts going forward.

Add an AWS GovCloud account

Adding an AWS GovCloud account is different from adding a commercial account in several ways, primarily in how you set up credential access to VMware Aria Automation for Secure Clouds and account inventory capabilities.

Obtain AWS GovCloud credentials

The following explains how to get the required credentials for onboarding an AWS GovCloud account into VMware Aria Automation for Secure Clouds:

Log in to your AWS GovCloud console, then navigate to the IAM service.
From the sidebar, select Users.
Click Add users.
Enter a user name (Example: “SecureStateUser”).
Select Access key - Programmatic access for the user’s access type.
Click Next: Permissions.
Choose the Attach existing policies directly option and search for the SecurityAudit policy.
Select the SecurityAudit policy and click Next: Tags.
Click Next: Review if you have no tags to add.
Review your choices, then click Create user.
Copy your Access Key ID and Secret access key for use in the next section.

Create an AWS GovCloud cloud account

The following explains how to create a cloud account in VMware Aria Automation for Secure Clouds and associate it to your AWS GovCloud resources.

Navigate to Settings > Cloud accounts.
Click the Add Account button.
Make the following selections:
- Provider - AWS.
- Onboarding Method - Single account.
- Account Type - Government.
Click Add.

Step one - General information

Enter the following information on the first page and click Next when finished:

Account name - Pick a name for your account in the service. You can enter any name as long as it's not already used by another cloud account.
Account ID - This should be the ID for your AWS account.
Account type - Select Government.
Project - If there is an existing project you want to add the cloud account to, select it here (Otherwise, you can leave it as the default value).
Environment - Select the appropriate environment for this account, if your organization makes use of them. A blank entry defaults to "None".
Account owner - Enter the name and email of the person or team responsible for the account. This field is optional, but it's good to have this information available when determining who is responsible for resolving a violation.
Account Tag - Add any tags you want to associate with this account. You can select from any tags assigned to previously added cloud accounts, or enter a new one.

Step two - Account details

Enter the Access Key ID and Secret access key you copied from the AWS portal where prompted, then click Finish.

Your AWS GovCloud resources are now monitored by VMware Aria Automation for Secure Clouds. Please note that an event stream is not available for GovCloud accounts, so findings are updated at regular 12 hour intervals for your account inventory instead.

Turn on event stream

VMware Aria Automation for Secure Clouds uses event streams to provide real-time updates about security findings for your monitored cloud accounts. Configuring an event stream for your cloud account is necessary to get information about misconfigurations and other vulnerabilities immediately, otherwise your information is only as accurate as your most recent system scan.

The event stream can be set up with a shell script available from the service portal. You can run the script in the AWS CloudShell or CLI.

The shell script performs several actions:

Checks for an active CloudTrail in each region.
Creates a CloudWatch event rule in each active CloudTrail region for AWS API actions.
Creates a AWS Simple Notification Service (SNS) topic to receive the events.
Subscribes a VMware Aria Automation for Secure Clouds queue to the SNS topic.

The script must be run from a terminal where access to the target AWS account is available through an environment variable or by using the --profile option. After checking for a CloudTrail in each region, the script runs a CloudFormation template anywhere a CloudTrail is found. The CloudFormation template is referenced in the shell script and can be found at https://s3.amazonaws.com/cloudcoreo-files/devtime/devtime_cfn.yml.

Due to the way the script runs, delivery notifications are not logged for SNS. This does produce a finding for the cloudcoreo-events SNS topic in each region it's deployed in.

An SNS topic finding for cloudcoreo-events

You can remove these findings by either using a suppression policy for the resource, or disabling the rule entirely for your organization.

IMPORTANT
If you send all your cloud account logs to a central account, you do not need to run the script in every account you add to the service. You should only need to run the script once in the account that's receiving the logs.

Setup with AWS CloudShell

Before running the setup script, make sure CloudTrail is enabled on your cloud account.

Note
Do not create more than one CloudTrail for the event stream.

From your cloud account, open AWS CloudShell and run this command:

curl https://api.securestate.vmware.com/download/onboarding/aws/bulk/vss_aws_bulk_account_onboarding.sh --output vss_aws_bulk_account_onboarding.sh && sh vss_aws_bulk_account_onboarding.sh <account ID>

Setup with AWS CLI

Before downloading the setup script, ensure these prerequisites are in place:

Set the following IAM managed policy for your user in the AWS console so you can export your access key and secret access ID. You may remove it after setup is complete.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sns:*",
        "cloudtrail:*",
        "cloudformation:*",
        "events:*"
      ],
      "Resource": "*"
    }
  ]
}

Enable CloudTrail on your cloud account.

Note
Do not create more than one CloudTrail for the event stream.
Install the AWS CLI.
Export your environment variables, specifically the access key and secret access key.

After confirming the prerequisites, enter this command to download and run the event stream setup shell script:

curl https://api.securestate.vmware.com/download/onboarding/aws/bulk/vss_aws_bulk_account_onboarding.sh --output vss_aws_bulk_account_onboarding.sh && sh vss_aws_bulk_account_onboarding.sh <account ID>

Alternatively, you may invoke the script with the profile option:

sh ./setup-coreo-devtime.sh --profile profile_name

Configuration and resource details

You can configure CloudWatch event rules manually or through some other deployment path. The following applies for individual accounts that are sending their own (or forwarded from a different account) CloudWatch events. A CloudWatch event rule is required in each region. The event source is built from this custom event pattern:

{
    "detail-type": [
    "AWS API Call via CloudTrail"
    ],
    "detail": {
        "eventSource": [
        "acm.amazonaws.com",
        "autoscaling.amazonaws.com",
        "cloudformation.amazonaws.com",
        "cloudfront.amazonaws.com",
        "cloudhsm.amazonaws.com",
        "cloudtrail.amazonaws.com",
        "directconnect.amazonaws.com",
        "dynamodb.amazonaws.com",
        "ec2.amazonaws.com",
        "elasticache.amazonaws.com",
        "elasticloadbalancing.amazonaws.com",
        "es.amazonaws.com",
        "iam.amazonaws.com",
        "kms.amazonaws.com",
        "rds.amazonaws.com",
        "redshift.amazonaws.com",
        "route53.amazonaws.com",
        "s3.amazonaws.com",
        "ses.amazonaws.com",
        "sqs.amazonaws.com",
        "waf.amazonaws.com"
        ]
    }
}

A target is added to the rule for events to invoke. VMware Aria Automation for Secure Clouds uses an SNS topic as the target, with the input as the default matched event. The SNS topic name must be set to “cloudcoreo-events” when configuring the event stream. The topic has a subscription that uses Amazon SQS protocol. The SNS topic is created in every region, and all SNS topics have the same subscription endpoint:

arn:aws:sqs:us-west-2:<account-id>:cloudcoreo-events-queue

Turn off event stream

To remove the event stream, perform these steps:

From the dashboard, navigate to Settings > Cloud accounts.
Select your AWS cloud account.
On the cloud account details page, select Turn-Off under event stream and follow the instructions.

Alternatively, you can use the vss event remove command in the AWS CLI, or remove the event stream manually through an existing deployment path.

Troubleshooting

Review this section for any errors you encounter when trying to onboard your cloud accounts.

Invalid access credentials

If your AWS cloud accounts are displaying this error in the Settings > Cloud accounts list and were previously in a healthy state, go through these steps to resolve the issue.

Go to the account details page and click Re-validate.
If you're still seeing an error, check the IAM role in your AWS portal and verify the following:
- The IAM role still exists and matches the ARN and external ID values in VMware Aria Automation for Secure Clouds.
- The IAM role has the SecurityAudit policy attached.
If the IAM role is gone, create a new role according to the IAM authentication instructions and update the credentials in VMware Aria Automation for Secure Clouds by going back to the account details page and clicking on Change. You can also try this step if the IAM role is current, but you're still getting a credential error.

If you're unable to resolve the error after creating and adding new credentials, contact support for further assistance.

InvalidRole error

If you receive an "InvalidRole" error while onboarding your AWS cloud account, the result is likely a mismatch between the external ID you entered in VMware Aria Automation for Secure Clouds and the one in your account's trust relationship on AWS.

To verify these two values, follow these steps:

In the VMware Aria Automation for Secure Clouds dashboard, go to the cloud account information and click on Change.
Note down or copy the value in the external ID field.
Verify the external ID in AWS matches what you wrote down. Update one or the other so that both values are the same.

OrganizationAccountAccessRole does not exist

When onboarding multiple member accounts from an AWS Organization, VMware Aria Automation for Secure Clouds supplies a script to create a required read-only IAM role for each member account. The script assumes a typical organization structure where the root account has administrator permissions on each member account through the OrganizationAccountAccessRole IAM role.

AWS organization diagram where root account accesses member accounts through the OrganizationAccountAccess role

If OrganizationAccountAccessRole isn't present in a member account, the script can't function correctly. This usually happens when you've chosen a custom name for the IAM role AWS automatically provisions for administrative privileges when adding member accounts.

There are two ways to resolve this issue. Choose the one you prefer:

Edit the script to include a custom IAM role

If you use a custom IAM role to provide administrator access to your member account resources, you can add the role name as a third parameter to the IAM setup script provided in step 4 of the AWS Organization onboarding procedure.

curl https://api.securestate.vmware.com/download/onboarding/aws/bulk/vss_aws_bulk_account_assume_role.sh --output vss_aws_bulk_account_assume_role.sh && sh vss_aws_bulk_account_assume_role.sh <account ID 1>, <external ID 1>, <custom role name>, <account ID 2>, <external ID 2>, <custom role name>....

This prompts the script to override the default behavior of accessing OrganizationAccountAccessRole and uses your custom role instead.

Note
For the script to function correctly, the custom role must have AdministratorAccess assigned as a permission policy.

Create OrganizationAccountAccessRole in your member accounts

If OrganizationAccountAccessRole doesn't exist, you can follow the AWS instructions to create it in each of your member accounts. You can use a CloudFormation template to automate this action across a large number of member accounts.