Using Asset Insights

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.

  1. Enable the Recommender API.

  2. 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) role

    • Cloud 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:

    1. Go to the Google Cloud console.

      Go to the Google Cloud console

    2. Click the switcher box in the menu bar.
    3. Click the Select from box, and then select your organization.
    4. 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:

    1. Go to the Google Cloud console.

      Go to the Google Cloud console

    2. Click the switcher box in the menu bar.
    3. Click the Select from box, and then select your organization.
    4. 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:

      1. Go to the Dashboard page in the Google Cloud console.

        Go to Dashboard

      2. Click the switcher box in the menu bar.
      3. Select your organization from the Select from box, and then search for your project name.
      4. 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:

      1. Go to the Google Cloud console.

        Go to the Google Cloud console

      2. Click the switcher box in the menu bar.
      3. Click the Select from box, and then select your organization.
      4. 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:

      1. Go to the Google Cloud console.

        Go to the Google Cloud console

      2. Click the switcher box in the menu bar.
      3. Click the Select from box, and then select your organization.
      4. 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 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.

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 the TERMINATED_MEMBER subtype.

  • domain: The specific domain detected in the members of the policy bindings of this particular 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 for this particular 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 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.