Connect a Google Cloud account

Authorize CISAPP read-only on a Google Cloud (GCP) environment through a service account that CISAPP impersonates, to inventory cloud resources and report security posture findings.

Access: organization administrator. Beta feature; the connector must be enabled on your platform.

How it works

No key is exchanged or stored. You create a read-only service account in one of your projects and you allow the CISAPP platform service account to impersonate it (the "Service Account Token Creator" role, on that service account only). At each synchronization, CISAPP obtains a short-lived access token (about one hour) from Google on behalf of your service account and reads your configuration. This token is never stored: it stays in CISAPP's memory and is reused for at most one hour (refreshed 5 minutes before it expires). Removing the authorization on the Google Cloud side prevents new tokens from being obtained: access ends at the latest when the current token expires (one hour at most), subject to Google IAM propagation. For an immediate stop on the CISAPP side, use Disconnect.

Prerequisites

• Be an organization administrator in CISAPP.
• Have the rights in Google Cloud to create a service account, create a custom role and grant IAM roles: for example IAM Admin on the organization (or on the project), or project owner. Without a Google Cloud organization, these rights are needed on every project to analyze.
• Have the gcloud CLI signed in with an authorized account, or Cloud Shell.
• A service account can only be connected to one CISAPP organization. Several service accounts (so several connections) remain possible within one CISAPP organization.
• The service account must be one you created (name@project.iam.gserviceaccount.com). Google-managed accounts (service agents gcp-sa-… and legacy Google service agents, the default Compute account …-compute@developer.gserviceaccount.com, the App Engine account) and legacy domain-named projects (example.com:project) are not supported. It must not belong to CISAPP's own project.

Set up Google Cloud

The commands below are the ones in the CISAPP setup panel. The panel shows them already pre-filled with your connection's verification token and the CISAPP service account address: copy them from the panel rather than using the generic values on this page (<VERIFICATION_TOKEN> and <CISAPP_SERVICE_ACCOUNT>).

1. Open My company → Connectors, then Connect on the Google Cloud card. The Set up Google Cloud panel shows two values to copy:

   • the CISAPP service account (platform): the address to authorize;
   • the verification token: specific to this connection, in the form cisapp-verify- followed by 32 hexadecimal characters.

2. Adapt the variables. PROJECT_ID is the project that will host the service account (its "home project"), ORG_ID is the numeric identifier of your organization (not needed without an organization).

   PROJECT_ID="my-project-id"
   SA_NAME="cisapp-readonly"
   SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"
   ORG_ID="123456789012"

3. Create the service account, with the verification token as its description: it proves that you control this account.

   gcloud iam service-accounts create "$SA_NAME" --project="$PROJECT_ID" \
     --display-name="CISAPP read-only" \
     --description="<VERIFICATION_TOKEN>"

   If the service account already exists, only update its description:

   gcloud iam service-accounts update "$SA_EMAIL" --project="$PROJECT_ID" \
     --description="<VERIFICATION_TOKEN>"

4. Allow CISAPP to impersonate the service account, on that service account only. Never grant it on the project, a folder or the organization: CISAPP refuses the connection if this role is granted more widely.

   gcloud iam service-accounts add-iam-policy-binding "$SA_EMAIL" \
     --project="$PROJECT_ID" \
     --member="serviceAccount:<CISAPP_SERVICE_ACCOUNT>" \
     --role="roles/iam.serviceAccountTokenCreator"

5. Save the custom role definition in a role.yaml file. It only contains metadata read permissions (see the list below): no data access.

   title: CISAPP Posture Reader
   description: Read-only metadata access for CISAPP security posture scans. No data-plane access.
   stage: GA
   includedPermissions:
   - resourcemanager.projects.get
   - resourcemanager.projects.getIamPolicy
   - compute.instances.list
   - compute.firewalls.list
   - compute.networks.list
   - compute.subnetworks.list
   - compute.projects.get
   - storage.buckets.list
   - storage.buckets.getIamPolicy
   - cloudsql.instances.list
   - container.clusters.list
   - iam.serviceAccounts.get
   - iam.serviceAccounts.list
   - iam.serviceAccountKeys.list
   - cloudfunctions.functions.list
   - cloudfunctions.functions.getIamPolicy
   - run.locations.list
   - run.services.list
   - run.services.getIamPolicy
   - cloudkms.locations.list
   - cloudkms.keyRings.list
   - cloudkms.cryptoKeys.list
   - bigquery.datasets.get
   - bigquery.datasets.getIamPolicy
   - serviceusage.services.list

6. Create the role and grant it to the service account. The role must cover the service account's home project (it must be able to read itself) and the projects to analyze.

   • With a Google Cloud organization: a single grant at the organization level covers all its projects, including the home project.

     gcloud iam roles create cisappPostureReader --organization="$ORG_ID" \
       --file=role.yaml
     gcloud organizations add-iam-policy-binding "$ORG_ID" \
       --member="serviceAccount:$SA_EMAIL" \
       --role="organizations/$ORG_ID/roles/cisappPostureReader"

   • Without an organization: project by project. Replace project-a project-b with your projects, without forgetting the service account's home project. The role is created in each one.

     for P in project-a project-b; do
       gcloud iam roles create cisappPostureReader --project="$P" \
         --file=role.yaml
       gcloud projects add-iam-policy-binding "$P" \
         --member="serviceAccount:$SA_EMAIL" \
         --role="projects/$P/roles/cisappPostureReader"
     done

7. Enable the APIs in the service account's home project: its calls are counted and rate-limited there.

   gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com serviceusage.googleapis.com \
     --project="$PROJECT_ID"

   Product APIs (Compute Engine, Cloud Storage, Cloud SQL…) do not have to be enabled for CISAPP: a product that is disabled in a project simply has nothing to inventory.

Fallback predefined roles

If your organization forbids custom roles, grant these predefined roles to the service account instead, on the organization or on each project (without forgetting the home project):

• roles/browser
• roles/compute.networkViewer
• roles/cloudsql.viewer
• roles/container.clusterViewer
• roles/iam.serviceAccountViewer
• roles/cloudfunctions.viewer
• roles/run.viewer
• roles/cloudkms.viewer
• roles/bigquery.metadataViewer
• roles/serviceusage.serviceUsageViewer
• roles/storage.bucketViewer

Limit: these roles do not allow reading bucket access policies (IAM). The public bucket check then stays "unknown": it neither creates nor resolves a finding.

Connect in CISAPP

1. In the setup panel, click I'm done.
2. Enter the service account email (for example cisapp-readonly@my-project.iam.gserviceaccount.com).
3. Optionally enter the projects to analyze, one identifier per entry (50 at most). Empty: every active project the service account can read, up to a cap set by the platform (100 by default); beyond it only the first ones are analyzed and the synchronization reports it.
4. Verify access: CISAPP checks that the service account exists, that it can impersonate it, that the token is in its description and that the projects are readable.
5. Check the displayed service account (its numeric identifier), then Connect. The connection becomes active and the first synchronization starts.

If you close the wizard before confirmation, the connection stays Pending and the setup panel is resumed from its record (the verification token stays the same). A connection left pending for more than 7 days without activity is deleted automatically.

Google IAM permissions propagate with a slight delay (a few seconds to a few minutes). If verification fails right after the commands, wait and try again. Likewise, the first synchronization may report a few partial "not granted" errors: the next one fixes them.

Once the connection is active, the list of projects can be changed from the connection record (Edit scope); the service account email cannot.

What CISAPP collects

CISAPP only performs reads (GET requests; reading IAM policies uses the Google API POST method, without changing anything) and only reads configuration, never content. For each analyzed project:

• Google Cloud projects (identifier, state) and the project IAM policy, summarized as counters (no member address is kept);
• Compute Engine: instances, VPC firewall rules, networks and subnets;
• Cloud Storage: buckets (configuration and IAM access rules, not the objects);
• Cloud SQL: instances;
• Google Kubernetes Engine (GKE): clusters;
• service accounts and their user-managed keys (metadata: age, state);
• Cloud Functions and Cloud Run services (configuration and who may invoke them);
• Cloud KMS: encryption keys (rotation metadata);
• BigQuery: datasets (configuration and public access);
• the list of APIs enabled in each project.

Resources appear in the Operational Safety → Cloud inventory menu entry and its Map view, with their region and location. A product that the service account cannot read is reported as not granted in the synchronization result.

What CISAPP never reads

CISAPP changes nothing in your environment. The role includes no write permission and no data read permission. CISAPP never reads, and therefore never stores:

• bucket content (objects), BigQuery tables, rows and queries;
• service account key material (no key is created, downloaded or used), secrets (Secret Manager), KMS keys themselves (no encryption, decryption or signing);
• environment variables and secrets of Cloud Functions and Cloud Run services, container images and arguments;
• GKE cluster credentials (certificates, tokens), passwords, certificates and flag values of Cloud SQL instances;
• disk encryption keys, labels, serial port output, screenshots and guest attributes;
• public IP addresses themselves (only the existence of a public address is kept) and the addresses of IAM policy members.

Compute instance and project metadata (for example startup scripts, SSH keys) is read for three flags only: enable-oslogin, block-project-ssh-keys and serial-port-enable. Google does not allow requesting a single key: the items are therefore requested as key/value pairs and their values pass through memory while the response is read; only these three flags are kept and nothing else is converted, stored or logged.

Posture findings

Findings appear in security findings with the Google Cloud posture source. A rule only triggers when the information is certain: an unknown state (product not granted, unreadable value, value missing from the response) neither creates nor resolves a finding. 20 rules are evaluated.

Finding title	Severity
Basic Owner or Editor role granted in the project	High; medium if only users hold the role
Project IAM policy open to allUsers or allAuthenticatedUsers	Critical
User-managed service account key older than 90 days	Medium
Compute instance exposed with a public IP address	Medium
Instance using the default service account with full API access	High
OS Login disabled on the instance	Medium
Serial console access enabled on the instance	Medium
Firewall rule open to the Internet on an administration port	High
Firewall rule open to the Internet on a database port	High
Firewall rule allowing all traffic from the Internet	Critical
Publicly accessible storage bucket	Critical; high if only read roles are public
Uniform bucket-level access disabled	Medium
Cloud SQL instance reachable from the Internet	Critical
Cloud SQL instance not enforcing TLS encryption	High; medium if the instance has no public address
Automated backups disabled on the Cloud SQL instance	Medium
Legacy ABAC authorization enabled on the GKE cluster	High
GKE control plane endpoint open to the Internet	High
Publicly invocable serverless function or service	Medium; high if ingress is open to all and the default Compute account runs it
KMS encryption key without automatic rotation	Medium
Publicly accessible BigQuery dataset	Critical

Details:

• Firewall: only classic VPC ingress rules that are enabled are evaluated. Administration = ports 22 and 3389; databases = 1433, 1521, 3306, 5432, 6379, 9200, 9300, 11211 and 27017. A rule that opens every port is reported once, by the "all traffic" rule.
• Serverless functions and services: public access is often intended (public API); the finding is advisory. An ingress limited to the internal network is considered compliant.
• Buckets: only the IAM policy is evaluated. Legacy object or bucket ACLs are not read.
• KMS: only symmetric keys that can be rotated are concerned; a rotation period longer than 365 days is also reported.

Limits

• Organization policies (for example compute.requireOsLogin, compute.disableSerialPortAccess, the ban on public bucket access) and hierarchical or network firewall policies are not evaluated: a finding may be neutralized at your organization level, and a deny rule is not taken into account. Findings describe each resource's own configuration.
• Audit policies inherited from a folder or the organization are not visible for a project attached to an organization.
• Google IAM permissions are eventually consistent: a role granted or removed may take a few minutes to take effect.
• Two CISAPP organizations can see the same projects through two different service accounts: the connection is exclusive per service account, not per project.
• An empty scope is capped; an inaccessible project is reported and its resources are not removed from the inventory.
• If the service account sees more projects than the cap (100 by default) in "all projects" mode, only the first ones are analyzed and automatic finding resolution is paused for the whole connection: findings are still created and updated, but none is resolved, and the synchronization reports it. List the projects to analyze explicitly to restore it.

Revoke access

• On the Google Cloud side: remove the "Service Account Token Creator" role granted to CISAPP on your service account. CISAPP can no longer obtain a new token; the token already issued stays usable until it expires (one hour at most), subject to Google IAM propagation.

  gcloud iam service-accounts remove-iam-policy-binding "$SA_EMAIL" \
    --project="$PROJECT_ID" \
    --member="serviceAccount:<CISAPP_SERVICE_ACCOUNT>" \
    --role="roles/iam.serviceAccountTokenCreator"

• On the CISAPP side, Disconnect deletes the connection and its cloud inventory, marks its posture findings as resolved and drops the token kept in memory: this is the immediate stop on the CISAPP side. There is nothing to revoke at Google: no credential is stored. Then remove the impersonation role, and delete the service account and the custom role if they are no longer needed.

Common issues

Message	What to do
The Google Cloud connector is unavailable on this instance	The platform service account is not configured on your platform yet: contact support.
Google Cloud refused access	See the detailed causes below.
This service account is already connected by another CISAPP organization, or does not match this connection's account	A service account has a single connection: disconnect it from the other CISAPP organization first. Otherwise the account was deleted then recreated (new identifier: it is no longer the service account connected earlier): check the email you entered, disconnect the connection and reconnect it. The same message appears if the connection was changed while it was being verified: reload the page.
Unable to confirm: this service account changed since the verification	Start the verification again.
Too many attempts	Too many connection attempts in a short time (10 per minute at most): wait a minute.
The email is not valid (message under the field)	Enter a service account you created (name@project.iam.gserviceaccount.com). Google-managed accounts, including the legacy Google service agents, are refused. This is an input error, not a refusal from Google Cloud.

When Google Cloud refuses access, verification stops at the first cause it meets, in this order:

Cause	What to do
The service account belongs to CISAPP's project	Create it in one of your projects.
CISAPP cannot impersonate this service account	Check the email and that CISAPP's service account holds roles/iam.serviceAccountTokenCreator on this service account. Google does not distinguish a missing account from a missing permission. Wait for IAM propagation.
The service account cannot read itself	Grant it the custom role on its home project.
Enable an API in the home project	Enable cloudresourcemanager, iam and serviceusage in the home project (step 7).
A VPC Service Controls perimeter blocks the service account	Allow the service account in the perimeter.
The service account is not found, does not match the email, does not belong to its project or is disabled	Check the email and re-enable the service account.
The verification token was not found in the service account description	Update the description with the exact value from the panel (no extra text). The token is only checked while the connection is not active.
roles/iam.serviceAccountTokenCreator is granted on the project, a folder or the organization	Remove these wide grants and grant the role on the service account only.
The service account sees no project, or a project is not readable	Grant the custom role on the projects to analyze (or on the organization) and check that each project is active.

After connecting, in synchronizations:

Symptom	Likely cause
Product "not granted" in the result	A permission of the role is missing on that project: grant it on that project or on the organization.
SERVICE_DISABLED error in the result	An API of the service account's home project is disabled (step 7).
Connection in error "credentials refused"	Impersonation is refused (role removed, account deleted or disabled): restore it, then start the verification again from the record.
Connection in error "the service account was replaced"	The service account was recreated: disconnect, then reconnect the account.
Project limit reached	Explicitly select the projects to analyze (while the list is empty, no finding is resolved automatically).

Expected result

The connection is active, the cloud inventory is populated and Google Cloud posture findings appear in CISAPP.

See also: Configure connectors.