> For the complete documentation index, see [llms.txt](https://docs.dropzone.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dropzone.ai/integrations/data/gcp_data.md).

# Google GCP

Dropzone AI integrates with GCP (Google Cloud Platform) APIs for ingesting alerts and enriching investigations with data from GCP such as VM and service account information. This document describes how to set up API credentials and install them into the Dropzone platform.

## Integration Overview

To enable these integrations you will perform the following actions:

* Determine which section of your GCP environment to enable Dropzone visibility
* Grant IAM access to the Dropzone service account
* Enable the Data source in your Dropzone tenant

Alternatively, if your policies require third-party integrations to use service accounts that you personally own, Dropzone also supports [Service Account Impersonation](https://docs.cloud.google.com/iam/docs/service-account-impersonation) as a method of authentication. This allows an already-authenticated principal to temporarily act as a target service account and use its permissions, often by requesting short-lived credentials instead of downloading long-lived keys. See the Account Impersonation section of this document for further information.

## Determine Dropzone Visibilty Scope

Dropzone requires some IAM access to query your GCP environment.

You will later be granting the Dropzone service account access to a portion of your GCP environment, at either a folder level or for the whole organization.

For example, in the screenshot below, if you were to grant access via the `production` folder then Dropzone would have access to the `Project FreezeRay` project, and any other folders or projects you add to `production` in the future. However, it would not be available to `alligator-apples`. If you grant access via the top level org, `example.net` then it would apply to all folders and projects going forward.

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2F2uLGEREZlEaytFVtHkj9%2Fgcp-console-03.png?alt=media" alt=""><figcaption><p>Resource Selection</p></figcaption></figure>

When enabling the integration you will be supplying the ID of the top level folder or organization, and Dropzone will recurse through all objects thereunder when making Data Source queries.

When you've chosen your folder or org, record the ID value for use later in the Dropzone UI where it is called "Parent Resource"."

## Identify your service account email address

To obtain the email address of your Dropzone service account, do the following:

* Navigate to your Dropzone AI tenant home page e.g. https\://*mycompany*.dropzone.app
* In the bottom left hand corner, navigate to Settings > Integrations

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FQKQGU2YK0KqsewZWvh0i%2Fui-integrations-dropdown.png?alt=media" alt=""><figcaption><p>Integrations Dropdown</p></figcaption></figure>

* Click "Library"

{% hint style="info" %}
If you have previously integrated this application, click "Configured"
{% endhint %}

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2Fx4O3FuRG5IqPwx5sFuHr%2Fapp_system_integrations_library.png?alt=media" alt=""><figcaption><p>Click Library</p></figcaption></figure>

* In the Search bar, search GCP, then click "Configure"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FTVWMOvPh99OMDHCf7Lzg%2Fapp_system_integrations_available_gcp.png?alt=media" alt=""><figcaption><p>The GCP Tile</p></figcaption></figure>

* Record the "SERVICE ACCOUNT EMAIL" field for use in the GCP Console interface

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FAMuLHHLMxfZNj44M9SVQ%2Fui-gcp-data-source-service-account.png?alt=media" alt="" width="320"><figcaption><p>SERVICE ACCOUNT EMAIL</p></figcaption></figure>

## Grant GCP Access to Dropzone Service Account

* Go to the GCP cloud console at <https://console.cloud.google.com>

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FDrvNHq5PytQ7x8ZsbnWJ%2Fgcp-console-00.png?alt=media" alt=""><figcaption><p>Project Dropdown</p></figcaption></figure>

* Click the current project dropdown
* Click "All"
* Select the organization or the folder you've chosen for Dropzone visibility

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2F2uLGEREZlEaytFVtHkj9%2Fgcp-console-03.png?alt=media" alt=""><figcaption><p>Resource Selection</p></figcaption></figure>

* From the left menu, navigate to IAM & Admin > IAM

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FuhBfkQ79Jm8h6TjKICnV%2Fgcp-console-02.png?alt=media" alt=""><figcaption><p>IAM &#x26; Admin Menu</p></figcaption></figure>

* Under "New principals," input the email address you copied earlier from the Dropzone UI "SERVICE ACCOUNT EMAIL"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FiyjqidFlF5e1W6w46R3T%2Fgoogle-gcp-add-principles-1.png?alt=media" alt=""><figcaption><p>Input the email address from the Dropzone UI Service Account Email</p></figcaption></figure>

* Click "Select a role"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FzIO2KZVj2MvKxHYXiUeh%2Fgoogle-gcp-assign-roles.png?alt=media" alt=""><figcaption></figcaption></figure>

* Add the following roles:

| Role Name                                                                                                         | Purpose                                    | Used By                  |
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------ |
| [Security Center Admin Viewer](https://cloud.google.com/iam/docs/understanding-roles#securitycenter.adminViewer)  | View GCP entity details and configurations | Alert Source Integration |
| [Browser](https://cloud.google.com/iam/docs/understanding-roles#browser)                                          | View GCP resources                         | Data Source Integration  |
| [Cloud Asset Viewer](https://cloud.google.com/iam/docs/understanding-roles#cloudasset.viewer)                     | View cloud assets                          | Data Source Integration  |
| [Compute Viewer](https://cloud.google.com/iam/docs/understanding-roles#compute.viewer)                            | View compute resources                     | Data Source Integration  |
| [Folder Viewer](https://cloud.google.com/iam/docs/understanding-roles#resourcemanager.folderViewer)               | View folders                               | Data Source Integration  |
| [Logs Viewer](https://cloud.google.com/iam/docs/understanding-roles#logging.viewer)                               | View GCP logs                              | Data Source Integration  |
| [Organization Role Viewer](https://cloud.google.com/iam/docs/understanding-roles#iam.roleViewer)\*                | View organization roles                    | Data Source Integration  |
| [Organization Viewer](https://cloud.google.com/iam/docs/understanding-roles#resourcemanager.organizationViewer)\* | View organization resources                | Data Source Integration  |
| [Private Logs Viewer](https://cloud.google.com/iam/docs/understanding-roles#logging.privateLogViewer)             | View private logs                          | Data Source Integration  |
| [Security Reviewer](https://cloud.google.com/iam/docs/understanding-roles#iam.securityReviewer)                   | Review security configurations             | Data Source Integration  |
| [Storage Object Viewer](https://cloud.google.com/iam/docs/understanding-roles#storage.objectViewer)               | View storage objects                       | Data Source Integration  |
| [Tag Viewer](https://cloud.google.com/iam/docs/understanding-roles#resourcemanager.tagViewer)                     | View tags                                  | Data Source Integration  |

\* These roles should only be included if the top-level parent is an organization.

{% hint style="info" %}
Some of these roles are only necessary for the Alert Source integration. If you don't intend to perform that integration, you may ignore them.
{% endhint %}

* Continue adding roles via the "Add another role" button until complete

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FZfSVjsiQFbY1CFtBN0op%2Fgcp-console-05.png?alt=media" alt=""><figcaption><p>Add another role</p></figcaption></figure>

* Click "Save"

If your GCP environment has [Domain Restricted Sharing](https://docs.cloud.google.com/organization-policy/domain-restricted-sharing) (e.g. `iam.allowedPolicyMemberDomains` enabled) you will also need to add Dropzone's GCP ID (`C043u1v4t`) to your allow-list. Follow instructions [here](https://docs.cloud.google.com/organization-policy/restrict-domains#managed-constraint) to do so.

## Account Impersonation

Rather than grant Dropzone's service account roles directly within your organization, you can [use account impersonation](https://docs.cloud.google.com/docs/authentication/use-service-account-impersonation). Dropzone will then only be able to use short-lived tokens to access your information, and you can control its access more directly.

To use account impersonation, do the following:

* Create or choose an existing service account in one of your GCP projects
* In the project you want Dropzone to have access to, grant your service account the same roles listed in the "Grant GCP Access to Dropzone Service Account" table above, instead of granting them to the Dropzone service account
* In the project that owns your service account, enable the following APIs:

| API                                                                                                             | Purpose                         |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| [Cloud Resource Manager API](https://console.cloud.google.com/apis/library/cloudresourcemanager.googleapis.com) | List folders and projects       |
| [Cloud Logging API](https://console.cloud.google.com/apis/library/logging.googleapis.com)                       | Query GCP logs                  |
| [Cloud Asset API](https://console.cloud.google.com/apis/library/cloudasset.googleapis.com)                      | Look up IAM policies and assets |
| [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com)                      | Look up VMs                     |

{% hint style="warning" %}
Google bills any API calls made by your service account (or account impersonator) to the project that owns it, so these APIs must be enabled in that project. If an API is disabled, the connection test fails with an error such as `SERVICE_DISABLED` or "API has not been used in project."
{% endhint %}

* Navigate to IAM & Admin > Service Accounts
* Select your service account, then open the Permissions tab
* Click "Grant access"
* Input the Dropzone "SERVICE ACCOUNT EMAIL" (as located in the "Identify your service account email address" section above) as the principal
* Assign your service account the [Service Account Token Creator](https://cloud.google.com/iam/docs/understanding-roles#iam.serviceAccountTokenCreator) role
* Record your service account's email address for use later in the Dropzone UI, where it is called "Customer-Owned Service Account (Impersonation)"

If your GCP environment has [Domain Restricted Sharing](https://docs.cloud.google.com/organization-policy/domain-restricted-sharing) (e.g. `iam.allowedPolicyMemberDomains` enabled) you will still need to add Dropzone's GCP ID (`C043u1v4t`) to your allow-list, as the Token Creator grant names the Dropzone service account. Follow instructions [here](https://docs.cloud.google.com/organization-policy/restrict-domains#managed-constraint) to do so.

## Enable GCP

The Data source integration allows Dropzone to interact with your GCP environment to gather information for use in investigation analysis and interactive chat.

You'll need the following information:

| Dropzone Field  | Source                                                        |
| --------------- | ------------------------------------------------------------- |
| Parent Resource | The ID of the org or folder where you granted Dropzone access |

To enable the Data Source integration, do the following:

* Navigate to your Dropzone AI tenant home page e.g. https\://*mycompany*.dropzone.app
* In the left side bar, navigate to Platform Settings > Integrations

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FQKQGU2YK0KqsewZWvh0i%2Fui-integrations-dropdown.png?alt=media" alt=""><figcaption><p>Integrations Dropdown</p></figcaption></figure>

* Click "Library"

{% hint style="info" %}
If you have previously integrated this application, click "Configured"
{% endhint %}

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2Fx4O3FuRG5IqPwx5sFuHr%2Fapp_system_integrations_library.png?alt=media" alt=""><figcaption><p>Click Library</p></figcaption></figure>

* In the Search bar, search GCP, then click "Configure"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FTVWMOvPh99OMDHCf7Lzg%2Fapp_system_integrations_available_gcp.png?alt=media" alt=""><figcaption><p>The GCP Tile</p></figcaption></figure>

* Under the Data Source heading, input the "Parent Resource" ID
* Select the "Parent Resource Type" that matches the resource you've selected
* If you are using Account Impersonation, input your Customer-Owned Service Account
* Select the "Default Zone." This is used for queries (such as finding VMs) when a zone is not specified

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FoDzIzz5QWCIO6hH4uf7m%2Fapp_system_integrations_available_gcp_data_config.png?alt=media" alt=""><figcaption><p>The GCP Data Source configuration</p></figcaption></figure>

* Click "Test & Save" to finish

If you have any errors contact our Customer Success team.
