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
) 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
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 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 theTERMINATED_MEMBER
subtype.domain
: The specific domain detected within 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 will be 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 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.