gcp-iam-policies

Search Google Cloud IAM policies using Cloud Asset Inventory API and output one row per role and member.

Syntax

gcp-iam-policies [profile=STRING] [scope=STRING] [types=STRING] [query=STRING] [limit=INT]

Options

profile=STRING: Optional. Google Cloud connect profile. If multiple profiles are separated by commas, each profile is queried in turn and distinguished by the profile field. If not specified, all Google Cloud connect profiles you can use are queried. If an error occurs on a profile, rows already returned remain, the remaining profiles are skipped and the query ends with an error.
scope=STRING: Optional. projects/{id} (or projects/{number}), folders/{number} or organizations/{number}. Policies set on resources in the scope and below it are returned. Project of JSON key is used if not specified.
types=STRING: Optional. Comma separated asset types of the resource the policy is attached to. Regular expression is supported. e.g. cloudresourcemanager.googleapis.com/Organization, storage.googleapis.com/Bucket. See the asset type table of gcp-assets for common types.
query=STRING: Optional. Search query of IAM policies. e.g. policy:user@example.com, policy:roles/owner, memberTypes:user, policy.role.permissions:storage.buckets.update. See Searching IAM policies.
limit=INT: Optional. Max number of rows per profile. Positive integer. All rows are returned if not specified.

Output fields

Field	Type	Name	Description
profile	String	Profile	Connect profile name
member	String	Member	e.g. user:user@example.com, allUsers
member_type	String	Member type	Prefix of member. e.g. user, serviceAccount, group, domain, allUsers
role	String	Role	e.g. roles/owner
asset_type	String	Asset type	Asset type of the resource
resource	String	Resource	Full resource name the policy is attached to
project_id	String	Project ID	User assigned project ID. Empty if the resource does not belong to a project (e.g. organization or folder)
project_name	String	Project name	Display name of the project. Empty if the resource does not belong to a project (e.g. organization or folder)
condition_title	String	Condition title	Title of IAM condition. Only conditional bindings have a value
condition_expression	String	Condition expression	CEL expression of IAM condition. e.g. request.time < timestamp("2026-12-31T00:00:00Z")
condition_description	String	Condition description	Description of IAM condition
project	String	Project	Project in projects/{number} form. Empty for organization and folder policies
folders	List	Folders	Ancestor folders in folders/{number} form
organization	String	Organization	Organization in organizations/{number} form
matched_permissions	List	Matched permissions	Permissions of the role matched by policy.role.permissions query

Error codes

Parse errors

Error message	Cause	Solution
No available Google Cloud profile found.	Wrong profile code or no permission to use the profile	Specify the connect profile code in the profile option and check the profile permission
Invalid scope: {scope}	Invalid scope format, or a folder or organization specified by name	Specify an ID or number after projects/, folders/ or organizations/
limit should be positive integer: {limit}	limit is 0 or less, or not a number	Specify a positive integer

Runtime errors

Error message	Cause	Solution
HTTP 403: PERMISSION_DENIED - The caller does not have permission	No Cloud Asset Viewer role on the scope	Check with gcp-check-permissions and grant the role on the scope
HTTP 403: PERMISSION_DENIED - Cloud Asset API has not been used in project ...	Cloud Asset API is not enabled in the project of the service account	Enable Cloud Asset API in the project the service account belongs to
HTTP 400: INVALID_ARGUMENT - Invalid query syntax, Unsupported field: ...	Invalid query syntax or unsupported field	Fix the query referring to the supported fields in the message and the query syntax document
HTTP 400: INVALID_ARGUMENT - Please quote term ... with double quotes	A query term with special characters is not quoted	Enclose the term with "
token exchange failed, HTTP 400: Invalid grant	Wrong JSON key, or the service account or key was deleted	Create a new key and update the connect profile

Description

Searches IAM policies set directly on resources in the scope using searchAllIamPolicies API of Cloud Asset Inventory. A policy has multiple role bindings and each binding has multiple members, so the command outputs one row per role and member combination. Permissions inherited from an ancestor folder or organization are returned as rows of that ancestor resource.

member_type distinguishes users (user), service accounts (serviceAccount), groups (group), domains (domain) and public access (allUsers, allAuthenticatedUsers), which helps to review excessive or public permissions.

Like gcp-assets, the command fills project ID and name (project_id, project_name). Folders and organization are returned as numbers only.

Note

Results are the recent policies collected by Google Cloud and permission data may be reflected late. Group members are not expanded, so check actual users of group rows in Google Workspace or similar.

Examples

Example: Permissions in the organization

Situation: Find which types of members have permissions on which resources in the organization.

gcp-iam-policies profile=gcp scope=organizations/123456789012
| stats count by asset_type, member_type

Expected result:

asset_type	member_type	count
cloudresourcemanager.googleapis.com/Organization	user	4
cloudresourcemanager.googleapis.com/Organization	domain	2
cloudresourcemanager.googleapis.com/Organization	serviceAccount	2
cloudresourcemanager.googleapis.com/Project	user	3

Interpretation: Organization level permissions are inherited by all projects below, so review them carefully.

Example: Owners

Situation: Check members with the owner role (roles/owner) by project.

gcp-iam-policies profile=gcp scope=organizations/123456789012 query="policy:roles/owner"
| fields project_id, resource, role, member

Expected result:

project_id	resource	role	member
my-project-123456	//cloudresourcemanager.googleapis.com/projects/my-project-123456	roles/owner	user:user@example.com

Interpretation: Owners can change and delete all resources. Check that the role is not granted more than necessary.

Example: Public access

Situation: Find resources open to everyone.

gcp-iam-policies profile=gcp scope=organizations/123456789012
| search member_type == "allUsers" or member_type == "allAuthenticatedUsers"
| fields project_id, asset_type, resource, role, member

Interpretation: If any rows are returned, check whether the public access is intended. If not, revoke the permission on the resource.

Example: Conditional permissions

Situation: Check permissions with conditions such as time limits.

gcp-iam-policies profile=gcp scope=organizations/123456789012
| search isnotnull(condition_expression)
| fields resource, role, member, condition_title, condition_expression

Interpretation: Conditional permissions whose expiry time has passed are no longer effective and can be cleaned up.

Example: Roles that include a specific permission

Situation: Check members who can get projects (resourcemanager.projects.get) and the roles that grant the permission.

gcp-iam-policies profile=gcp scope=organizations/123456789012 query="policy.role.permissions:resourcemanager.projects.get"
| fields resource, role, member, matched_permissions

Interpretation: matched_permissions shows the permissions matched in the role of the row.