Review policy insights for projects, folders, and organizations

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.
Roles required to enable APIs
To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.
Enable the API
Be familiar with IAM role recommendations.
You must have Premium or Enterprise activated at the organization or project level to use policy insights. 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.

Go to IAM
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 value project, folder, or organization.
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 value projects, folders, or organizations.
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, like my-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 (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

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"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$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, 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.

Go to IAM
Select a project, folder, or organization.
In the Security insights column, click a policy insight. 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.

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 value project, folder, or organization.
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 value projects, folders, or organizations.
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 after insights/ in the name field for the insight.
PROJECT_ID: Your Google Cloud project ID. Project IDs are alphanumeric strings, like my-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 (Linux, macOS, or Cloud Shell)

Execute the following command:

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"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token

Review policy insights for projects, folders, and organizations Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Required roles

Required permissions

List policy insights

Console

gcloud

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Get a single policy insight

Console

gcloud

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Review policy insights for projects, folders, and organizations