How to onboard your GCP accounts in CloudHealth Secure State

To connect a new GCP project, you must first create a service account for authentication. The service account is read-only, and the CloudHealth Secure State platform uses it to perform several key tasks:

  • Scans your GCP resource configurations to create an interconnected cloud security model of the environment.
  • Performs near real-time evaluations of configuration changes with the Google Cloud Logging API connected to a Pub/Sub as the event stream.

CloudHealth Secure State provides shell scripts throughout this guide to simplify the creation of the Service Account and set up the event stream with Google Deployment Manager. Although you can use the Google Cloud SDK in a local shell to run the scripts, using Google Cloud Shell for the setup process offers a more streamlined experience with less dependencies.

Enable APIs

You must enable several APIs in GCP so the service can call them to inventory your cloud environment. These instructions assume you are using the Google Cloud Shell to enable the APIs, but you can also enable them individually the GCP Cloud SDK. 

  1. Enable the GCP APIs for service monitoring:
gcloud services enable
  1. Enable Deployment Manager and Pub/Sub APIs to setup event stream after you’ve onboarded your projects.
gcloud services enable

You can verify that these services are active in your GCP console’s APIs & Services dashboard.

Enable APIs for bulk onboarding

If you have multiple projects under a single organization, you can also enable Google Cloud APIs at the organization-level by using these commands in the GCP console or Google Cloud Shell: 

  1. Enable service monitoring GCP APIs for all projects in your organization:

    for project in $(gcloud projects list --format="value(projectId)");
        do echo "ProjectId: $project";
        gcloud config set project $project;
        gcloud services enable;
  2. Enable event stream APIs for all projects in your organization: 

    for project in $(gcloud projects list --format="value(projectId)");
        do echo "ProjectId: $project";
        gcloud config set project $project;
        gcloud services enable;

Set up an organization-level service account

An organization-level service account allows you to onboard multiple GCP projects in bulk, provided you have the organization ID to create the service account. If you don’t have access to your organization ID, follow the Project-level Service Account instructions in the next section. 

  1. Retrieve your organization ID from the GCP console.

  2. Ensure that the default service account (identified as <project-number> has an IAM member with the Organization Administrator role. To create an IAM binding for the default service account, you can use the command below.

    gcloud organizations add-iam-policy-binding <gcp_organization_id> --member serviceAccount:<gcp_project_number> --role roles/resourcemanager.organizationAdmin

Use organization-level service accounts where possible so you can onboard and manage multiple GCP projects in bulk and set up event streams per project. The overall architecture for GCP monitoring appears below. And the following sections provide detailed steps for protecting your Google Cloud resources.

GCP Architecture

Set up a project-level service account

To set up a service account on a per-project basis, follow these steps.

Note: You must onboard every GCP project individually with these instructions, and you’ll need to have Project Owner & Project IAM Admin permissions.

  1. Set the project ID you want to onboard.

    gcloud config set project <project_id>
  2. Create the required custom role in the project.

    gcloud iam roles create vmwareSecureStateRole --project=<project_id> --title="VMware Secure State Viewer" --description="Custom role including additional read permissions required for Secure state." --permissions=storage.buckets.get --stage=GA
  3. Create a service account in the project.

    gcloud iam service-accounts create vmware-secure-state-account --project=<project_id>
  4. Create IAM members for the service account at the project scope.

    gcloud projects add-iam-policy-binding <project_id> --member serviceAccount:vmware-secure-state-account@<project_id> --role projects/<project_id>/roles/vmwareSecureStateRole
    gcloud projects add-iam-policy-binding <project_id> --member serviceAccount:vmware-secure-state-account@<project_id> --role roles/viewer
    gcloud projects add-iam-policy-binding <project_id> --member serviceAccount:vmware-secure-state-account@<project_id> --role roles/iam.securityReviewer
  5. Create the service account key file.

    gcloud iam service-accounts keys create --iam-account vmware-secure-state-account@<project_id> vmw-secure-state-sa-key.json

    Note: If you’re using Google CloudShell, use this command to download the service account key file.

    cloudshell download vmw-secure-state-sa-key.json

Onboard service account

This section covers UI-based onboarding, but if you prefer to onboard your service account and GCP projects by using the API, refer to the API Onboarding Guide.

  1. To connect a new GCP cloud account, navigate to Settings > Cloud accounts. Click the Add New button and select GCP. You can connect multiple GCP projects at the same time.

    Add GCP Cloud Accounts 1

  2. If you followed instructions to set up an organization-level service account, use the UI directions to get the service account onboarded and download the corresponding service account key. The UI onboarding script will create a aervice account at the organization level and assign it several read-only roles:

    • Project Viewer to view configurations of the different services.
    • Organization Viewer to list your GCP Organization metadata and policies.
    • Folder Viewer to list your GCP folders.
    • Security Reviewer to list your GCP Projects.
    • CloudHealth Secure State Role which is a custom role to get configuration details of a bucket.

    Note: If you set up a project-level service account, you already assigned these roles in the previous section. From here, the onboarding actions will be the same regardless of whether you’re using an organization or project-level service account.

  3. Upload the service account key file to CloudHealth Secure State. All GCP Projects that are accessible through the service account are listed. If you don’t see certain GCP Projects, make sure the service account permissions are configured to access them. Select the GCP projects to onboard.

  4. On the next screen, enter information in the Account Name, CloudHealth Secure State Project, Environment (optional), Account Owner Email Address, and Account Owner Name fields as you onboard the selected accounts.

    Add GCP Cloud Accounts 2

  5. Save your configurations and continue to set up your event stream. 

Turn on event stream

After you configure the GCP projects to monitor, you should set up an event stream for each project. CloudHealth Secure State 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.

Add GCP Cloud Accounts 3

Setup with Google Cloud Shell

CloudHealth Secure State provides a simple script and a ready-to-use command in the UI for this setup. You can run this command from Google Cloud Shell or on a local terminal if you've installed the Google Cloud SDK.

curl -o && curl -o gcp-event-bridge.jinja && sh --endpoint= --project-ids=<gcp_project_id1,gcp_project_id2,gcp_project_id3>

A Cloud Logging Sink and Pub/Sub is created per project selected to send change configurations to the service.

Note: While not recommended, a central event stream can also be setup for change monitoring across multiple projects. An Aggregator Sink must be configured to aggregate and send all log entries to the service.

After you run the script, click Finish. The GCP projects you selected are onboarded for monitoring.

Remove event stream

You can remove the event stream for an individual GCP account or a group of accounts using a simple script. To remove the event stream, follow these steps:

  1. Navigate to Settings > Cloud accounts.
  2. Select your GCP cloud account.
  3. On the cloud account details page, select Turn-Off under event stream and follow the instructions.

The script will remove the Cloud Logging, Pub/Sub topic and other pieces for the selected GCP projects.

Manage GCP cloud accounts

To onboard additional GCP projects in your environment after the initial setup, go to the details page for one of your GCP cloud accounts and select Manage.

Manage GCP Accounts 1

This initiates the cloud account management workflow for your GCP credentials (that is, your service account). You can onboard new GCP Projects or remove existing ones connected to the service account from here.

Manage GCP Accounts 2

To onboard new GCP projects, select the projects to onboard from the table at the bottom of the screen and click on Add Account. You’ll then be able to optionally provide Environment, Account Owner Name, and Account Owner Email Address related details, and to configure the event stream. Refer to the GCP event stream overview section for more information on event streams. 

Remove cloud accounts

You can either remove GCP projects in bulk by going through the same work workflow for adding cloud accounts that share the same credential (service account) or do the removal on a per-account basis. 

For bulk GCP account removal, begin by selecting Manage on one of the accounts. From the list of onboarded accounts, select the ones to remove and click Delete Account. A confirmation box will be presented for you to verify that only the desired cloud accounts have been selected for removal. 

Next, click Delete, and the selected GCP account will be removed from monitoring. This action is not reversible and will lead to the removal of all findings, reports, remediations, and so on for the removed cloud accounts.

Manage GCP Accounts 3

To remove a single GCP cloud account, navigate to the cloud account details page, click the Actions button, and select Delete. A confirmation dialog will be presented to verify whether this is intended. Select Delete and the cloud account will be removed from the service along with its findings, reports, remediations, and so on.

Note: You must remove the cloud account’s event stream before the cloud account can be removed from monitoring.

check-circle-line exclamation-circle-line close-line
Scroll to top icon