Google Cloud Platform

Overview

Heeler supports broad visibility into Google Cloud Platform, and can be configured to onboard and stream inventory data from all accounts via a GCP Organization. It is recommended to setup both organization collection and event collection for near real-time assessment.

Setup Options

  • Terraform - Please reach out to the Heeler team for the Terraform modules for GCP setup.

  • gcloud CLI - The instructions below leverage gcloud CLI commands. To install the gcloud CLI utility please follow this guide: https://cloud.google.com/sdk/docs/install.

There are several steps that must be completed within the GCP Console.

Permissions Check

To validate you have the permissions needed to connect your GCP organization to Heeler you can run the following steps:

  1. Login with GCP CLI: 

gcloud auth login

  1. Determine your GCP Organization ID:

gcloud organizations list

  1. Replace below with the value of the ID (not DIRECTORY_CUSTOMER_ID) from the previous step and validate permissions:

  ACCESS_TOKEN=$(gcloud auth print-access-token)
  
  curl -X POST \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    "https://cloudresourcemanager.googleapis.com/v1/organizations/:testIamPermissions" \
    -d '{
      "permissions": [
        "resourcemanager.projects.create",
        "resourcemanager.organizations.get",
        "resourcemanager.organizations.setIamPolicy",
        "resourcemanager.organizations.getIamPolicy",
        "serviceusage.services.enable",
        "iam.serviceAccounts.list",		
        "iam.serviceAccounts.create",
        "iam.workloadIdentityPoolProviders.create"	
      ]
    }'

The response should include all 8 permissions required:

{
  "permissions": [
    "serviceusage.services.enable",
    "resourcemanager.organizations.getIamPolicy",
    "resourcemanager.organizations.setIamPolicy",
    "iam.serviceAccounts.create",
    "iam.serviceAccounts.list",
    "iam.workloadIdentityPoolProviders.create",
    "resourcemanager.projects.create",
    "resourcemanager.organizations.get"
  ]
}

If you do not have all required permissions, you will need to work with a GCP administrator to add the additional permissions.

GCP Organization

To add your GCP Organization to Heeler, it is recommended that a dedicated project be added to your company's existing organization. Doing this ensures isolation and adheres to industry standard best practices. The new project, typically named heeler-security will hold a single service account that will have read-only permission to view resources inside the project and inside the organization.

  1. Create a new project, e.g., heeler-security

gcloud projects create heeler-security

  1. To simplify the remaining gcloud commands, set the newly created project as default

gcloud config set project heeler-security

  1. Enable the APIs that Heeler uses to communicate with GCP

gcloud services enable \
    cloudresourcemanager.googleapis.com \
    iam.googleapis.com \
    iamcredentials.googleapis.com \
    pubsub.googleapis.com \
    sqladmin.googleapis.com \
    sts.googleapis.com

  1. Create a new service account that Heeler will use to pull inventory data, e.g., heeler-collector

gcloud iam service-accounts create heeler-collector \
    --description="Service account used to collect inventory across GCP" \
    --display-name="Heeler Security Collector"

  1. Get the organization ID 

gcloud organizations list

DISPLAY_NAME                ID             DIRECTORY_CUSTOMER_ID
<your organization name>    99580XXXXXXX.  D02pabcde

  1. Grab the email from the newly created service account

gcloud iam service-accounts list

DISPLAY NAME                    EMAIL                                              DISABLED
Heeler Security Collector Demo  [email protected]     False

  1. Use the organization ID to add the Heeler-required predefined IAM Roles to the newly created service account using the email from the previous step, e.g., [email protected]

gcloud organizations add-iam-policy-binding 99580XXXXXXX \
    --member=serviceAccount:[email protected] \
    --role=roles/artifactregistry.reader

gcloud organizations add-iam-policy-binding 99580XXXXXXX \
    --member=serviceAccount:[email protected] \
    --role=roles/iam.securityReviewer

gcloud organizations add-iam-policy-binding 99580XXXXXXX \
    --member=serviceAccount:[email protected] \
    --role=roles/resourcemanager.folderViewer

gcloud organizations add-iam-policy-binding 99580XXXXXXX \
    --member=serviceAccount:[email protected] \
    --role=roles/resourcemanager.organizationViewer

gcloud organizations add-iam-policy-binding 99580XXXXXXX \
    --member=serviceAccount:[email protected] \
    --role=roles/iam.serviceAccountTokenCreator

GKE Cluster Access:

If you are using GKE with GKE DNS endpoints enabled, Heeler needs an additional permission container.clusters.connect. You can create a custom role with this permission, or use the Google-managed roles/container.viewer. 

gcloud organizations add-iam-policy-binding 99580XXXXXXX \
    --member=serviceAccount:[email protected] \
    --role=roles/container.viewer

If you are using GKE clusters without publicly accessible endpoints and you use authorized networks instead of DNS endpoints, you need to add the Heeler outbound IPs as authorized networks:

  • 44.221.229.40

  • 52.73.231.96

  1. Create the Workload Identity Pool

gcloud iam workload-identity-pools create heeler-aws-pool \
    --description="Workload Identity Pool for Heeler on AWS." \
    --display-name="Heeler AWS Pool" \
    --location="global"

  1. Create Workload Identity Provider

gcloud iam workload-identity-pools \
    providers create-aws heeler-aws-provider  \
    --account-id=168777450829 \
    --description="Workload Identity Provider for Heeler on AWS" \
    --display-name="Heeler AWS Provider" \
    --attribute-mapping="google.subject=assertion.arn,attribute.account=assertion.account" \
    --location="global" \
    --workload-identity-pool="heeler-aws-pool"

  1. Login to the GCP Console in order to finalize the configuration and download the Workload Credentials in the following steps:

https://console.cloud.google.com/iam-admin/workload-identity-pools/pool/heeler-aws-pool?hl=en&inv=1&invt=Abh69A&project=heeler-security

  1. Click on Grant Access at the top and on the overlay window select Grant access using Service Account impersonation. Then select the available service account Heeler Security Collector and select account as the attribute with a value of 168777450829. Once you click on save you will be prompted to save

  1. Click on Save and then click on Connected Service Accounts on the top right. Select Download Config and select the provider Heeler AWS Provider.

Heeler Configuration

Once the resources are created and configured in GCP, you need to add their information to Heeler. Open the URL https://app.heeler.com/administration/connections/organizations or just click on the settings icon at the top right and then click on Connections.

Click on Add Organization and then select Google Cloud Platform. Enter:

  1. Organization Name (e.g. Acme Corp)

  2. Workload Identity Configuration, which was downloaded in the prior step

  3. Project ID from the first step, e.g., heeler-security

  4. Folder IDs (optional). If entered, a subset of projects within provided folders will be harvested. If left blank then Heeler will collect inventory from all projects/folders that it has access to.

Click Save. If everything is configured properly within GCP you should see a success message and inventory collection will immediately begin in the background. Please note that for the first round of collection it could take some time based on the size of the GCP footprint.

PreviousAWS Event CollectionNextGCP Supported Services

Last updated

Was this helpful?