Console

1. In the Google Cloud console, go to theIAM page.

   Go to IAM

2. Select a project, folder, or organization.

TheSecurity insights column shows all security-related insights for your project, including policy insights. Policy insights have the formEXCESS/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.

gcloud

Use thegcloud 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.

gcloudrecommenderinsightslist--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    DESCRIPTION00133c0b-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'sinsights.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 projectID. 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:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project:PROJECT_ID" \
     "https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/insightTypes/google.iam.policy.Insight/insights"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/insightTypes/google.iam.policy.Insight/insights" | Select-Object -Expand Content

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, seeReview policy insights on this page.

Console

1. In the Google Cloud console, go to theIAM page.

   Go to IAM

2. Select a project, folder, or organization.

3. In theSecurity insights column, click a policy insight. Policy insights have the formEXCESS/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 thegcloud 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.

gcloudrecommenderinsightsdescribeINSIGHT_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 thatmy-service-account@my-project.iam.gserviceaccount.com has used zero permissions fromthe 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-c762e7b0731fcategory:SECURITYcontent:condition:description:''expression:''location:''title:''exercisedPermissions:[]inferredPermissions:[]member:serviceAccount:my-service-account@my-project.iam.gserviceaccount.comrole:roles/viewerdescription:0 of the permissions in this role binding were used in the past 90 days.etag:'"d3cdec23cc712bd0"'insightSubtype:PERMISSIONS_USAGElastRefreshTime:'2020-07-11T07:00:00Z'name:projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/0d3ce433-f067-4e78-b6ae-03d7d1f6f040observationPeriod:7776000sseverity:HIGHstateInfo:state:ACTIVEtargetResources:-//cloudresourcemanager.googleapis.com/projects/123456789012

To learn more about the components of an insight, seeReview policy insights on this page.

REST

The Recommender API'sinsights.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 bylisting 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 projectID. 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:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project:PROJECT_ID" \
     "https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID" | Select-Object -Expand Content

The response contains the insight. For example, the following insight indicates thatmy-service-account@my-project.iam.gserviceaccount.com has used zero permissions fromthe 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, seeReview policy insights on this page.

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.

Note: You can check if an insight is associated with a recommendation by looking for theRecommendation available icon in theSecurity insights column.

If the insight is associated with a recommendation, the pane shows thedetails 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.

Note: If an insight is for abasic role, the list of permissions in the Google Cloud console might not include all of the permissions that a principal needs. This is because some services use basic roles to indirectly grant additional roles. The list of permissions might not include permissions from these additional roles, even if a principal used them. Role recommendations automatically account for this discrepancy.

Indirectly granted roles include roles granted throughCloud Storage convenience values andBigQuery special group membership.

gcloud

An insight's content is determined by its subtypes. Policy insights (google.iam.policy.Insight) insights have thePERMISSIONS_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, throughML, 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 theetag 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: Thefull 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 thePERMISSIONS_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, throughML, 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 theetag 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: Thefull resource name of the project, folder, or organization that the insight is for. For example,//cloudresourcemanager.googleapis.com/projects/123456789012.

Console

If an insight is associated with a recommendation,applying the recommendation changes the insight's state toACCEPTED.

To mark an insight asACCEPTED without applying a recommendation, use the gcloud CLI or REST API.

gcloud

Use thegcloud recommender insights mark-accepted command with your insight ID to mark an insight asACCEPTED.

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

  1. Get the insight using thegcloud recommender insights describe command.
  2. Find and copy theetag value from the output, including the enclosing quotes. For example,"d3cdec23cc712bd0".

gcloudrecommenderinsightsmark-acceptedINSIGHT_ID\--insight-type=google.iam.policy.Insight\--RESOURCE_TYPE=RESOURCE_ID\--location=global\--etag=ETAG

The output shows the insight, now with the state ofACCEPTED:

associatedRecommendations:-recommendation:projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/0573b702-96a5-4622-a916-c762e7b0731fcategory:SECURITYcontent:condition:description:''expression:''location:''title:''exercisedPermissions:[]inferredPermissions:[]member:serviceAccount:my-service-account@my-project.iam.gserviceaccount.comrole:roles/viewerdescription:0 of the permissions in this role binding were used in the past 90 days.etag:'"b153ab487e4ae100"'insightSubtype:PERMISSIONS_USAGElastRefreshTime:'2020-07-11T07:00:00Z'name:projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/0d3ce433-f067-4e78-b6ae-03d7d1f6f040observationPeriod:7776000sseverity:HIGHstateInfo:state:ACCEPTEDtargetResources:-//cloudresourcemanager.googleapis.com/projects/123456789012

To learn more about the state info of an insight, seeReview policy insights on this page.

REST

The Recommender API'sinsights.markAccepted method marks an insight asACCEPTED.

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 bylisting 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:
  1. Get the insight using theinsights.get method.
  2. Find and copy theetag value from the response.
• PROJECT_ID: Your Google Cloud projectID. 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:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project:PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID:markAccepted"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID:markAccepted" | Select-Object -Expand Content

The response contains the insight, now with the state ofACCEPTED:

{  "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, seeReview policy insights on this page.