Improve your security posture with asset insights

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.

Enable the Recommender API.
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) role
- Cloud 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, where PROJECT_ID is the ID of the project you want insights for.
- folder=FOLDER_ID, where FOLDER_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.
  
  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, where ORGANIZATION_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.
  
  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 or storage.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, where PROJECT_ID is the ID of the project you want insights for.
- projects/PROJECT_NUMBER, where PROJECT_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.
  
  Go to Welcome
  
  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, where FOLDER_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.
  
  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, where ORGANIZATION_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.
  
  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 or storage.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 the TERMINATED_MEMBER subtype.
domain: The domain detected in the members of the policy bindings of this insight. This field is included in the EXTERNAL_MEMBER, EXTERNAL_POLICY_EDITOR, EXTERNAL_CLOUD_STORAGE_OBJECT_VIEWER, and EXTERNAL_SERVICE_ACCOUNT_IMPERSONATOR subtypes.
assetName: The asset name for which access was detected in this insight. This field is included in the OWNER_TERMINATED_PROJECT and PUBLIC_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.

Improve your security posture with asset insights

Before you begin

Limitations

Request asset insights

gcloud

Google Cloud console

gcloud CLI

Google Cloud console

gcloud CLI

Example

Example response

REST

Google Cloud console

gcloud CLI

Google Cloud console

gcloud CLI

Google Cloud console

gcloud CLI

Command examples

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Example response

Interpreting insight responses

Insight subtypes

Additional content fields