Skip to main content
With the Google Cloud Platform (GCP) integration, 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.
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

1

On the Plerion dashboard, go to Settings > Integrations

Sidebar navigation with Settings expanded and Integrations highlighted
2

Find GCP and click the + button

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.
Integrations page with GCP organization option and plus button to add integration
3

Select capabilities

  • 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.
  • 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.
4

Grant Plerion access

Choose the Script or Terraform tab.
  • Open Google Cloud Shell 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.
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:
5

Choose projects

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 <N> 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.
6

Done

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 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: 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 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: 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 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

1

On the Plerion dashboard, go to Settings > Integrations

Sidebar navigation with Settings expanded and Integrations highlighted
2

Find GCP and click the + button

Choose GCP project rather than GCP organization.
Integrations page with GCP project option and plus button to add integration
3

Enter an integration name

Integration setup page with GCP integration name field
4

Download the service account key JSON

Follow the GCP integration guide to create a service account and download the JSON key file.
Instructions for downloading GCP service account JSON
5

Upload your service account key file

Drag and drop or browse to upload the JSON file.
Service account key file upload option in Plerion
6

Set scan schedule

Choose when scans should run and set the interval (6, 8, 12, or 24 hours). By default, scans use your local time at setup.
Scan time configuration screen for GCP integration
7

Click Add to complete your GCP integration

Plerion saves the integration and runs its first scan on the schedule you set. Findings appear in your dashboards as they’re collected.