This topic shows you how to use Asset Insights to detect potential risks in your asset configurations and help you improve your security posture.
Overview
Cloud Asset Insights provides insights
based on the IAM policies associated with your organization's
resources. It is a 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 the
appropriate action. They are generated daily, based on a snapshot of the data
stored in Cloud Asset Inventory.
Before you begin
Before you can begin using Asset Insights, you must complete the following steps.
Ensure 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
Requesting Asset Insights
To request Asset Insights, the easiest way is to list insights as shown in the following steps. For other types of insights interactions, see the insights guide for the Recommender API.
Requesting project insights
To request insights for a project, make one the following requests.
gcloud
Run the following gcloud CLI commands to list insights for your project, folder, or organization.
Projects
gcloud recommender insights list \
--project=PROJECT_ID \
--location=global \
--insight-type=google.cloudasset.asset.Insight \
--filter="insightSubtype:SUBTYPE" \
--format="FORMAT"
Provide the following values:
PROJECT_ID
: The ID of the project you want insights for.
Other flags:
--filter
: Optional. Filters results by insight subtype.--format
: Optional. A supported output format for the gcloud CLI. For example, to list insight contents as a flattened table:gcloud recommender insights list \ --project=PROJECT_ID \ --location=global \ --insight-type=google.cloudasset.asset.Insight \ --flatten="content.matchedPolicies[].matchedBindings[].matchedMembers[]" \ --format="table(insightSubtype, name, content.matchedPolicies.matchedBindings.matchedMembers, content.matchedPolicies.matchedBindings.role, content.matchedPolicies.resource)"
Folders
gcloud recommender insights list \
--folder=FOLDER_ID \
--location=global \
--insight-type=google.cloudasset.asset.Insight \
--filter="insightSubtype:SUBTYPE" \
--format="FORMAT"
Provide the following values:
FOLDER_ID
: The ID of the folder you want insights for.How to find a Google Cloud folder ID
Console
To find a Google Cloud folder ID, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher box in the menu bar.
- Click the Select from box, and then select your organization.
- Search for your folder name. The folder ID is shown next to the folder name.
gcloud CLI
You can retrieve a Google Cloud folder ID 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 can be a full or partial string match. Remove the
--format
option to see further information about the found folders.To get the ID of a folder within another folder, list the subfolders:
gcloud resource-manager folders list --folder=FOLDER_ID
-
Other flags:
--filter
: Optional. Filters results by insight subtype.--format
: Optional. A supported output format for the gcloud CLI. For example, to list insight contents as a flattened table:gcloud recommender insights list \ --folder=FOLDER_ID \ --location=global \ --insight-type=google.cloudasset.asset.Insight \ --flatten="content.matchedPolicies[].matchedBindings[].matchedMembers[]" \ --format="table(insightSubtype, name, content.matchedPolicies.matchedBindings.matchedMembers, content.matchedPolicies.matchedBindings.role, content.matchedPolicies.resource)"
Organizations
gcloud recommender insights list \
--organization=ORGANIZATION_ID \
--location=global \
--insight-type=google.cloudasset.asset.Insight \
--filter="insightSubtype:SUBTYPE" \
--format="FORMAT"
Provide the following values:
ORGANIZATION_ID
: The ID of the organization you want insights for.How to find a Google Cloud organization ID
Console
To find a Google Cloud organization ID, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher box in the menu bar.
- Click the Select from box, and then select your organization.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve a Google Cloud organization ID with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-
Other flags:
--filter
: Optional. Filters results by insight subtype.--format
: Optional. A supported output format for the gcloud CLI. For example, to list insight contents as a flattened table:gcloud recommender insights list \ --organization=ORGANIZATION_ID \ --location=global \ --insight-type=google.cloudasset.asset.Insight \ --flatten="content.matchedPolicies[].matchedBindings[].matchedMembers[]" \ --format="table(insightSubtype, name, content.matchedPolicies.matchedBindings.matchedMembers, content.matchedPolicies.matchedBindings.role, content.matchedPolicies.resource)"
REST
Run the following curl
command to list insights for your project, folder,
or organization.
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://recommender.googleapis.com/v1/SCOPE/locations/global/insightTypes/google.cloudasset.asset.Insight/insights
Provide the following values:
SCOPE
: A scope can be a project, a folder, or an organization.The allowed values are:
projects/PROJECT_ID
projects/PROJECT_NUMBER
How to find a Google Cloud project number
Console
To find a Google Cloud project number, complete the following steps:
-
Go to the Dashboard page in the Google Cloud console.
- Click the switcher box in the menu bar.
- Select your organization from the Select from box, and then search for your project name.
- Click the project name to switch to that project. The project number is shown in the Project info card.
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
How to find a Google Cloud folder ID
Console
To find a Google Cloud folder ID, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher box in the menu bar.
- Click the Select from box, and then select your organization.
- Search for your folder name. The folder ID is shown next to the folder name.
gcloud CLI
You can retrieve a Google Cloud folder ID 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 can be a full or partial string match. Remove the
--format
option to see further information about the found folders.To get the ID of a folder within another folder, list the subfolders:
gcloud resource-manager folders list --folder=FOLDER_ID
-
organizations/ORGANIZATION_ID
How to find a Google Cloud organization ID
Console
To find a Google Cloud organization ID, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher box in the menu bar.
- Click the Select from box, and then select your organization.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve a Google Cloud organization ID with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-
Interpreting insight responses
In addition to the standard insight attributes, Asset Insights provides several specialized subtypes and fields.
Insight subtypes
There are seven distinct Asset Insight subtypes.
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.
Additional content fields
In addition to the standard fields in the response, Asset Insights provides
several specialized ones in the content
field.
user
: The specific user email address detected in the members of the policy bindings for this particular insight. This field is included in theTERMINATED_MEMBER
subtype.domain
: The specific domain detected in the members of the policy bindings of this particular 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 for this particular 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 particular insight. This field is included for all Asset Insights 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 Insights subtypes.policySearchQuery
: A query which can be used with the Cloud Asset Inventory IAM policy search API in order to retrieve all of the relevant policies in real time.
Sample response
The following code snippet shows the format of a sample response.
{
"name": "organizations/1234567/locations/global/insightTypes/google.cloudasset.asset.Insight/insights/0ab35ae7-afa8-42a3-a173-92da8771a489",
"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/5678910",
"project" :"projects/5678910",
"matchedBindings" :[
{
"role" :"roles/viewer",
"matchedMembers" :[
"user:example@example.com"
]
}
]
}
]
},
"lastRefreshTime": "2020-12-04T06:59:04Z",
"observationPeriod": "0s",
"stateInfo": {
"state": "ACTIVE"
},
"category": "SECURITY",
"targetResources": [
"//cloudresourcemanager.googleapis.com/organizations/1234567"
],
"insightSubtype": "EXTERNAL_MEMBER",
"etag": "\"00000000000\"",
"initialRefreshTime": "2020-12-01T06:58:03Z"
}
Limitations
These insights do not consider group memberships as part of their findings and should not be considered an exhaustive list of matching vulnerabilities.
Individual insights include a sampling of matching IAM policies which is capped at 100 distinct policies. All matching policies can be retrieved by calling Cloud Asset Inventory policy search.
Asset insights does not consider service accounts for the purposes of insight generation.