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.

Enable the Recommender API.
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, complete the following steps.

gcloud

Run the following gcloud CLI command.

gcloud recommender insights list \
  --project=PROJECT \
  --billing-project=BILLING_PROJECT \
  --location=global \
  --insight-type=google.cloudasset.asset.Insight \
  --filter="insightSubtype:SUBTYPE" \
  --format=FORMAT

Where:

BILLING_PROJECT is the project that enabled the Recommender API. Alternatively, if you set a project as the billing/quota_project in the gcloud CLI configuration, this parameter is not required.
--filter is optional but can be used to filter results by insight subtype.
FORMAT is a supported output format for the gcloud CLI. For example, to list insight contents as flattened table:

gcloud recommender insights list \
    --project=PROJECT \
    --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)"

API

Run the following curl command.

curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
  -H "x-goog-user-project: WHITELISTED_PROJECT" \
  "https://recommender.googleapis.com/v1/projects/PROJECT/locations/global/insightTypes/google.cloudasset.asset.Insight/insights"

Requesting folder insights

To request insights for a folder, complete the following steps.

gcloud

Run the following gcloud CLI command.

gcloud recommender insights list \
  --folder=FOLDER_NUMBER \
  --billing-project=BILLING_PROJECT \
  --location=global \
  --insight-type=google.cloudasset.asset.Insight \
  --filter="insightSubtype:SUBTYPE" \
  --format=FORMAT

Where:

BILLING_PROJECT is the project that enabled the Recommender API. Alternatively, if you set a project as the billing/quota_project in the gcloud CLI configuration, this parameter is not required.
--filter is optional but can be used to filter results by insight subtype.
FORMAT is a supported output format for the gcloud CLI. For example, to list insight contents as a flattened table:

gcloud recommender insights list \
    --folder=FOLDER_NUMBER \
    --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)"

API

Run the following curl command.

curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
  -H "x-goog-user-project: PROJECT" \
  "https://recommender.googleapis.com/v1/folders/FOLDER_NUMBER/locations/global/insightTypes/google.cloudasset.asset.Insight/insights"

Requesting organization insights

To request insights for an organization, complete the following steps.

gcloud

Run the following gcloud CLI command.

gcloud recommender insights list \
  --organization=ORGANIZATION \
  --billing-project=BILLING_PROJECT \
  --location=global \
  --insight-type=google.cloudasset.asset.Insight \
  --filter="insightSubtype:SUBTYPE" \
  --format=FORMAT

Where:

BILLING_PROJECT is the project that enabled the Recommender API. Alternatively, if you set a project as the billing/quota_project in the gcloud CLI configuration, this parameter is not required.
--filter is optional but can be used to filter results by insight subtype.
FORMAT is a supported output format for the gcloud CLI. For example, to list insight contents as a flattened table:

gcloud recommender insights list \
    --organization=ORGANIZATION \
    --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)"

API

Run the following curl command.

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)"  \
-H "x-goog-user-project: PROJECT" \
"https://recommender.googleapis.com/v1/organizations/ORGANIZATION

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 within 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 within the members of the policy bindings for this particular insight. This field is included in the TERMINATED_MEMBER subtype.
domain: The specific domain detected within 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 will be 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 will 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 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 may be retrieved by calling Cloud Asset Inventory policy search.
Asset insights does not consider service accounts for the purposes of insight generation.

Using Asset Insights

Overview

Before you begin

Requesting Asset Insights

Requesting project insights

gcloud

API

Requesting folder insights

gcloud

API

Requesting organization insights

gcloud

API

Interpreting insight responses

Insight subtypes

Additional content fields

Sample response

Limitations

Additional `content` fields