How to onboard your AWS accounts with the VMware Aria Automation for Secure Clouds API
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 can onboard an AWS account with the API, you need:
- The ID of the AWS account you want to onboard.
- Permissions to to create IAM roles and enable CloudWatch for your AWS account.
- A bash-supported environment (run
bash –versionin a command line terminal). VMware Aria Automation for Secure Clouds scripts for event stream setup work only for bash-supported environments. - An API access token for the VMware Aria Automation for Secure Clouds platform.
- A shell terminal with curl installed or an API development tool capable of making REST API calls, such as Postman.
Obtain credentials from AWS
The AWS credentials you need to onboard your account into VMware Aria Automation for Secure Clouds include the Role ARN and External ID. You can get these credentials by creating an IAM role and assigning it a SecurityAudit Policy that grants VMware Aria Automation for Secure Clouds read-only access to your account.
The following describes how to create an IAM role with the necessary permissions in the AWS console:
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). Copy the external ID for later use.
Select SecurityAudit from AWS's pre-configured policy list. This grants read-only access to your account.
Enter a name for the role, include any optional description or tags, then select Create role.
From the Roles page, locate your new role in the list and select it.
Copy the information under ARN. If you entered your own external ID, you can copy it from the Trust relationships tab if you didn't do so earlier.
With your credentials in hand, you now have everything you need to onboard your AWS account into VMware Aria Automation for Secure Clouds.
Add a single cloud account
To add an individual cloud account, make a cloud-credentials API call, adding the role ARN and external ID to the request body where indicated.
curl -X POST \
https://api.securestate.vmware.com/v1/providers/aws/cloud-credentials/ \
-H 'Authorization: Bearer {access_token}' \
-d '{
"credentialType": "collection",
"provider": "aws",
"properties": [
{
"name": "RoleARN",
"type": "string",
"stringV": "{IAM role ARN}"
},
{
"name": "ExternalID",
"type": "string",
"stringV": "{External ID}"
}
]
}'
A successful response confirms that the credentials were uploaded to the service, and returns a credentialId value. Copy the credentialId for use in the next step.
Response body
{
"credentialId": "{Credential ID}",
"credentialType": "collection",
"provider": "aws",
"properties": [
{
"name": "ExternalId",
"type": "string",
"stringV": "{External ID}"
},
{
"name": "RoleArn",
"type": "string",
"stringV": "{IAM resource name}"
}
],
"eTag": "{e-tag}",
"createdTime": "{timestamp}",
"lastUpdateTime": "{timestamp}"
}
Next, make a call to the bulk-update API to create a cloud account for your AWS account ID and link it with the credentials you just uploaded. The cloudAccountName field accepts a string value of your choice, while cspProjectId can be either default, or another project you would like to add your account under.
Note: The environment and ownerInfo fields are optional, and can be removed from the request if preferred.
curl -X POST \
https://api.securestate.vmware.com/v1/cloud-accounts/bulk-update \
-H 'Authorization: Bearer {access_token}' \
-d '{
"provider": "aws",
"cloudAccountUpdates": [
{
"action": "post",
"cloudAccountName": "{Cloud account name}",
"cspProjectId": "{CSP project ID}",
"environment": "None",
"ownerInfo": {
"email": "{Owner email address}",
"name": "{Owner name}"
},
"properties": [
{
"name": "accountId",
"type": "string",
"stringV": "{AWS account ID}"
}
],
}
],
"relationshipUpdates": [
{
"action": "post",
"cloudAccountId": "{AWS account ID}",
"credentialId": "{Credential ID}"
}
]
}'
A successful response confirms the information you entered, along with general status updates and timestamps.
Response Body
{
"cloudAccountUpdates": [
{
"action": "post",
"cloudAccountId": "{AWS account ID}",
"cloudAccountName": "{AWS account name}",
"cspProjectId": "{CSP Project ID}",
"provider": "aws",
"environment": "{Environment}",
"ownerInfo": {
"email": "{Owner email address}",
"name": "{Owner name}"
},
"accountStatus": {
"value": "{Account status value}",
"lastUpdateTime": "{timestamp}"
},
"rollupStatus": {
"value": "{Rollup status value}",
"lastUpdateTime": "{timestamp}"
},
"properties": [
{
"name": "accountID",
"type": "string",
"stringV": "{AWS Account ID}"
}
],
"eTag": "{e-tag}",
"createdTime": "{timestamp}",
"lastUpdateTime": "{timestamp}"
}
],
"relationshipUpdates": [
{
"action": "post",
"cloudAccountId": "{AWS account ID}",
"credentialId": "{Credential ID}",
"eTag": "{e-tag}",
"createdTime": "{timestamp}",
"lastUpdateTime": "{timestamp}"
}
]
}
Add multiple cloud accounts
VMware Aria Automation for Secure Clouds supports creating multiple cloud accounts in a single API call for situations where you need to onboard a large number of AWS accounts associated with the same AWS Organization.
Note: You must log in to the AWS root account as an administrator IAM user with AdministratorAccess permissions to effectively perform all directions.
To use this feature, you must first create a credential for your AWS organization's root account according the directions for individual account onboarding.
Create a credential for AWS root account
Make a cloud-credentials API call with the ARN and external ID of the AWS root account to upload a credential for it.
curl -X POST \
https://api.securestate.vmware.com/v1/providers/aws/cloud-credentials/ \
-H 'Authorization: Bearer {access_token}' \
-d '{
"credentialType": "collection",
"provider": "aws",
"properties": [
{
"name": "RoleARN",
"type": "string",
"stringV": "{AWS root account ARN}"
},
{
"name": "ExternalID",
"type": "string",
"stringV": "{External ID}"
}
]
}'
Copy the credentialId from the response for use in the next call.
Onboard the root AWS account
Once you have a credential ID, make a bulk-update API call to onboard the root account.
Note: If the root account is already onboarded as an individual account, remove it before following these instructions.
curl -X POST \
https://api.securestate.vmware.com/v1/cloud-accounts/bulk-update \
-H 'Authorization: Bearer {access_token}' \
-d '{
"provider":"aws",
"cloudAccountUpdates":[
{
"provider":"aws",
"cloudAccountId":"{Root account ID}",
"cloudAccountName":"{Root account name}",
"cspProjectId":"default",
"environment":"None",
"ownerInfo":{
"name":"{Owner Name}",
"email":"{Owner email}"
},
"properties":[
{
"name":"AccountId",
"type":"string",
"stringV":"{Root account ID}"
},
{
"name":"IsRoot",
"type":"bool",
"boolV":true
}
],
"action":"post"
}
],
"credentialUpdates":[
],
"relationshipUpdates":[
{
"action":"post",
"cloudAccountId":"{Root account ID}",
"credentialId":"{Root account credential}"
}
]
}'
Create credentials for AWS member accounts
Once the root account is onboarded, make a bulk-update and create credentials for all the member accounts you want to associate with it. You must create a SecurityAudit IAM role to get the necessary information for a successful call.
curl -X POST \
https://api.securestate.vmware.com/v1/cloud-accounts/bulk-update \
-H 'Authorization: Bearer {access_token}' \
-d '{
"provider": "aws",
"cloudAccountUpdates": [],
"credentialUpdates": [
{
"credentialType": "collection",
"properties": [
{
"name": "RoleArn",
"type": "string",
"stringV": "{IAM resource name 1}"
},
{
"name": "ExternalId",
"type": "string",
"stringV": "{External ID 1}"
}
],
"action": "post"
},
{
"credentialType": "collection",
"properties": [
{
"name": "RoleArn",
"type": "string",
"stringV": "{IAM resource name 2}"
},
{
"name": "ExternalId",
"type": "string",
"stringV": "{External ID 2}"
}
],
"action": "post"
}
],
"relationshipUpdates": []
}'
Onboard member AWS accounts
Make another bulk-update API call to associate the AWS account IDs with the credentials you just uploaded. Include the RootCloudAccountId property with each account to indicate their relationship with the root account.
curl -X POST \
https://api.securestate.vmware.com/v1/cloud-accounts/bulk-update \
-H 'Authorization: Bearer {access_token}' \
-d '{
"provider": "aws",
"cloudAccountUpdates": [
{
"action": "post",
"cloudAccountId":"{AWS account ID 1}",
"cloudAccountName": "{AWS account name 1}",
"cspProjectId": "{CSP project ID}",
"environment": "None",
"ownerInfo": {
"email": "{Owner email address}",
"name": "{Owner name}"
},
"properties": [
{
"name": "accountId",
"type": "string",
"stringV": "{AWS account ID 1}"
},
{
"name": "RootCloudAccountId",
"type": "string",
"stringV": "{AWS root account ID}"
}
],
},
{
"action": "post",
"cloudAccountId":"{AWS account ID 2}",
"cloudAccountName": "{AWS account name 2}",
"cspProjectId": "{CSP project ID}",
"properties": [
{
"name": "accountId",
"type": "string",
"stringV": "{AWS account ID 2}"
},
{
"name": "RootCloudAccountId",
"type": "string",
"stringV": "{AWS root account ID}"
}
],
"environment": "None",
"ownerInfo": {
"email": "{Owner email address}",
"name": "{Owner name}"
}
}
],
"relationshipUpdates": [
{
"action": "post",
"cloudAccountId": "{AWS account ID 1}",
"credentialId": "{AWS account credential ID 1}"
},
{
"action": "post",
"cloudAccountId": "{AWS account ID 2}",
"credentialId": "{AWS account credential ID 2}"
}
]
}'
This example onboards 2 accounts, but you can include up to 100 AWS individual accounts and credentials in one call. If you need to onboard more than 100 AWS accounts, you can submit an additional call.
Associate pre-existing AWS accounts with a root account
If you have an AWS account you added prior to adding the root account, you can take the following actions to link them together.
First, retrieve the AWS account information with a GET request.
curl -X GET \
https://api.securestate.vmware.com/v1/cloud-accounts/{Cloud Account ID} \
-H 'Authorization: Bearer {access_token}' \
-d '{}'
Copy the appropriate information into a PUT request and add the RootCloudAccountId as follows.
curl -X PUT \
https://api.securestate.vmware.com/v1/cloud-accounts/{Cloud Account ID} \
-H 'Authorization: Bearer {access_token}' \
-d '{
"cloudAccountId": "{AWS account ID}",
"cloudAccountName": "{AWS account name}",
"cspProjectId": "{CSP project ID}",
"provider": "aws",
"environment":"{Environment}",
"ownerInfo":{
"name":"{Owner name}",
"email":"{Owner email address}"
}
"properties": [
{
"name": "accountId",
"type": "string",
"stringV": "{AWS account ID}"
},
{
"name": "AccountType",
"type": "string",
"stringV": "Commercial"
},
{
"name": "RootCloudAccountId",
"type": "string",
"stringV": "{AWS root account ID}"
}
]
}'
A successful response confirms the information you entered, along with general status updates and timestamps.
Event stream setup
You can set up the event stream with a shell script hosted on the VMware Aria Automation for Secure Clouds portal. You need to have CloudTrail to be enabled for the script to run, details for which can be found at the AWS CloudTrail Documentation.
The shell script performs several actions:
- Enables CloudTrail in each region.
- Creates a CloudWatch event rule in each region for AWS API actions.
- Creates an AWS Simple Notification Service (SNS) topic to receive the events.
- Subscribes a VMware Aria Automation for Secure Clouds queue to the SNS topic.
Run this command to download the 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 <AWS Account 1> <AWS Account 2> <AWS Account 3>
Note: You can also run this script in the Azure CLI on a local machine. If you do, ensure that you create the appropriate resource group privileges.
For more information on the CloudWatch rule the shell script creates or removing the event stream, see the event stream Configuration and resource details in the Getting Started guide.
To verify the event stream is active, make the following call to the cloud-accounts API.
curl -X GET \
https://api.securestate.vmware.com/v1/providers/{provider}/cloud-accounts/{cloud account ID} \
-H 'Authorization: Bearer {access_token}'
Look for the eventStreamStatus object in the response and verify the value is connected:
"eventStreamStatus": {
"value": "connected",
"lastUpdateTime": "2022-06-27T21:25:44.000Z"
}
While the event stream is active, you should see real-time updates in the service for any changes in your cloud account that trigger or resolve a violation.
