Connect a Google Cloud project or organisation

This page describes the identity to give Ctadel on Google Cloud, in single-project or organisation mode, the roles to grant it and what the collector reads.

What you need

A JSON credential file of one of two kinds:

Kind	When to choose it
Service account key	The usual case. The file holds a private key and the project id of the service account.
external_account file (workload identity federation)	When your organisation forbids creating service account keys (the iam.disableServiceAccountKeyCreation constraint). The file holds neither a private key nor a project id.

The file is pasted as is into the "Service Account Key (JSON)" field. The credentials are not checked when the account is saved: the application only reads the project identifier from the file, without calling Google Cloud. The collector requests the cloud-platform scope at the first scan; a refused file then shows in the account's state.

Single project or organisation

The "Organization ID" field decides the mode:

• empty: Ctadel reads the service account's project, the one named in the file;
• organizations/<number>: Ctadel searches every active project the identity can see, walks its folder ancestry up to the organisation, and reads those that belong to it. Projects that are visible but belong to another organisation are skipped. The IAM policies of the folders met on the way are read, since a role granted on a folder applies to every project below it.

An id that is not an organisation number (a folder, a domain) is refused rather than ignored.

Roles to grant

At organisation level in organisation mode, at project level in single-project mode:

Role	What it gives
roles/viewer	The general inventory, including VPC firewall rules and global and regional network firewall policies.
roles/iam.securityReviewer	IAM policies of projects, folders and the organisation, service accounts.
roles/browser	The organisation hierarchy: project search and folder reads. Organisation mode only.
roles/monitoring.viewer, roles/logging.viewer	Alert policies and log sinks.
roles/accessapproval.viewer	Access approval settings.
roles/policyanalyzer.activityAnalysisViewer	Last authentication of service accounts, to detect dormant ones.
roles/serviceusage.serviceUsageViewer	The list of enabled APIs per project.

Enable on the service account's host project the cloudresourcemanager, compute, container, iam, logging, monitoring, dns, cloudkms, cloudfunctions, run, sqladmin, storage, bigquery, accessapproval, essentialcontacts, policyanalyzer, serviceusage and securitycenter APIs, plus those of the services you use.

Content analyses

Analysis	Permissions to grant	What Ctadel does
Virtual machine disks	roles/compute.storageAdmin restricted by condition to the ctadel-managed label, and roles/compute.instanceAdmin.v1 on the project hosting the scanner machine.	A snapshot of the disk, labelled ctadel-managed, is mounted on a temporary scanner machine, then deleted.
Cloud SQL databases	Cloud SQL administration rights on the instance's project: cloning, changing authorised networks, deletion.	The instance is cloned as ctadel-dspm-<timestamp>, the clone accepts only the egress address of your Ctadel instance, it is read then deleted. The original instance is not modified.
Cloud Storage buckets	An object read role on the buckets.	Objects are read in place with the same credential file.
BigQuery datasets	roles/bigquery.dataViewer on the datasets.	The first hundred rows of each table are read in place through the read-only API; no query is run and nothing is copied.
GKE clusters	A read role on the clusters.	A kubeconfig is built with a short-lived OAuth2 token of the service account, then the cluster objects are read.

Declaring the account in Ctadel

1. Open "Settings", tab "Integrations", sub-tab "Cloud Providers", then "Add account" on the Google Cloud Platform row.
2. Enter a "Label".
3. Leave "Organization ID" empty, or enter organizations/<number>.
4. Paste the JSON file into "Service Account Key (JSON)".
5. Click "Create".

"Discover" makes no call to Google Cloud: it shows the project id read from the file.

What the collector reads

Family	Resources read
Organisation and projects	Organisation settings, access approval, IAM policies of the organisation, folders and projects, project metadata, enabled APIs, Security Command Center.
Identities	Service accounts, their keys and their last authentication.
Compute	Compute Engine instances and their disks, GKE clusters, Cloud Functions, Cloud Run, Cloud Build, Artifact Registry.
Network	VPC networks and subnets, firewall rules and network firewall policies, load balancers, Cloud Armor, DNS zones.
Data	Cloud Storage buckets, Cloud SQL instances, BigQuery, Memorystore, Pub/Sub, Dataflow, Dataproc, Composer.
Keys and logs	Cloud KMS keys, log sinks, Monitoring alert policies.
AI	Vertex AI: models, endpoints and related resources, per location.

Limitations

• Hierarchical firewall policies (organisation, folder) are not read; only global and regional network policies are.
• With an identity federation file, single-project mode is not possible: the file carries no project id and the form does not ask for one. Enter an "Organization ID".
• A service account's dormancy is derived from the age of its oldest user-managed key; an account without such a key stays "unknown".
• If the IAM policy of a bucket or an Artifact Registry repository cannot be read, its visibility stays unknown, unless an ACL declares it public.
• A Vertex AI location that refuses the call (API not enabled, product unavailable) is skipped; a permission refusal is reported as such, not as "nothing".
• A folder that cannot be read while walking the hierarchy does not exclude the project below it.
• Reading audit logs for detection (roles/logging.privateLogViewer role) is under internal validation, not available to customers.