> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plerion.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GCP integration overview
> Integrate Plerion with Google Cloud Platform (GCP) to automate scanning for misconfigurations and strengthen cloud security posture across your GCP environment.
With the [Google Cloud Platform (GCP) integration](https://app.plerion.com/settings/integrations/add/GCP/GCPOrganization), Plerion connects to your GCP environment and continuously scans it for misconfigurations and other security risks, with findings displayed in your dashboards for monitoring and remediation. Connect an entire Google Cloud organization in one step. Plerion discovers every project automatically, scans the ones you select (every project, by default), and continuously assesses organization-level resources such as folders, organization policies, and VPC Service Controls. You can also connect a single project.
***
## About the GCP integration
Plerion integrations connect your GCP projects to the platform so risks across your cloud footprint can be continuously assessed and reported.
* **Complete visibility**
The more GCP projects you integrate, the more accurate and complete your risk reporting becomes. Each integration feeds findings into Plerion's dashboards, where you can filter and analyze results by project.
* **Organization-wide and keyless** *(recommended)*
Connect a whole GCP organization at once. Plerion authenticates using Workload Identity Federation, so no service account key is ever created or stored.
* **Single project**
Alternatively, connect one project at a time using a service account key with least-privilege permissions. Plerion is agentless, so there's no software to deploy in your project.
***
## Organization-wide integration (recommended)
Connect every project in a Google Cloud organization to Plerion in one step. Plerion discovers every project under the organization, including ones created after you connect it, and scans the ones you select.
### Prerequisites
* **Organization Admin** (or equivalent) access to the GCP organization you want to connect.
* Nothing to create for the Plerion service project. The onboarding script or the Terraform template sets it up automatically.
Both the Workload Identity pool and the service account Plerion authenticates as must live inside a GCP project, since GCP requires it. Rather than asking you to designate one of your workload projects, the onboarding script or Terraform template creates a small, dedicated project to hold them: no workloads run in it, and it adds no compute cost. Keeping it separate from the projects you actually run workloads in keeps the access boundary clean and easy to audit.
The project is named **Plerion service project**, with a project ID beginning with `plerion-service-` followed by a random suffix. GCP project IDs are unique across every Google Cloud customer, not just within your organization, so a fixed ID would only ever work once, for whoever claimed it first; the random suffix guarantees one is always available. Either path also labels the project `plerion-service=true` and looks for that label on every run, so re-running it reuses the existing project instead of creating a duplicate.
### Steps to connect a GCP organization
Choose **GCP organization** *(recommended)* rather than **GCP project**. Plerion opens straight into capability selection: there's no name, environment, or schedule form to fill in up front. Plerion names the integration after your GCP organization once it's detected, and applies a default daily scan schedule; adjust the name, environment, or schedule later from the integration's page.
* **Cloud security posture management (CSPM)** and **Cloud infrastructure entitlement management (CIEM)** are always on and can't be turned off.
* **Cloud workload protection platform (CWPP)** is optional. Turning it on grants Plerion the access it needs for agentless workload scanning, and you can change or revoke this access at any time. Workload scanning itself (what it scans, how it works, and how to turn it on) is covered separately in [Workload scanning](/guides/integrations/gcp/workload-scanning/overview).
* If CWPP is on, choose a **Cloud Key Management Service (KMS) access mode**:
* **All keys** *(recommended)*: Plerion is granted access to every Cloud KMS key across the organization, needed to decrypt the workload snapshots it creates for scanning. Exclude a project's keys by tagging the project `PlerionAccess: Denied`. You'll need to acknowledge that Plerion will have access to every Cloud KMS key in the organization before continuing.
* **Selected KMS keys**: Plerion is granted no Cloud KMS key access at onboarding. Grant a project's keys by tagging the project `PlerionAccess: Granted`.
* Click `Next`. Capabilities and KMS access mode are editable later from the integration's detail page; expanding access may prompt you to re-run the script or Terraform apply so the GCP-side grants match, but it's a quick sync, not a full re-onboard.
Choose the **Script** or **Terraform** tab.
* Open [Google Cloud Shell](https://shell.cloud.google.com) in the organization's Google Cloud console.
* Paste and run the generated command. It downloads and runs `plerion-gcp-onboard.sh`, which sets up keyless access and registers the organization with Plerion. Nothing is installed outside Cloud Shell.
* The script prints every command it runs before running it, so you can review exactly what it does. It never creates or downloads a service account key.
* Download the Terraform template linked in the tab.
* Fill in `terraform.tfvars`. Plerion's wizard shows your `plerion_api_url` and other account and authentication details for you to copy in.
* Add your **organization ID** (`org_id`) yourself: unlike the script, the Terraform module can't detect it. Find yours with `gcloud organizations list`.
* Run `terraform init` and `terraform apply` (or apply it through your own Terraform workflow).
Terraform authenticates to GCP with your local [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials), which must belong to an **Organization Admin** of the target organization. In Cloud Shell this is automatic. Anywhere else, run `gcloud auth application-default login` and select that admin account before `terraform apply`. Missing or mismatched credentials surface as organization-level `403 permission-denied` errors, even when your `gcloud` user already holds the right roles.
Either path finds your organization automatically and creates or reuses the **Plerion service project**. You never name or provide a project yourself. Plerion detects the new organization once the script or `terraform apply` completes, and you can navigate away from this page while you wait.
**If registration fails on the first run:** newly granted GCP IAM permissions can take a minute to propagate. The script already retries registration automatically (for up to about 3.5 minutes) before giving up, and every step it runs is safe to repeat, so re-running the same command resolves this. If the script instead reports that your access token expired (tokens are valid for about 2 hours), re-running the same command won't help: open the wizard again and copy a fresh command.
**Verify the script (optional):** Plerion publishes a SHA-256 checksum alongside `plerion-gcp-onboard.sh`, regenerated on every release. Before running the script, download its checksum from the same URL with `.sha256` appended and check it:
```bash theme={"system"}
curl -sO && sha256sum -c plerion-gcp-onboard.sh.sha256
```
Once Plerion detects the organization, it shows every project discovered so far, all selected by default.
* Search by project name, ID, or label to narrow a long list.
* Use `Select all` or `Deselect all`. Either acts on the current search results when a filter is active, or on every project otherwise.
* Turn `Automatically include new projects` off if you don't want projects created later to join automatically. New projects are discovered and scanned with no further action while it's on.
* Click `Add projects` to confirm your selection. Deselecting every project swaps this to `Continue without projects`; the organization integration keeps scanning organization-level resources either way, and you can add projects later from the integration's page.
If discovery hasn't found any projects yet, or the list fails to load, click `Onboard all projects automatically` instead of waiting on a retry: it onboards every project with no exclusions.
Your organization is already connected once the previous step's script or Terraform apply completes. If you leave the wizard on this step without confirming a selection, all discovered projects onboard automatically within an hour.
If `Automatically include new projects` is on, new projects can take up to an hour to appear as an integration in Plerion.
Plerion takes you to the organization integration's detail page. From there you can see every discovered project, the organization's own scan history and next scheduled scan, and the Plerion service project it created for you.
### What the organization integration scans
Beyond discovering every project and scanning the ones you select, each scan of the organization integration itself collects:
* **Organization details and the organization-level IAM policy:** who has access at the organization level, and what they can do.
* **Folders:** the hierarchy Plerion walks to discover projects.
* **Organization policies:** the [organization policy](https://cloud.google.com/resource-manager/docs/organization-policy/overview) constraints enforced across the organization.
* **VPC Service Controls service perimeters:** the access boundaries configured in Access Context Manager.
Its scan history, next scheduled scan, and a `Scan now` action all appear on the organization integration's detail page, the same as any other integration, and its scan schedule can be changed at any time. That schedule also serves as the default for every project the integration discovers going forward. Changing it doesn't retroactively update projects already discovered, but it applies to any new project found afterward.
### What the script or Terraform creates
The onboarding script or Terraform template grants Plerion's service account a **Plerion Posture Read** custom role, scoped to the configuration and metadata of the GCP services Plerion supports. Plerion defines and reviews every permission in this role.
Plerion cannot modify or delete your resources, and reads only resource configuration and metadata, never the contents of your data. That excludes object contents, database rows, message payloads, log bodies, secret values, and model or AI content. CWPP (workload access) uses a separate, opt-in role, described below.
The script and Terraform template list every permission granted. Review either one before you run it. You can review the same grants afterward in your GCP IAM console. New organizations receive this access set automatically when you connect them.
If **CWPP (workload access)** is enabled, the script or Terraform template also creates a custom role, **Plerion Workload Scan**, scoped to the following permissions:
| Permission | Purpose |
| ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `compute.disks.get`, `compute.disks.list`, `compute.disks.createSnapshot` | Snapshot disks for workload scanning |
| `compute.instances.get`, `compute.instances.list` | Read Compute Engine instance metadata |
| `compute.instanceGroupManagers.get`, `compute.instanceGroupManagers.list` | Read managed instance group metadata |
| `cloudfunctions.functions.get`, `cloudfunctions.functions.list` | Read Cloud Functions metadata |
| `run.services.get`, `run.services.list` | Read Cloud Run service metadata |
| `artifactregistry.repositories.get`, `artifactregistry.repositories.list`, `artifactregistry.repositories.downloadArtifacts` | Read and pull container images from Artifact Registry |
| `container.clusters.get`, `container.clusters.list` | Read GKE cluster metadata |
This role deliberately excludes any write or delete permission on your resources beyond `disks.createSnapshot`, the same boundary AWS workload protection uses: Plerion can create the temporary resources it needs to scan, but never modifies or deletes anything already in your environment. Turning on workload scanning for Compute Engine VMs (below) narrows that boundary slightly, adding a delete permission scoped only to snapshots Plerion itself created; see the note below for details.
With workload access on, the script or Terraform template also grants `roles/cloudkms.cryptoKeyEncrypterDecrypter`, so Plerion can decrypt customer-managed encryption key (CMEK)-protected assets it encounters while scanning. This grant applies for either KMS access mode; only its condition changes: for **All keys**, it covers every project except those tagged `PlerionAccess: Denied`; for **Selected KMS keys**, only projects tagged `PlerionAccess: Granted`.
Turning on **workload scanning** for Compute Engine VMs (below) extends this same role with a small set of snapshot-related permissions, plus a second, tightly conditioned role. See [Access and permissions](/guides/integrations/gcp/workload-scanning/access-and-permissions) for the full, current grant list.
### Keyless access
Plerion never creates, downloads, or stores a service account key for an organization-wide integration. Instead, the script or Terraform template sets up [Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation): Plerion authenticates as its own AWS identity and exchanges it for a short-lived GCP access token, scoped to only the service account it creates.
To revoke Plerion's access at any time, delete the workload identity pool (`plerion`, in your Plerion service project). This immediately ends all federated access: Plerion can no longer exchange tokens for your organization. If you provisioned access with the script, it prints the exact command to do this, along with commands to remove the organization-level role bindings, at the end of its run. If you used Terraform, run `terraform destroy` (or remove the corresponding resources from your configuration) instead.
### Controlling CMEK access per project
Which projects Plerion's KMS access covers depends on your KMS access mode, using the same [resource tag](https://cloud.google.com/resource-manager/docs/tags/tags-overview) key both ways:
* **All keys:** every project is included by default. Tag a project `PlerionAccess: Denied` to exclude it. Plerion's access to that project's KMS keys is removed automatically, with no further action needed.
* **Selected KMS keys:** no project is included by default. Tag a project `PlerionAccess: Granted` to include it. Plerion's access to that project's KMS keys is granted automatically, with no further action needed.
The onboarding script or Terraform template creates the `PlerionAccess` tag key with both the `Denied` and `Granted` values, so they're ready to apply as soon as you need them.
Both tags are project-level, not per-key. To scope access to a single key ring instead of an entire project, don't apply the tag. See the source comment above the CMEK binding step in the onboarding script for the equivalent per-key grant command.
***
## Projects Plerion does not scan
Google creates and owns a small number of projects inside your organization to hold Workspace products. They contain no infrastructure you can manage or secure, so Plerion never onboards them. They are excluded during discovery, which means they don't appear in the project picker and are scanned by neither posture nor workload scanning.
Two rules identify them:
* Any project under the **`system-gsuite`** folder at your organization root. This is where Google puts Apps Script and AppSheet container projects, and where it has added new folders in the past without notice, so the whole subtree is skipped.
* Any project whose ID looks like **`sys-`** followed by a long number. These are Apps Script containers, one per script in your Workspace.
Projects Google creates for you but that you own are not affected. The Default Gemini Project (`gen-lang-client-...`) sits at your organization root, is yours to manage, and is discovered and scanned normally.
Plerion does not exclude projects merely because their ID starts with `app-`. That is a common prefix for real projects, so exclusion is based on the folder, not the name.
***
## Single project
As an alternative to an organization-wide integration, connect one GCP project at a time using a service account key.
### Steps to connect a single GCP project
Choose **GCP project** rather than **GCP organization**.
Follow the GCP integration guide to create a service account and download the JSON key file.
Drag and drop or browse to upload the JSON file.
Choose when scans should run and set the interval (6, 8, 12, or 24 hours). By default, scans use your local time at setup.
Plerion saves the integration and runs its first scan on the schedule you set. Findings appear in your dashboards as they're collected.