This page shows how to manage policy insights, which are machine learning-based findings about permission usage. Policy insights can help you identify which principals have permissions that they don't need.
This page focuses on policy insights for projects, folders, and organizations. Recommender also offers policy insights for the following resource types:
Policy insights are sometimes linked to role recommendations. Role recommendations suggest actions that you can take to remediate the issues identified by policy insights.
Before you begin
-
Enable the Recommender API.
- Be familiar with IAM role recommendations.
- Ensure that you have an organization-level activation of the premium tier of Security Command Center. For more information, see Billing questions.
- Optional: Read about Recommender insights.
Required roles
To get the permissions that you need to manage policy insights, ask your administrator to grant you the following IAM roles on the project, folder, or organization that you want to manage insights for:
-
To view policy insights:
IAM Recommender Viewer (
roles/recommender.iamViewer
) -
To modify policy insights:
IAM Recommender Admin (
roles/recommender.iamAdmin
)
For more information about granting roles, see Manage access to projects, folders, and organizations.
These predefined roles contain the permissions required to manage policy insights. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to manage policy insights:
-
To view policy insights:
-
recommender.iamPolicyInsights.get
-
recommender.iamPolicyInsights.list
-
-
To modify policy insights:
recommender.iamPolicyInsights.update
You might also be able to get these permissions with custom roles or other predefined roles.
List policy insights
To list all policy insights for your project, folder, or organization, use one of the following methods:Console
-
In the Google Cloud console, go to the IAM page.
- Select a project, folder, or organization.
The Security insights column shows all security-related insights for your
project, including policy insights. Policy insights have the form
EXCESS/TOTAL excess
permissions
, where EXCESS
is the number of permissions in the
role that the principal does not need and TOTAL
is the total number of
permissions in the role.
gcloud
Use the gcloud recommender
insights list
command to view all policy insights for your
project,
folder,
or organization.
Before you run the command, replace the following values:
-
RESOURCE_TYPE
: The resource type that you want to list insights for. Use the valueproject
,folder
, ororganization
. -
RESOURCE_ID
: The ID of the project, folder, or organization that you want to list insights for.
gcloud recommender insights list --insight-type=google.iam.policy.Insight \ --RESOURCE_TYPE=RESOURCE_ID \ --location=global
The output lists all of the policy insights for your project, folder, or organization. For example:
INSIGHT_ID CATEGORY INSIGHT_STATE LAST_REFRESH_TIME SEVERITY INSIGHT_SUBTYPE DESCRIPTION 00133c0b-5431-4b30-9172-7c903aa4af24 SECURITY ACTIVE 2022-05-24T07:00:00Z LOW PERMISSIONS_USAGE 9 of the permissions in this role binding were used in the past 90 days. 0161f2eb-acb7-4a5e-ad52-50284beaa312 SECURITY ACTIVE 2022-05-24T07:00:00Z LOW PERMISSIONS_USAGE 0 of the permissions in this role binding were used in the past 90 days. 01ea0d0d-e9a1-4073-9367-5a934a857fb4 SECURITY ACTIVE 2022-05-24T07:00:00Z LOW PERMISSIONS_USAGE 1 of the permissions in this role binding were used in the past 90 days. 039407bc-a25b-4aeb-b573-5c851f2e9833 SECURITY ACTIVE 2022-05-24T07:00:00Z HIGH PERMISSIONS_USAGE 52 of the permissions in this role binding were used in the past 90 days. 0541df88-8bc3-44b3-ad5d-9cb372630aeb SECURITY ACTIVE 2022-05-24T07:00:00Z HIGH PERMISSIONS_USAGE 31 of the permissions in this role binding were used in the past 90 days. 07841f74-02ce-4de8-bbe6-fc4eabb68568 SECURITY ACTIVE 2022-05-24T07:00:00Z HIGH PERMISSIONS_USAGE 0 of the permissions in this role binding were used in the past 90 days. 07713094-fdee-4475-9c43-cd53d52c9de1 SECURITY ACTIVE 2022-05-24T07:00:00Z LOW PERMISSIONS_USAGE 2 of the permissions in this role binding were used in the past 90 days. 0a438d19-9d63-4749-aadd-578aa4e77908 SECURITY ACTIVE 2022-05-24T07:00:00Z LOW PERMISSIONS_USAGE 0 of the permissions in this role binding were used in the past 90 days. f4292f55-105b-4744-9dc3-fcacf59685bb SECURITY ACTIVE 2022-05-24T07:00:00Z HIGH PERMISSIONS_USAGE 4 of the permissions in this role binding were used in the past 90 days.
REST
The Recommender API's
insights.list
method lists all policy insights for your
project,
folder,
or organization.
Before using any of the request data, make the following replacements:
-
RESOURCE_TYPE
: The resource type that you want to list insights for. Use the valueprojects
,folders
, ororganizations
. -
RESOURCE_ID
: The ID of the project, folder, or organization that you want to list insights for. PROJECT_ID
: Your Google Cloud project ID. Project IDs are alphanumeric strings, likemy-project
.
HTTP method and URL:
GET https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/insightTypes/google.iam.policy.Insight/insights
To send your request, expand one of these options:
The response lists all of the policy insights for your project, folder, or organization. For example:
{ "insights": [ { "name": "projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/07841f74-02ce-4de8-bbe6-fc4eabb68568", "description": "0 of the permissions in this role binding were used in the past 90 days.", "content": { "role": "roles/viewer", "member": "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com", "condition": { "expression": "", "title": "", "description": "", "location": "" }, "exercisedPermissions": [], "inferredPermissions": [] }, "lastRefreshTime": "2022-05-24T07:00:00Z", "observationPeriod": "7776000s", "stateInfo": { "state": "ACTIVE" }, "category": "SECURITY", "associatedRecommendations": [ { "recommendation": "projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/b1932220-867d-43d1-bd74-fb95876ab656" } ], "targetResources": [ "//cloudresourcemanager.googleapis.com/projects/123456789012" ], "insightSubtype": "PERMISSIONS_USAGE", "etag": "\"b153ab487e4ae100\"", "severity": "HIGH" }, { "name": "projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/f4292f55-105b-4744-9dc3-fcacf59685bb", "description": "4 of the permissions in this role binding were used in the past 90 days.", "content": { "role": "roles/owner", "member": "serviceAccount:my-service-account2@my-project.iam.gserviceaccount.com", "condition": { "expression": "", "title": "", "description": "", "location": "" }, "exercisedPermissions": [ { "permission": "iam.roles.create" }, { "permission": "iam.roles.delete" }, { "permission": "iam.roles.list" }, { "permission": "iam.roles.update" } ], "inferredPermissions": [] }, "lastRefreshTime": "2022-05-24T07:00:00Z", "observationPeriod": "7776000s", "stateInfo": { "state": "ACTIVE" }, "category": "SECURITY", "associatedRecommendations": [ { "recommendation": "projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/6ab16c1d-edce-45e5-8d82-570fdd49892a" } ], "targetResources": [ "//cloudresourcemanager.googleapis.com/projects/123456789012" ], "insightSubtype": "PERMISSIONS_USAGE", "etag": "\"49bb705553338fc3\"", "severity": "HIGH" } ] }
To learn more about the components of an insight, see Review policy insights on this page.
Get a single policy insight
To get more information about a single insight, including the insight's description, status, and any recommendations it's associated with, use one of the following methods:
Console
-
In the Google Cloud console, go to the IAM page.
- Select a project, folder, or organization.
-
In the Security insights column, click a policy insight. Policy insights have the form
EXCESS/TOTAL excess permissions
, whereEXCESS
is the number of permissions in the role that the principal does not need andTOTAL
is the total number of permissions in the role.
The Google Cloud console opens a pane showing the details of the insight.
gcloud
Use the gcloud recommender
insights describe
command with your insight ID to view information about a single
insight.
-
INSIGHT_ID
: The ID of the insight that you want to view. To find the ID, list the insights for your project, folder, or organization. -
RESOURCE_TYPE
: The resource type that you want to manage insights for. Use the valueproject
,folder
, ororganization
. -
RESOURCE_ID
: The ID of the project, folder, or organization that you want to manage insights for.
gcloud recommender insights describe INSIGHT_ID \ --insight-type=google.iam.policy.Insight \ --RESOURCE_TYPE=RESOURCE_ID \ --location=global
The output shows the insight in detail. For example, the following insight indicates that
my-service-account@my-project.iam.gserviceaccount.com
has used zero permissions from
the Viewer role (roles/viewer
) in the past 90 days:
associatedRecommendations: - recommendation: projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/0573b702-96a5-4622-a916-c762e7b0731f category: SECURITY content: condition: description: '' expression: '' location: '' title: '' exercisedPermissions: [] inferredPermissions: [] member: serviceAccount:my-service-account@my-project.iam.gserviceaccount.com role: roles/viewer description: 0 of the permissions in this role binding were used in the past 90 days. etag: '"d3cdec23cc712bd0"' insightSubtype: PERMISSIONS_USAGE lastRefreshTime: '2020-07-11T07:00:00Z' name: projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/0d3ce433-f067-4e78-b6ae-03d7d1f6f040 observationPeriod: 7776000s severity: HIGH stateInfo: state: ACTIVE targetResources: - //cloudresourcemanager.googleapis.com/projects/123456789012
To learn more about the components of an insight, see Review policy insights on this page.
REST
The Recommender API's
insights.get
method gets a single insight.
Before using any of the request data, make the following replacements:
-
RESOURCE_TYPE
: The resource type that you want to manage insights for. Use the valueprojects
,folders
, ororganizations
. -
RESOURCE_ID
: The ID of the project, folder, or organization that you want to manage insights for. -
INSIGHT_ID
: The ID of the insight that you want to view. If you don't know the insight ID, you can find it by listing the insights in your project, folder, or organization. The ID of an insight is everything afterinsights/
in thename
field for the insight. PROJECT_ID
: Your Google Cloud project ID. Project IDs are alphanumeric strings, likemy-project
.
HTTP method and URL:
GET https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID
To send your request, expand one of these options:
The response contains the insight. For example, the following insight indicates that
my-service-account@my-project.iam.gserviceaccount.com
has used zero permissions from
the Viewer role (roles/viewer
) in the past 90 days:
{ "name": "projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/07841f74-02ce-4de8-bbe6-fc4eabb68568", "description": "0 of the permissions in this role binding were used in the past 90 days.", "content": { "role": "roles/viewer", "member": "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com", "condition": { "expression": "", "title": "", "description": "", "location": "" }, "exercisedPermissions": [], "inferredPermissions": [] }, "lastRefreshTime": "2022-05-24T07:00:00Z", "observationPeriod": "7776000s", "stateInfo": { "state": "ACTIVE" }, "category": "SECURITY", "associatedRecommendations": [ { "recommendation": "projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/b1932220-867d-43d1-bd74-fb95876ab656" } ], "targetResources": [ "//cloudresourcemanager.googleapis.com/projects/123456789012" ], "insightSubtype": "PERMISSIONS_USAGE", "etag": "\"d3cdec23cc712bd0\"", "severity": "HIGH" }
To learn more about the components of an insight, see Review policy insights on this page.
Review policy insights
After you get a single insight, you can review its contents to understand the pattern of resource usage that it highlights.
Console
When you click a policy insight in the Google Cloud console, the Google Cloud console opens a pane showing the details of the insight. The appearance of these details depends on whether the insight is associated with a recommendation.
If the insight is associated with a recommendation, the pane shows the details of the recommendation.
If the insight is not associated with a recommendation, the pane shows a list of all permissions in the role. The permissions that the principal used appear at the top of the list, followed by the excess permissions.
gcloud
An insight's content is determined by its subtypes.
Policy insights (google.iam.policy.Insight
) insights
have the PERMISSIONS_USAGE
subtype.
PERMISSIONS_USAGE
insights have the following components, not necessarily
in this order:
-
associatedRecommendations
: The identifiers for any recommendations associated with the insight. If there are no recommendations associated with the insight, this field is empty. -
category
: The category for IAM insights is alwaysSECURITY
. -
content
: Reports a principal's permission usage for a specific role. This field contains the following components:condition
: Any conditions attached to the binding that grants the principal the role. If there are no conditions, this field contains an empty condition.exercisedPermissions
: The permissions in the role that the principal used during the observation period.inferredPermissions
: The permissions in the role that Recommender has determined, through ML, that the principal is likely to need based on their exercised permissions.member
: The principal whose permission usage was analyzed.role
: The role for which the permission usage was analyzed.
-
description
: A human-readable summary of the insight. -
etag
: A unique identifier for the current state of an insight. Each time the insight changes, a newetag
value is assigned.To change the state of an insight, you must provide the
etag
of the existing insight. Using theetag
helps ensure that any operations are performed only if the insight has not changed since you last retrieved it. -
insightSubtype
: The insight subtype. -
lastRefreshTime
: The date when the insight was last refreshed, which indicates the freshness of the data used to generate the insight. -
name
: The name of the insight, in the following format:RESOURCE_TYPE/RESOURCE_ID/locations/global/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID
The placeholders have the following values:
-
RESOURCE_TYPE
: The resource type that the insight was generated for. -
RESOURCE_ID
: The ID of the project, folder, or organization where the insight was generated. INSIGHT_ID
: A unique ID for the insight.
-
-
observationPeriod
: The time period leading up to the insight. The source data used to generate the insight ends atlastRefreshTime
and begins atlastRefreshTime
minusobservationPeriod
. -
stateInfo
: Insights go through multiple state transitions after they are proposed:-
ACTIVE
: The insight has been generated, but either no actions have been taken, or an action was taken without updating the insight's state. Active insights are updated when the underlying data changes. -
ACCEPTED
: Some action has been taken based on the insight. Insights become accepted when an associated recommendation was markedCLAIMED
,SUCCEEDED
, orFAILED
, or the insight was accepted directly. When an insight is in theACCEPTED
state, the content of the insight cannot change. Accepted insights are retained for 90 days after they are accepted.
-
-
targetResources
: The full resource name of the project, folder, or organization that the insight is for. For example,//cloudresourcemanager.googleapis.com/projects/123456789012
.
REST
An insight's content is determined by its subtypes.
Policy insights (google.iam.policy.Insight
) insights
have the PERMISSIONS_USAGE
subtype.
PERMISSIONS_USAGE
insights have the following components, not necessarily
in this order:
-
associatedRecommendations
: The identifiers for any recommendations associated with the insight. If there are no recommendations associated with the insight, this field is empty. -
category
: The category for IAM insights is alwaysSECURITY
. -
content
: Reports a principal's permission usage for a specific role. This field contains the following components:condition
: Any conditions attached to the binding that grants the principal the role. If there are no conditions, this field contains an empty condition.exercisedPermissions
: The permissions in the role that the principal used during the observation period.inferredPermissions
: The permissions in the role that Recommender has determined, through ML, that the principal is likely to need based on their exercised permissions.member
: The principal whose permission usage was analyzed.role
: The role for which the permission usage was analyzed.
-
description
: A human-readable summary of the insight. -
etag
: A unique identifier for the current state of an insight. Each time the insight changes, a newetag
value is assigned.To change the state of an insight, you must provide the
etag
of the existing insight. Using theetag
helps ensure that any operations are performed only if the insight has not changed since you last retrieved it. -
insightSubtype
: The insight subtype. -
lastRefreshTime
: The date when the insight was last refreshed, which indicates the freshness of the data used to generate the insight. -
name
: The name of the insight, in the following format:RESOURCE_TYPE/RESOURCE_ID/locations/global/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID
The placeholders have the following values:
-
RESOURCE_TYPE
: The resource type that the insight was generated for. -
RESOURCE_ID
: The ID of the project, folder, or organization where the insight was generated. INSIGHT_ID
: A unique ID for the insight.
-
-
observationPeriod
: The time period leading up to the insight. The source data used to generate the insight ends atlastRefreshTime
and begins atlastRefreshTime
minusobservationPeriod
. -
stateInfo
: Insights go through multiple state transitions after they are proposed:-
ACTIVE
: The insight has been generated, but either no actions have been taken, or an action was taken without updating the insight's state. Active insights are updated when the underlying data changes. -
ACCEPTED
: Some action has been taken based on the insight. Insights become accepted when an associated recommendation was markedCLAIMED
,SUCCEEDED
, orFAILED
, or the insight was accepted directly. When an insight is in theACCEPTED
state, the content of the insight cannot change. Accepted insights are retained for 90 days after they are accepted.
-
-
targetResources
: The full resource name of the project, folder, or organization that the insight is for. For example,//cloudresourcemanager.googleapis.com/projects/123456789012
.
Mark a policy insight as ACCEPTED
If you take action based on an active insight, you can mark that insight as
ACCEPTED
. The ACCEPTED
state tells the
Recommender API that you have taken action based on this
insight, which helps refine your recommendations.
Accepted insights are retained for 90 days after
they are marked as ACCEPTED
.
Console
If an insight is associated with a recommendation,
applying the recommendation
changes the insight's state to ACCEPTED
.
To mark an insight as ACCEPTED
without applying a recommendation, use the
gcloud CLI or REST API.
gcloud
Use the
gcloud recommender insights mark-accepted
command with your insight ID to mark
an insight as ACCEPTED
.
-
INSIGHT_ID
: The ID of the insight that you want to view. To find the ID, list the insights for your project, folder, or organization. -
RESOURCE_TYPE
: The resource type that you want to manage insights for. Use the valueproject
,folder
, ororganization
. -
RESOURCE_ID
: The ID of the project, folder, or organization that you want to manage insights for. -
ETAG
: An identifier for a version of the insight. To get theetag
, do the following:-
Get the insight using the
gcloud recommender insights describe
command. -
Find and copy the
etag
value from the output, including the enclosing quotes. For example,"d3cdec23cc712bd0"
.
-
Get the insight using the
gcloud recommender insights mark-accepted INSIGHT_ID \ --insight-type=google.iam.policy.Insight \ --RESOURCE_TYPE=RESOURCE_ID \ --location=global \ --etag=ETAG
The output shows the insight, now with the state of ACCEPTED
:
associatedRecommendations: - recommendation: projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/0573b702-96a5-4622-a916-c762e7b0731f category: SECURITY content: condition: description: '' expression: '' location: '' title: '' exercisedPermissions: [] inferredPermissions: [] member: serviceAccount:my-service-account@my-project.iam.gserviceaccount.com role: roles/viewer description: 0 of the permissions in this role binding were used in the past 90 days. etag: '"b153ab487e4ae100"' insightSubtype: PERMISSIONS_USAGE lastRefreshTime: '2020-07-11T07:00:00Z' name: projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/0d3ce433-f067-4e78-b6ae-03d7d1f6f040 observationPeriod: 7776000s severity: HIGH stateInfo: state: ACCEPTED targetResources: - //cloudresourcemanager.googleapis.com/projects/123456789012
To learn more about the state info of an insight, see Review policy insights on this page.
REST
The Recommender API's
insights.markAccepted
method marks an insight as ACCEPTED
.
Before using any of the request data, make the following replacements:
-
RESOURCE_TYPE
: The resource type that you want to manage insights for. Use the valueprojects
,folders
, ororganizations
. -
RESOURCE_ID
: The ID of the project, folder, or organization that you want to manage insights for. -
INSIGHT_ID
: The ID of the insight that you want to view. If you don't know the insight ID, you can find it by listing the insights in your project, folder, or organization. The ID of an insight is everything afterinsights/
in thename
field for the insight. -
ETAG
: An identifier for a version of the insight. To get theetag
, do the following:- Get the insight using the
insights.get
method. - Find and copy the
etag
value from the response.
- Get the insight using the
PROJECT_ID
: Your Google Cloud project ID. Project IDs are alphanumeric strings, likemy-project
.
HTTP method and URL:
POST https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID:markAccepted
Request JSON body:
{ "etag": "ETAG" }
To send your request, expand one of these options:
The response contains the insight, now with the state of ACCEPTED
:
{ "name": "projects/1234567890/locations/global/insightTypes/google.iam.policy.Insight/insights/07841f74-02ce-4de8-bbe6-fc4eabb68568", "description": "0 of the permissions in this role binding were used in the past 90 days.", "content": { "role": "roles/viewer", "member": "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com", "condition": { "expression": "", "title": "", "description": "", "location": "" }, "exercisedPermissions": [], "inferredPermissions": [] }, "lastRefreshTime": "2022-05-24T07:00:00Z", "observationPeriod": "7776000s", "stateInfo": { "state": "ACCEPTED" }, "category": "SECURITY", "associatedRecommendations": [ { "recommendation": "projects/1234567890/locations/global/recommenders/google.iam.policy.Recommender/recommendations/b1932220-867d-43d1-bd74-fb95876ab656" } ], "targetResources": [ "//cloudresourcemanager.googleapis.com/projects/123456789012" ], "insightSubtype": "PERMISSIONS_USAGE", "etag": "\"b153ab487e4ae100\"", "severity": "HIGH" }
To learn more about the state info of an insight, see Review policy insights on this page.
What's next
- Learn how to view and apply policy recommendations.
- Use the Recommendation Hub to view and manage all recommendations for your project, including IAM recommendations.