GCP Project Setup

This guide covers the detailed GCP configuration required to onboard a project into Cloud Guardian.

Service Account Requirements

Cloud Guardian uses a dedicated service account in each target project. The service account name is cloud-guardian by convention.

Required IAM Roles

| Role | Purpose | Resource Types | |------|---------|---------------| | roles/viewer | Read access to most GCP resources | Compute Engine, general | | roles/run.viewer | Cloud Run service details and metrics | Cloud Run | | roles/secretmanager.viewer | Secret and version enumeration | Secret Manager | | roles/cloudsql.viewer | Cloud SQL instance details | Cloud SQL | | roles/monitoring.viewer | Cloud Monitoring metrics (CPU, memory utilization) | All |

Optional Roles

| Role | Purpose | |------|---------| | roles/artifactregistry.repoAdmin | Required for auto-remediation of Artifact Registry (cleanup old images) |

Credential Security

Envelope Encryption

Cloud Guardian uses envelope encryption for stored credentials:

  1. A random Data Encryption Key (DEK) is generated per credential
  2. The credential JSON is encrypted with AES-256-GCM using the DEK
  3. The DEK is wrapped (encrypted) using Cloud KMS
  4. Only the wrapped DEK, nonce, and ciphertext are stored in Firestore

The raw service account key is never stored in plaintext. It exists only in memory during scan operations.

Credential Lifecycle

  1. Upload — Raw JSON key uploaded via CreateConnector API
  2. Encrypt — Envelope encrypted and stored
  3. Display — API returns credentials_ref: "stored://" (never the actual key)
  4. Scan — Decrypted in memory, used for GCP API calls, then discarded
  5. Delete — Both connector and encrypted credential are removed

Testing the Connection

After creating a connector, use Test Connection to verify all required permissions:

| Permission Tested | API Call | |-------------------|----------| | resourcemanager.projects.get | Projects API | | run.services.list | Cloud Run API | | secretmanager.secrets.list | Secret Manager API | | artifactregistry.repositories.list | Artifact Registry API |

IAM Propagation Delay

After granting IAM roles, there is a propagation delay of 3-30 seconds. If the test connection fails immediately after granting roles, wait 30 seconds and retry.

Multi-Project Setup

Cloud Guardian supports scanning multiple GCP projects under a single organization:

  1. Create a service account in each target project
  2. Create a connector for each project
  3. Link each connector to your organization via Projects

Alternatively, use Clone Credentials to copy an encrypted credential from one connector to another without decrypting it.

Configuring Checks

Each built-in check can be customized per organization:

  • Enable/Disable — Skip checks that don't apply to your workloads
  • Thresholds — Adjust numeric thresholds (e.g., max image versions, storage limits)
  • Severity — Override the default severity level

Configure checks in Policies > Checks in the dashboard.