# GCP HostID integration This GCP HostID integration is also covered in the [GCP Brain](https://docs.vectra.ai/deployment/ndr-virtual-cloud-appliances/gcp-brain) and [GCP vSensor](https://docs.vectra.ai/deployment/ndr-virtual-cloud-appliances/gcp-vsensor) deployment guides. ## GCP HostID Integration To enable efficient investigation of cloud hosts, the Vectra Brain can be configured to periodically query GCP to gather additional information about hosts running in GCP. This information contributes to Vectra’s automated Host identification (Host ID) and adds information to the Host details screen. It is a best practice is to enable this integration. Vectra NDR attributes Detections to a Host or an Account. For some algorithms that support learning, Detections must be attributable to a Host (including statically defined hosts), rather than a generic Host container (denoted by IP-x.x.x.x in the Vectra Platform UI). Enabling this integration can help contribute to more complete Detection as a result. Please see this example screenshot below of a Host in GCP where additional context was pulled through API calls: ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-3754d50c20c4ef7926db694dbb003f7543ed72a4%2Fgcp-hostid-extraction-1.png?alt=media) As you can see, the integration provided the following (viewable by drilling down to the Host and then the Details tab): * Host ID artifacts including a unique identifier and name * Project, link to GCP, IP, and Last Seen date/time * Summary information on the left-hand side including instance size, status, name, and zone ### Configuration Example {% hint style="info" %} **Please Note:** If your organization is organized in a manner requiring more than one service account for your Vectra GCP deployment, multiple sets of credentials can be added to your Vectra configuration for the HostID integration. For the HostID integration, if your monitoring needs span multiple projects, Vectra requires a service account per project. Existing service accounts can be re-used, or you may add new ones specific to this use case. {% endhint %} ### **Resources** * [Creating and Managing GCP Service Accounts](https://cloud.google.com/iam/docs/creating-managing-service-accounts) * [Understanding GCP Roles - Also details predefined roles](https://cloud.google.com/iam/docs/understanding-roles) ### **Basic Steps** * After signing into the GCP console, navigate to *IAM and Admin → Service Accounts* and click **+ CREATE SERVICE ACCOUNT.** ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-84e3939d9f0120218de6a05944089511cc33cec1%2Fgcp-hostid-extraction-2.png?alt=media) * Give the account a name and optionally a description and then click **CREATE AND CONTINUE.** ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-a0c21e16e7c22e2e70d16543392a7eda5237b232%2Fgcp-hostid-extraction-3.png?alt=media) {% hint style="info" %} In the below example, we are creating a service account for the HostID service account used by the Brain to retrieve artifacts that help with Vectra's automated HostID. When creating other service accounts, choose the appropriate role for the service account you are creating. {% endhint %} * Choose a role that has read access to the compute v1 endpoints on GCP API to list zones, instances, and networks and click **CONTINUE**. The predefined **Compute Viewer** role provides the required permissions: ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-2a47cecf937a5c9da75ec5c9adc0e800bdd9fb36%2Fgcp-hostid-extraction-4.png?alt=media) * Optionally grant users access to the service account and then click **DONE.** ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-90fc46baebd744657c1d15c12f89095defc19bd6%2Fgcp-hostid-extraction-5.png?alt=media) * Now select your newly created service account and navigate to the **KEYS** tab, click on **ADD KEY**, and then **Create new key.** ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-fb7075c11aa8ea9b164c701c23f8c621b56f0c5a%2Fgcp-hostid-extraction-6.png?alt=media) * Select **JSON** format and click **CREATE.** ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-7e406672ddbe4a478bcc73392f69bda9fa85f954%2Fgcp-hostid-extraction-7.png?alt=media) * This key will download to your computer when created. {% hint style="info" %} **Please note:** * Save the key for later use. * On the **DETAILS** tab for your service account, also make note of the **Unique ID** for later use. {% endhint %} * To complete the integration, in the Vectra UI, browse to *Configuration →* *Settings → External Connectors*. * Click on the pencil or **Edit** link for Google Cloud. * Toggle the integration to **On** and fill in the **CREDENTIAL ID** (the **Unique ID** you made note of in the last step) and upload your **CREDENTIAL JSON** file. * Click **Save**. Multiple sets of credentials can be configured if required for organization. ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-50ff7fa1492f691af55d7fe6d88f1b9ca3aadf3b%2Fgcp-hostid-extraction-8.png?alt=media) * The connection will be tested and if successful, you will see a green checkmark showing that Google Cloud integration has been completed. ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-2e742cfc13a93423d847026cbc47a9b40c35a11e%2Fgcp-hostid-extraction-9.png?alt=media) ### Viewing and Modifying Virtual Networks Considered by the Connector The connector will only look at virtual machines that belong to some VPCs, not necessarily all VPCs that the credentials have access to. Specifically, by default, the connector will only look for virtual machines with network interfaces in the VPCs where a Vectra GCP Sensor traffic interface is deployed into, and all the VPCs peered to it. If a virtual machine has multiple network interfaces, the connector will provide host identification only for the IP addresses belonging to interfaces on monitored VPCs. Vectra limits the scope of the connector to only virtual networks that can reach an GCP Sensor for the following reasons: * Vectra wants to avoid an excessive number of connections to the GCP resource manager. * To improve performance, Vectra wants to avoid storing unnecessary information in the platform for resources that we are not monitoring. * In the cloud it is possible that you may have some isolated virtual networks that are not monitored by Vectra Sensors but have overlapping IP space with some other networks that are monitored. Duplicate IPs are not supported by Vectra. To avoid Host ID issues, we only consider virtual machines on the networks that appear reachable by our Sensors. If you want to add or remove some virtual networks from the set of virtual networks that Vectra monitors, you can do so through the CLI (ssh to the Brain as the `vectra` user). This functionality is not available in the Vectra UI. The use case for adding or removing virtual networks could be any of the following: * If you have some tunneling or forwarding enabled and Vectra GCP Sensors see traffic from VPCs that are NOT directly connected to our Sensor: * You will want to add the networks to the monitored networks list to extend HostID coverage to the tunneled/forwarded traffic’s associated Hosts. * If you do **NOT** have any GCP Sensors deployed, but mirror GCP traffic into your data center where you have Vectra physical or virtual Sensor coverage: * You will want to add the networks to the monitored networks list to extend Host ID coverage to the mirrored traffic. * If you do have some overlapping IP space on a network that appears reachable by our Sensor, but it is not monitored by our Sensor: * You will want to remove the overlapping networks from the monitored networks to avoid any Host ID issues. * If you have a lot of peered VPCs but only some are monitored by the Sensor: * You will want to remove the non-monitored networks from the monitored networks list to increase performance and reduce load on the GCP resource manager. The command to add or remove virtual network from the Vectra CLI is `set gcp vpcs` . The command has a very helpful help message illustrating its use: ``` vscli > set gcp vpcs --help Usage: set gcp vpcs [OPTIONS] Set GCP virtual network information. Usage example: > set gcp vpcs --whitelist A --whitelist B will set the whitelist to [A, B] > set gcp vpcs --blacklist A --blacklist B will set the blacklist to [A, B] > set gcp vpcs --clear-whitelist will set the whitelist to [] (ie remove the whitelist) > set gcp vpcs --clear-blacklist will set the blacklist to [] (ie remove the blacklist) Options: --whitelist TEXT vpc to include in whitelist --blacklist TEXT vpc to include in blacklist --clear-whitelist reset whitelist to empty list --clear-blacklist reset blacklist to empty list -h, --help Show this message and exit. ``` The command `show gcp vpcs` will show the VPC configuration, including the whitelist (VPCs to ADD), the blacklist (VPCs to REMOVE), the Sensor’s VPCs, and finally the overall monitored networks, which is simply computed as ((Sensors networks + peered) + whitelist) - blacklist. It may take up to 10 minutes for the summarized `monitored networks` to update in the `show gcp vpcs` command output. Example of usage: ``` vscli > show gcp vpcs Output: Blacklist Vpcs: Monitored Vpcs: projects/vectra-tme-dev/global/networks/tme-cognito-source, projects/vectra-tme-dev/global/networks/tme-sensor-trf, projects/vectra-tme-dev/global/networks/tme-sensor-mgt Sensors Vpcs: projects/vectra-tme-dev/global/networks/tme-cognito-source, projects/vectra-tme-dev/global/networks/tme-sensor-trf, projects/vectra-tme-dev/global/networks/tme-sensor-mgt Whitelist Vpcs: ``` ``` vscli > set gcp vpcs --blacklist projects/vectra-tme-dev/global/networks/tme-sensor-mgt Output: success vscli > show gcp vpcs Output: Blacklist Vpcs: projects/vectra-tme-dev/global/networks/tme-sensor-mgt Monitored Vpcs: projects/vectra-tme-dev/global/networks/tme-cognito-source, projects/vectra-tme-dev/global/networks/tme-sensor-trf Sensors Vpcs: projects/vectra-tme-dev/global/networks/tme-cognito-source, projects/vectra-tme-dev/global/networks/tme-sensor-trf, projects/vectra-tme-dev/global/networks/tme-sensor-mgt Whitelist Vpcs: ```