# Google Cloud Virtual Machine Scanning Setup

{% hint style="info" %}
GCP Virtual Machine Scanning is currently available by request. [Reach out to support](https://www.aikido.dev/contact) to have it enabled for your workspace.
{% endhint %}

### Why should I scan my virtual machines?

With virtual machine scanning, Aikido scans the disks of your Google Compute Engine VMs for vulnerable packages, outdated runtimes and risky licenses.

### Getting started

To enable the scanning of your virtual machines on GCP, you should first start by connecting your Google Cloud project to Aikido. Follow the steps outlined [here](https://help.aikido.dev/cloud-scanning/connect-your-cloud/gcp) if you haven't done so already.

Once your cloud is connected, navigate to the Virtual Machines page and click **Connect VMs**.

<figure><img src="/files/gYplCFUSehZeuJrh38z1" alt=""><figcaption></figcaption></figure>

In the **Connect your Virtual Machines** modal, select **Google Cloud** under **Agentless scanning**. This opens a 6-step setup wizard that guides you through creating a Cloud Storage Bucket, enabling the required APIs, creating a custom IAM role and service account, and uploading a service account key to Aikido.

Only the bare minimum of permissions are granted to the custom role and service account, and storage permissions are scoped to the snapshot bucket only, not project-wide. This ensures that Aikido can perform its security checks without the risk of unintended altering of your resources.

{% stepper %}
{% step %}
**Create a Cloud Storage Bucket**

Aikido needs a Cloud Storage Bucket to export your VM disk snapshots to before scanning them.

Create the bucket using either option:

* **GCP console**: follow [Google's bucket creation guide](https://cloud.google.com/storage/docs/creating-buckets).
* **`gcloud` CLI**: Aikido pre-fills a ready-to-run command on the setup screen with your project ID and a suggested bucket name. Adjust the name or location if needed.

Paste the bucket name into the **Bucket Name** field and click **Continue**.
{% endstep %}

{% step %}
**Enable Cloud APIs**

Aikido needs several Google Cloud APIs enabled in your project to scan your compute instances.

1. In the GCP console, click the **Activate Cloud Shell** icon in the top right.
2. In the shell that opens at the bottom of the screen, run the command shown on the setup page. It enables the following APIs:
   * `compute.googleapis.com`
   * `storage-component.googleapis.com`
   * `cloudbuild.googleapis.com`
   * `iamcredentials.googleapis.com`
   * `iam.googleapis.com`
3. Once the command completes, click **Continue**.
   {% endstep %}

{% step %}
**Create a custom role**

Aikido needs a custom IAM role with permissions to list instances, manage snapshots, and start Cloud Build exports. Default GCP roles for these operations typically require admin-level access, which is more permissive than necessary. A custom role grants only what Aikido needs.

1. In the Cloud Shell, run the `gcloud iam roles create` command shown on the setup page. Aikido pre-fills your project ID and a recommended role ID (`aikidoSecurityVmScannerRole`).
2. The command provisions a role at the **GA** stage with the following permissions:
   * `compute.instances.list`
   * `compute.instanceGroups.get`
   * `compute.instanceGroups.list`
   * `compute.disks.createSnapshot`
   * `compute.disks.get`
   * `compute.snapshots.create`
   * `compute.snapshots.delete`
   * `compute.snapshots.get`
   * `compute.snapshots.list`
   * `compute.snapshots.setLabels`
   * `compute.globalOperations.get`
   * `compute.zoneOperations.get`
   * `cloudbuild.builds.create`
   * `cloudbuild.builds.get`
   * `iam.serviceAccounts.actAs`
3. Once the role is created, note its ID (`aikidoSecurityVmScannerRole` unless you changed it). You'll attach it to the service account in the next step.
4. Click **Continue**.

{% hint style="info" %}
**Keep all permissions in this role.** This is the absolute minimum Aikido needs to perform VM scans. Removing any will cause scans to fail.
{% endhint %}
{% endstep %}

{% step %}
**Configure access**

Aikido needs to authenticate to your project to access VM metadata and write snapshots to your bucket. You can use a service account, or reuse Workload Identity Federation if you've already configured it for your GCP cloud connection.

{% tabs %}
{% tab title="Service account" %}
**Service account**

Aikido uses a service account in your project to access VM metadata and write snapshots to your bucket.

1. Click **Create Service Account** on the setup page. This opens the GCP console.
2. Create a new service account (recommended name: `Aikido Security VM Scanner`), or reuse the one you created for cloud scanning.
3. Assign the `aikidoSecurityVmScannerRole` custom role you created in the previous step, then save.
4. Back in the Cloud Shell, run the command shown on the setup page to grant the service account `roles/storage.objectAdmin` on the Cloud Storage bucket from step 1. This grant is scoped to the bucket only, not project-wide. Replace `YOUR_SERVICE_ACCOUNT_EMAIL` with the service account email shown in the GCP console.
5. Click **Continue**.
   {% endtab %}

{% tab title="Workload Identity Federation" %}
**Workload Identity Federation**

If you've already configured Workload Identity Federation for your GCP cloud connection, you can reuse the same WIF setup for VM scanning instead of creating a service account.

1. Skip the **Create Service Account** button in the wizard UI.
2. Grant the `aikidoSecurityVmScannerRole` custom role you created in the previous step, and `roles/storage.objectAdmin` on the Cloud Storage bucket from step 1, to the Aikido WIF principal you configured for cloud scanning. See the [WIF setup doc](https://help.aikido.dev/cloud-scanning/connect-your-cloud/gcp/google-cloud-workload-identity-federation-setup) for the principal format.
3. Click **Continue**.
   {% endtab %}
   {% endtabs %}
   {% endstep %}

{% step %}
**Upload your credentials**

Upload the credential file Aikido will use to authenticate to your project.

{% tabs %}
{% tab title="Service account key" %}
**Service account key**

Aikido authenticates to your project using a JSON service account key.

1. In the GCP console, open the service account you created in the previous step.
2. Go to the **Keys** tab.
3. Click **Add key** → **Create new key**.
4. Select **JSON** as the key type and click **Create**. GCP will download a JSON file containing the credentials.
5. Back on the Aikido setup page, click **Upload JSON file** and select the key file you just downloaded.
6. Click **Save & Continue**.

{% hint style="info" %}
Treat the downloaded JSON key like a password. It grants access to your GCP project under the role you just assigned, so don't commit it to source control or share it.
{% endhint %}
{% endtab %}

{% tab title="WIF config file" %}
**WIF config file**

If you configured Workload Identity Federation in the previous step, upload the WIF config file generated during your GCP cloud connection setup instead of an SA key. The same **Upload JSON file** field accepts both file types.

1. On the Aikido setup page, click **Upload JSON file** and select your WIF config file.
2. Click **Save & Continue**.
   {% endtab %}
   {% endtabs %}
   {% endstep %}
   {% endstepper %}

### Temporary Resources

When exporting a GCP snapshot, [Google's export tooling (Daisy)](https://docs.cloud.google.com/compute/docs/images/export-image) creates temporary resources in your project, such as:

* a temporary Compute Engine VM
* temporary disks
* temporary objects in a Daisy bucket, typically named `${PROJECT}-daisy-bkt-${REGION}`

These resources are normally cleaned up automatically when the export workflow finishes successfully. However, if the export job fails or is interrupted, Google might leave these temporary resources behind and they may need to be deleted manually.

You can identify Daisy-created temporary VM instances by the following:

* label `gce-image-export-tmp=true`
* label `aik-gcp-vm-scanner-export=<your Aikido workspace ID>`
* description such as `Instance created by Daisy in workflow "image-export-export-disk"`

If you notice these instances persisting in your project(s), it is safe to delete them.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.aikido.dev/virtual-machine-scanning/gcp-vm-scanning/gcp-virtual-machine-scanning-configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.