API Onboarding Guide

This content has moved and will no longer be updated. Please go to https://docs.vmware.com/en/CloudHealth-Secure-State/ for the latest version. Please see the latest What's new for the more details about the move.

Last updated on June 21, 2022

Overview

CloudHealth Secure State (CHSS) provides the industry-leading multicloud security and compliance monitoring platform, enabling customers to detect and remediate security findings in real-time. This tutorial shows you how to onboard your accounts with the Cloud Accounts Service API as an alternative to the UI-based onboarding instructions. API-based onboarding is available for all cloud providers supported by Secure State (AWS, Azure, and GCP).

If you prefer to onboard your accounts through the Secure State UI, refer to the Getting Started page.

You need an access token for the Secure State API to follow these instructions. See the API Getting Started page if you don't have one.


AWS Cloud Account Onboarding

Prerequisites

Before you can onboard an AWS account with the API, you need:

  • Your AWS account ID.

  • Your AWS account's IAM role Amazon Resource Name (ARN).

  • Your AWS account's IAM role external ID.

  • Permissions to to create IAM roles and enable CloudWatch for your cloud account.

  • A bash-supported environment (run bash –version in a command line terminal). Secure State scripts for event stream setup work only for bash-supported environments.

Step One - Upload Cloud Account Credentials

Use this command to create a credential for your AWS account and upload it to Secure State.

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 the information you entered and returns the credentialId. Copy the value in this field 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}" }

Step Two - Onboard with the Bulk Update API

Use this command to add your AWS account to Secure State and link it with the previously uploaded credentials. The value of cspProjectId can be either "default" or another CSP Project ID you would like to add your account under.

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": "{AWS account name 1}", "cspProjectId": "{CSP project ID}", "properties": [ { "name": "accountId", "type": "string", "stringV": "{AWS account ID 1}" } ] }, { "action": "post", "cloudAccountName": "{AWS account name 2}", "cspProjectId": "{CSP project ID}", "properties": [ { "name": "accountId", "type": "string", "stringV": "{AWS account ID 2}" } ] }, ... ], "relationshipUpdates": [ { "action": "post", "cloudAccountId": "{AWS account ID 1}", "credentialId": "{Credential ID 1}" }, { "action": "post", "cloudAccountId": "{AWS account ID 2}", "credentialId": "{Credential ID 2}" }, ... ] }'

You can use the bulk update API to upload single or multiple AWS accounts, as seen in the request example. While there is no limit to the accounts and credential you can add to the cloudAccountUpdates and relationshipUpdates, AWS does require unique credentials for every account you add.

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", "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}" } ... ] }

Step Three - Event Stream Setup

You can set up the event stream with a shell script hosted on the Secure State 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 Secure State queue to the SNS topic. 

Run this command to download the script.

curl https://app.securestate.vmware.com/downloads/setup-coreo-devtime.sh --output setup-coreo-devtime.sh

If you're using environment variables with the script, run this command:

export AWS_ACCESS_KEY_ID=YOUR_AWS_ACCESS_KEY_ID export AWS_SECRET_ACCESS_KEY=YOUR_AWS_SECRET_ACCESS_KEY sh ./setup-coreo-devtime.sh

You can also invoke the script with the profile option:

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

For more information on the CloudWatch rule the shell script creates or removing the event stream, see Cloud Account Setup for AWS in the Getting Started page.

To verify the event stream is active, follow these steps:

  1. From the CloudHealth Secure State dashboard, navigate to Settings > Cloud accounts.

  2. Locate your cloud account in the list, filtering as necessary.

  3. If the Status field displays a green checkmark, then the event stream is active for your account.

  4. You can click on the Account Name to see additional details regarding event stream status and cloud account metadata.

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.


Azure Cloud Account Onboarding

Prerequisites

Before you can onboard a cloud account for Azure with the API, you need:

  • Your Azure subscription ID.

  • An existing application registration for Secure State (details in the Azure section of the Getting Started page).

  • The Azure Active Directory client application ID, tenant ID, and client secret for the Secure State application.

Step One - Upload Cloud Account Credentials

Use this command to create a credential for your Azure subscription and upload it to Secure State.

curl -X POST \ https://api.securestate.vmware.com/v1/providers/azure/cloud-credentials/ \ -H 'Authorization: Bearer {access_token}' \ -d '{ "credentialType": "collection", "provider": "azure", "properties": [ { "name": "ApplicationId", "type": "string", "stringV": "{Client application ID}" }, { "name": "ApplicationKey", "type": "string", "stringV": "{Client secret}" }, { "name": "DirectoryId", "type": "string", "stringV": "{Tenant ID}" } ] }' A successful response confirms the information you entered and returns the credentialId. Copy the value in this field for use in the next step.

Step Two - Onboard with the Bulk Update API

Use this command to add your Azure subscription to Secure State and link it with the previously uploaded credentials. The value of cspProjectId can be either "default" or another CSP Project ID you would like to add this cloud account under.

curl -X POST \ https://api.securestate.vmware.com/v1/cloud-accounts/bulk-update \ -H 'Authorization: Bearer {access_token}' \ -d '{ "provider": "azure", "cloudAccountUpdates": [ { "action": "post", "cloudAccountName": "{Azure subscription name 1}", "cspProjectId": "{CSP project ID}", "properties": [ { "name": "subscriptionId", "type": "string", "stringV": "{Azure subscription ID 1}" }, { "name": "AccountType", "type": "string", "stringV": "<Commercial or Government>" } ] }, { "action": "post", "cloudAccountName": "{Azure subscription name 2}", "cspProjectId": "{CSP project ID}", "properties": [ { "name": "subscriptionId", "type": "string", "stringV": "{Azure subscription ID 2}" }, { "name": "AccountType", "type": "string", "stringV": "<Commercial or Government>" } ] }, ... ], "relationshipUpdates": [ { "action": "post", "cloudAccountId": "{Azure subscription ID 1}", "credentialId": "{Credential ID}" }, { "action": "post", "cloudAccountId": "{Azure subscription ID 2}", "credentialId": "{Credential ID}" }, ... ] }'

Note: If the AccountType property isn't included, the cloud account onboards as a commercial type into the service by default.

You can use the bulk update API to upload single or multiple Azure subscriptions, as seen in the request example. You can add as many subscriptions and credentials as necessary to the cloudAccountUpdates and relationshipUpdates objects, though Azure does let you share a single credential across multiple subscriptions if desired.

A successful response confirms the information you entered, along with general account status and timestamps.

Response Body

{ "cloudAccountUpdates": [ { "action": "post", "cloudAccountId": "{Azure subscription ID}", "cloudAccountName": "{Azure subscription name}", "cspProjectId": "{CSP Project ID}", "provider": "azure", "accountStatus": { "value": "{Account status value}", "lastUpdateTime": "{timestamp}" }, "rollupStatus": { "value": "{Rollup status value}", "lastUpdateTime": "{timestamp}" }, "properties": [ { "name": "subscriptionId", "type": "string", "stringV": "{Azure subscription ID}" } ... ], "eTag": "{e-tag}", "createdTime": "{timestamp}", "lastUpdateTime": "{timestamp}" } ... ], "relationshipUpdates": [ { "action": "post", "cloudAccountId": "{Azure subscription ID}", "credentialId": "{Credential ID}", "eTag": "{e-tag}", "createdTime": "{timestamp}", "lastUpdateTime": "{timestamp}" } ... ] }

Step Three - Azure Role Assignment

Follow these directions in your Azure portal to complete the permission needs for your application registration to communicate with the service.

  1. From your Azure console, navigate to the Subscriptions page, select your subscription, then select Access control (IAM).

  2. Select Add > Add role assignment.

  3. Search for and select the Reader role, then select Next.

  4. Click Select members, search for the application you created, then click Select.

  5. Click Review + assign, confirm your assignment, then click Review + assign again.

  6. Verify the role is assigned by going to Access control (IAM) > Role assignments and searching for your application.

Step Four - Event Stream Setup

CloudHealth Secure State uses event streams through Azure Activity logs to provide real-time inspection of changes and to dynamically update the cloud infrastructure model. Enter this command in the Azure Cloud Shell to download and run the event stream setup shell script:

curl https://app.securestate.vmware.com/downloads/setup-azure-coreo-devtime.sh --output setup-azure-coreo-devtime.sh && curl https://app.securestate.vmware.com/downloads/azure_webhook_alert.json --output azure_webhook_alert.json && curl https://app.securestate.vmware.com/downloads/azure_webhook_action.json --output azure_webhook_action.json && /bin/bash setup-azure-coreo-devtime.sh -s <Your_Subscription_ID> -a azure_webhook_action.json -f azure_webhook_alert.json -w https://r62g0jx9a9.execute-api.us-west-2.amazonaws.com/LATEST/

On successful execution of this command, the Azure subscription is configured to send activity log events to Secure State. To verify the event stream is active, follow these steps:

  1. From the CloudHealth Secure State dashboard, navigate to Settings > Cloud accounts.

  2. Locate your cloud account in the list, filtering as necessary.

  3. If the Status field displays a green checkmark, then the event stream is active for your account.

  4. You can click on the Account Name to see additional details regarding event stream status and cloud account metadata.

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.


GCP Cloud Account Onboarding

Prerequisites

Before you can onboard a GCP account with the API, you need:

  • To complete all instructions to APIs per the GCP section of the Getting Started page.

  • To complete all instructions related to creating an organization or project-level Service Account per the GCP section of the Getting Started page.

  • Your GCP project ID.

  • Your GCP Service Account email.

  • Your GCP Service Account key.

Your GCP Service Account email and key should be created when you complete the instructions for creating a Service Account in the Getting Started page.

Step One - Discover GCP Projects

Open a shell terminal and navigate to where you saved the GCP Service Account key. If you're on a Unix-based OS, use this command to create a Base 64 encoding from the key.

base64 -i vmw-secure-state-sa-key.json -o vmw-secure-state-sa-key-encoded.txt

If you're performing this step in GCP cloud shell, use this command instead.

cat <filename> | base64 -w 0

Once you have the encoded key, use this command to invoke the GCP Discovery API and upload your Service Account the Secure State.

curl -X POST \ https://api.securestate.vmware.com/v1/cloud-accounts/gcp-discovery-task \ -H 'Authorization: Bearer {access_token}' \ -d '{ "serviceAccountKey": "{base64_encoded_service_account}" }'

A successful response should list all GCP Projects associated with the Service Account.

Response Body

{ "projects": [ { "creationTime": {timestamp}, "tags": { {GCP project tag 1} {GCP project tag 2} {GCP project tag 3} ... }, "lifecycleState": "{status}", "name": "{Cloud account name}", "projectId": "{GCP project ID}", "projectNumber": "{GCP project number}" } ] }

If you don't see certain GCP Projects, make sure the Service Account permissions have been configured to access them and submit another request until you verify all projects you want Secure State to monitor are part of the response.

Step Two - Upload Credentials

The GCP Service Account acts as a credential for monitoring GCP Projects by Secure State. Use this command to upload the Service Account to Secure State and get a credential ID.

curl -X POST \ https://api.securestate.vmware.com/v1/providers/gcp/cloud-credentials/ \ -H 'Authorization: Bearer {access_token}' \ -d '{ "credentialType": "collection", "provider": "gcp", "properties": [ { "name": "ServiceAccountEmail", "type": "string", "stringV": "{GCP Service Account email}" }, { "name": "ServiceAccountKey", "type": "string", "stringV": "{Base 64 encoded Service Account key}" } ] }'

A successful response confirms the information you entered and returns the credentialId. Copy the value in this field for use in the next step.

Response Body

{ "credentialId": "{Credential ID}", "credentialType": "collection", "provider": "gcp", "properties": [ { "name": "ServiceAccountEmail", "type": "string", "stringV": "{GCP Service Account email}" } ], "eTag": "{e-tag}", "createdTime": "{timestamp}", "lastUpdateTime": "{timestamp}" }

Step 3 - Onboard with the Bulk Update API

Use this command to add your GCP project to Secure State and link it with the previously uploaded credentials. The value of cspProjectId can be either "default" or another CSP Project ID you would like to add the GCP project to.

curl -X POST \ https://api.securestate.vmware.com/v1/cloud-accounts/bulk-update \ -H 'Authorization: Bearer {access_token}' \ -d '{ "provider": "gcp", "cloudAccountUpdates": [ { "action": "post", "cloudAccountName": "{GCP project name 1}", "cspProjectId": "{CSP project ID}", "properties": [ { "name": "projectId", "type": "string", "stringV": "{GCP project ID 1}" } ] }, { "action": "post", "cloudAccountName": "{GCP project name 2}", "cspProjectId": "{CSP project ID}", "properties": [ { "name": "projectId", "type": "string", "stringV": "{GCP project ID 2}" } ] }, ... ], "relationshipUpdates": [ { "action": "post", "cloudAccountId": "{GCP project ID 1}", "credentialId": "{Credential ID}" }, { "action": "post", "cloudAccountId": "{GCP project ID 2}", "credentialId": "{Credential ID}" }, ... ] }'

You can use the bulk update API to upload single or multiple GCP projects, as seen in the request example. You can add as many projects and credentials as necessary to the cloudAccountUpdates and relationshipUpdates objects, though GCP does let you share a single credential across multiple projects if desired.

A successful response confirms the information you entered, along with general status updates and timestamps. 

Step Four - Event Stream Setup

Run this script to set up an event stream for the cloud accounts you've added.

curl https://gcp.events.securestate.vmware.com/scripts/gcp-eventstream/setup-securestate-events.sh -o setup-securestate-events.sh && curl https://gcp.events.securestate.vmware.com/scripts/gcp-eventstream/gcp-event-bridge.jinja -o gcp-event-bridge.jinja && sh setup-securestate-events.sh --endpoint=https://gcp.events.securestate.vmware.com --project-ids=<gcp-project-id1,gcp-project-id2,gcp-project-id3>

Note: The script assigns three roles to the specified projects for the event stream setup. The default cloud services Service Account for each monitored project is assigned the “Logs Configuration Writer” and “Security Admin” roles to create a Cloud Logging Sink and publish to a Pub/Sub topic. The Pub/Sub service account (identified as <project-number>@gcp-sa-pubsub.iam.gserviceaccount.com) is also assigned the “Service Account Token Creator” role for authentication.

The script creates a Cloud Logging Sink and Pub/Sub per project selected to send change configurations to Secure State. You can verify whether the event stream is successfully connected by using the Cloud Accounts Query API to check that your GCP projects have an event stream connected status.

To verify the event stream is active, follow these steps:

  1. From the CloudHealth Secure State dashboard, navigate to Settings > Cloud accounts.

  2. Locate your cloud account in the list, filtering as necessary.

  3. If the Status field displays a green checkmark, then the event stream is active for your account.

  4. You can click on the Account Name to see additional details regarding event stream status and cloud account metadata.

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.


Conclusion

You’re ready to leverage the power of Secure State’s interconnected cloud security model to minimize security risk and proactively mitigate threats in your multicloud environment with Secure State APIs for simplified bulk onboarding.