Cloud Asset Inventory insights can help to detect potential risks in your asset
configurations, and help you to improve your security posture. It's part of the
Recommender service, and is provided as the
google.cloudasset.asset.Insight
insight type.
Insights are specific anomalies which require further analysis to determine appropriate action. They are generated daily, based on a snapshot of the data stored in Cloud Asset Inventory.
The insights provided by Cloud Asset Inventory are based on the IAM policies associated with your organization's resources.
Before you begin
Before you can begin using asset insights, you must complete the following steps.
Make sure that your account has the following permissions:
recommender.cloudAssetInsights.get
recommender.cloudAssetInsights.list
recommender.cloudAssetInsights.update
You can grant these permissions individually, or you can grant one of the following roles.
Cloud Asset Insights Viewer (
roles/recommender.cloudAssetInsightsViewer
) roleCloud Asset Insights Admin (
roles/recommender.cloudAssetInsightsAdmin
) role
Limitations
These insights don't consider group memberships or service accounts as part of their findings, and shouldn't be considered an exhaustive list of matching vulnerabilities.
Individual insights include a sampling of matching IAM policies capped at 100 distinct policies. All matching policies can be retrieved by searching for IAM allow policies on resources.
Request asset insights
The easiest way to request asset insights is to list them, as shown in the following steps. For other types of insights interactions, see Use the API - Insights.
gcloud
gcloud recommender insights list \ --SCOPE \ --location=global \ --insight-type=google.cloudasset.asset.Insight \ --filter="insightSubtype:SUBTYPE" \
Provide the following values:
-
SCOPE
: Use one of the following values:-
project=PROJECT_ID
, wherePROJECT_ID
is the ID of the project you want insights for. -
folder=FOLDER_ID
, whereFOLDER_ID
is the ID of the folder you want insights for.How to find the ID of a Google Cloud folder
Google Cloud console
To find the ID of a Google Cloud folder, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher list box in the menu bar.
- Select your organization from the list box.
- Search for your folder name. The folder ID is shown next to the folder name.
gcloud CLI
You can retrieve the ID of a Google Cloud folder that's located at the organization level with the following command:
gcloud resource-manager folders list \ --organization=$(gcloud organizations describe ORGANIZATION_NAME \ --format="value(name.segment(1))") \ --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \ --format="value(ID)"
Where TOP_LEVEL_FOLDER_NAME is a partial or full string match for the folder's name. Remove the
--format
flag to see more information about the found folders.The previous command doesn't return the IDs of subfolders within folders. To do so, run the following command using a top level folder's ID:
gcloud resource-manager folders list --folder=FOLDER_ID
-
-
organization=ORGANIZATION_ID
, whereORGANIZATION_ID
is the ID of the organization you want insights for.How to find the ID of a Google Cloud organization
Google Cloud console
To find the ID of a Google Cloud organization, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher list box in the menu bar.
- Select your organization from the list box.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve the ID of a Google Cloud organization with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-
-
-
BILLING_PROJECT_ID
: Optional. The project ID that the default Cloud Asset Inventory service agent is in that has permissions to manage your billing and quota. Read more about setting the billing project. -
SUBTYPE
: The asset insight subtype. One of the following values:-
EXTERNAL_MEMBER
: Detects IAM policies containing users or groups which belong to a domain outside of your organization's domains. -
EXTERNAL_POLICY_EDITOR
: Detects IAM policies containing users or groups outside of your organization's domains that are granted permission to modify IAM policies. -
EXTERNAL_CLOUD_STORAGE_OBJECT_VIEWER
: Detects IAM policies containing users or groups outside of your organization's domains that are granted permission to get or list storage objects (storage.objects.list
orstorage.objects.get
permission). -
EXTERNAL_SERVICE_ACCOUNT_IMPERSONATOR
: Detects IAM policies containing users or groups outside of your organization's domains that are granted permission to impersonate service accounts. -
TERMINATED_MEMBER
: Detects IAM policies containing users or groups with deactivated, deleted, or purged accounts. -
PUBLIC_IAM_POLICY
: Detects IAM policies containing all users or all authenticated users. -
OWNER_TERMINATED_PROJECT
: Detects projects which do not contain any active users or groups in the project's IAM policy.
-
If not specified, all subtypes are returned.
See the gcloud CLI reference for all options.
Example
Run the following command to list insights for the my-project
project.
gcloud recommender insights list \ --project=my-project \ --location=global \ --insight-type=google.cloudasset.asset.Insight
Example response
INSIGHT_ID: 00000000-0000-0000-0000-000000000000 CATEGORY: SECURITY INSIGHT_STATE: ACTIVE LAST_REFRESH_TIME: 2024-01-30T00:00:00Z SEVERITY: LOW INSIGHT_SUBTYPE: EXTERNAL_MEMBER DESCRIPTION: Domain example.com detected in 1 IAM policies
REST
HTTP method and URL:
GET https://recommender.googleapis.com/v1/SCOPE_PATH/locations/global/insightTypes/google.cloudasset.asset.Insight/insights
Headers:
X-Goog-User-Project: BILLING_PROJECT_ID
Provide the following values:
-
SCOPE_PATH
: Use one of the following values:The allowed values are:
-
projects/PROJECT_ID
, wherePROJECT_ID
is the ID of the project you want insights for. -
projects/PROJECT_NUMBER
, wherePROJECT_NUMBER
is the number of the project you want insights for.How to find a Google Cloud project number
Google Cloud console
To find a Google Cloud project number, complete the following steps:
-
Go to the Welcome page in the Google Cloud console.
- Click the switcher list box in the menu bar.
-
Select your organization from the list box, and then search for your project name. The project name, project number, and project ID are shown near the Welcome heading.
Up to 4,000 resources are displayed. If you don't see the project you're looking for, go to the Manage resources page and filter the list using the name of that project.
gcloud CLI
You can retrieve a Google Cloud project number with the following command:
gcloud projects describe PROJECT_ID --format="value(projectNumber)"
-
-
folders/FOLDER_ID
, whereFOLDER_ID
is the ID of the folder you want insights for.How to find the ID of a Google Cloud folder
Google Cloud console
To find the ID of a Google Cloud folder, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher list box in the menu bar.
- Select your organization from the list box.
- Search for your folder name. The folder ID is shown next to the folder name.
gcloud CLI
You can retrieve the ID of a Google Cloud folder that's located at the organization level with the following command:
gcloud resource-manager folders list \ --organization=$(gcloud organizations describe ORGANIZATION_NAME \ --format="value(name.segment(1))") \ --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \ --format="value(ID)"
Where TOP_LEVEL_FOLDER_NAME is a partial or full string match for the folder's name. Remove the
--format
flag to see more information about the found folders.The previous command doesn't return the IDs of subfolders within folders. To do so, run the following command using a top level folder's ID:
gcloud resource-manager folders list --folder=FOLDER_ID
-
-
organizations/ORGANIZATION_ID
, whereORGANIZATION_ID
is the ID of the organization you want insights for.How to find the ID of a Google Cloud organization
Google Cloud console
To find the ID of a Google Cloud organization, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher list box in the menu bar.
- Select your organization from the list box.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve the ID of a Google Cloud organization with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-
-
-
BILLING_PROJECT_ID
: The project ID that the default Cloud Asset Inventory service agent is in that has permissions to manage your billing and quota. Read more about setting the billing project.
Command examples
Run on of the following commands to list insights for the my-project
project.
curl (Linux, macOS, or Cloud Shell)
curl -X GET \ -H "X-Goog-User-Project: BILLING_PROJECT_ID" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ https://recommender.googleapis.com/v1/projects/my-project/locations/global/insightTypes/google.cloudasset.asset.Insight/insights
PowerShell (Windows)
$cred = gcloud auth print-access-token $headers = @{ "X-Goog-User-Project" = "BILLING_PROJECT_ID"; "Authorization" = "Bearer $cred" } Invoke-WebRequest ` -Method GET ` -Headers $headers ` -Uri "https://recommender.googleapis.com/v1/projects/my-project/locations/global/insightTypes/google.cloudasset.asset.Insight/insights" | Select-Object -Expand Content
Example response
{ "name": "organizations/000000000000/locations/global/insightTypes/google.cloudasset.asset.Insight/insights/00000000-0000-0000-0000-000000000000", "description": "Domain example.com detected in 1 IAM policies", "content": { "domain": "example.com", "policyCount": 1, "policySearchQuery": "policy: example.com", "matchedPolicies" :[ { "resource" :"//cloudresourcemanager.googleapis.com/projects/000000000000", "project" :"projects/000000000000", "matchedBindings" :[ { "role" :"roles/viewer", "matchedMembers" :[ "user:example@example.com" ] } ] } ] }, "lastRefreshTime": "2024-01-30T00:00:00Z", "observationPeriod": "0s", "stateInfo": { "state": "ACTIVE" }, "category": "SECURITY", "targetResources": [ "//cloudresourcemanager.googleapis.com/organizations/000000000000" ], "insightSubtype": "EXTERNAL_MEMBER", "etag": "\"00000000000\"", "initialRefreshTime": "2024-01-30T00:00:00Z" }
Interpreting insight responses
In addition to the standard insight attributes, asset insights provide several specialized subtypes and fields.
Insight subtypes
The asset insight subtypes are as follows:
EXTERNAL_MEMBER
: Detects IAM policies containing users or groups which belong to a domain outside of your organization's domains.EXTERNAL_POLICY_EDITOR
: Detects IAM policies containing users or groups outside of your organization's domains that are granted permission to modify IAM policies.EXTERNAL_CLOUD_STORAGE_OBJECT_VIEWER
: Detects IAM policies containing users or groups outside of your organization's domains that are granted permission to get or list storage objects (storage.objects.list
orstorage.objects.get permission
).EXTERNAL_SERVICE_ACCOUNT_IMPERSONATOR
: Detects IAM policies containing users or groups outside of your organization's domains that are granted permission to impersonate service accounts.TERMINATED_MEMBER
: Detects IAM policies containing users or groups with deactivated, deleted, or purged accounts.PUBLIC_IAM_POLICY
: Detects IAM policies containing all users or all authenticated users.OWNER_TERMINATED_PROJECT
: Detects projects which don't contain any active users or groups in the project's IAM policy.
Additional content fields
In addition to the standard fields in the response, asset insights provide
several specialized fields in the content
field.
user
: The user email address detected in the members of the policy bindings for this insight. This field is included in theTERMINATED_MEMBER
subtype.domain
: The domain detected in the members of the policy bindings of this insight. This field is included in theEXTERNAL_MEMBER
,EXTERNAL_POLICY_EDITOR
,EXTERNAL_CLOUD_STORAGE_OBJECT_VIEWER
, andEXTERNAL_SERVICE_ACCOUNT_IMPERSONATOR
subtypes.assetName
: The asset name for which access was detected in this insight. This field is included in theOWNER_TERMINATED_PROJECT
andPUBLIC_IAM_POLICY
subtypes.policyCount
: The total number of distinct IAM policies in which matching members were detected for this insight. This field is included for all asset insight subtypes.matchedPolicies
: A sampling of the IAM policies matching the detected insight. Matching policies only include the subset of bindings and binding members which match the detected insight. This field is included for all asset insight subtypes.policySearchQuery
: A query which can be used with the Cloud Asset Inventory IAM policy search API to retrieve the relevant policies in real time.