Using policy insights

In addition to providing recommendations, the IAM recommender uses machine learning (ML) to provide detailed insights. These insights include IAM policy insights, which are are ML-based findings about permission usage within your project.

Some insights link to recommendations and provide evidence for the associated recommendations. However, you can use insights independently from recommendations to proactively improve your IAM configuration.

Before you begin

Required Permissions

To view IAM policy insights, you need a role on the project that includes the following permissions:

  • recommender.iamPolicyInsights.get
  • recommender.iamPolicyInsights.list

To modify IAM policy insights, you need a role on the project that includes the following permissions:

  • recommender.iamPolicyInsights.update

To gain these permissions while following the principle of least privilege, ask your administrator to grant you one of the following predefined roles:

  • To view policy insights and recommendations only, ask for one of the following roles:
    • IAM Recommender Viewer role (roles/recommender.iamViewer)
    • IAM Security Reviewer role (roles/iam.securityReviewer)
  • To view and modify policy insights and recommendations, ask for the IAM Recommender Admin role (roles/recommender.iamAdmin).

Alternatively, your administrator can grant you a different role with the required permissions, such as a custom role or a more permissive predefined role.

Listing policy insights

To list all the IAM policy insights for your project, use one of the following methods:

gcloud

Use the gcloud recommender insights list command with the insight type google.iam.policy.Insight and the location global to view all IAM policy insights for your project:

gcloud recommender insights list --insight-type=google.iam.policy.Insight \
  --location=global

The output will show a list of all the policy insights in your project. For example:

INSIGHT_ID                            LOCATION  INSIGHT_TYPE               CATEGORY  INSIGHT_STATE  LAST_REFRESH_TIME
07841f74-02ce-4de8-bbe6-fc4eabb68568  global    google.iam.policy.Insight  SECURITY  ACCEPTED       2020-07-12T07:00:00Z
0d3ce433-f067-4e78-b6ae-03d7d1f6f040  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
0e2cc488-38fb-4b9b-942c-cfe06a0ab88f  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
12b557be-d48f-49cf-a0b0-b3b73a178edf  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
279ef748-408f-44db-9a4a-1ff8865b9839  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
29a4553d-9ffb-4508-9f13-77f40fc4e8b6  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
2a00a91a-3e37-4dca-81f7-fb607d18053f  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
2baea818-df89-4ab3-8a48-0e752459d816  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
4a59da9d-cde8-46cc-9c68-6980487175fb  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
78fee8d9-c25c-4070-9f1b-ae5e4a4a164b  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z

REST API

The Recommender API's insights.list method lists all insights of a specific type for your project. Use this method with the insight type google.iam.policy.Insight the location global to list all IAM policy insights for your project.

Before using any of the request data below, make the following replacements:

  • project-id: Your Google Cloud project ID.

HTTP method and URL:

GET https://recommender.googleapis.com/v1/projects/project-id/locations/global/insightTypes/google.iam.policy.Insight/insights

To send your request, expand one of these options:

The response contains all of the policy insights for your project. For example:

{
  "insights": [
    {
      "name": "projects/1234567890/locations/global/insightTypes/google.iam.policy.Insight/insights/07841f74-02ce-4de8-bbe6-fc4eabb68568",
      "description": "0 permission checks were authorized by this policy binding tuple.",
      "content": {
        "role": "roles/viewer",
        "member": "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com",
        "condition": {
          "expression": "",
          "title": "",
          "description": "",
          "location": ""
        },
        "exercisedPermissions": [],
        "inferredPermissions": []
      },
      "lastRefreshTime": "2020-07-12T07:00:00Z",
      "observationPeriod": "7776000s",
      "stateInfo": {
        "state": "ACTIVE"
      },
      "category": "SECURITY",
      "associatedRecommendations": [
        {
          "recommendation": "projects/1234567890/locations/global/recommenders/google.iam.policy.Recommender/recommendations/b1932220-867d-43d1-bd74-fb95876ab656"
        }
      ],
      "targetResources": [
        "//cloudresourcemanager.googleapis.com/projects/1234567890"
      ],
      "insightSubtype": "PERMISSIONS_USAGE",
      "etag": "\"b153ab487e4ae100\""
    },
    {
      "name": "projects/1234567890/locations/global/insightTypes/google.iam.policy.Insight/insights/f4292f55-105b-4744-9dc3-fcacf59685bb",
      "description": "4 permission checks were authorized by this policy binding tuple.",
      "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": "2020-07-12T07:00:00Z",
      "observationPeriod": "7776000s",
      "stateInfo": {
        "state": "ACTIVE"
      },
      "category": "SECURITY",
      "associatedRecommendations": [
        {
          "recommendation": "projects/1234567890/locations/global/recommenders/google.iam.policy.Recommender/recommendations/6ab16c1d-edce-45e5-8d82-570fdd49892a"
        }
      ],
      "targetResources": [
        "//cloudresourcemanager.googleapis.com/projects/1234567890"
      ],
      "insightSubtype": "PERMISSIONS_USAGE",
      "etag": "\"49bb705553338fc3\""
    }
  ]
}

To learn more about the components of a IAM insight, see Reviewing policy insights on this page.

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

gcloud

Use the gcloud recommender insights describe command with your insight ID, the insight type google.iam.policy.Insight, and the location global to view information about a single IAM policy insight.

Replace insight-id with the ID of the policy insight that you want to view. To see the IDs of the policy insights in your project, list the policy insights in your project.

gcloud recommender insights describe insight-id \
  --insight-type=google.iam.policy.Insight --location=global

The output will show the policy insight. For example:

associatedRecommendations:
- recommendation: projects/1234567890/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 permission checks were authorized by this policy binding tuple.
etag: '"d3cdec23cc712bd0"'
insightSubtype: PERMISSIONS_USAGE
lastRefreshTime: '2020-07-11T07:00:00Z'
name: projects/1234567890/locations/global/insightTypes/google.iam.policy.Insight/insights/0d3ce433-f067-4e78-b6ae-03d7d1f6f040
observationPeriod: 7776000s
stateInfo:
  state: ACTIVE
targetResources:
- //cloudresourcemanager.googleapis.com/projects/1234567890

To learn more about the components of a IAM policy insight, see Reviewing policy insights on this page.

REST API

The Recommender API's insights.get method gets a single insight. Use this method with the insight type google.iam.policy.Insight the location global to get a single IAM policy insight.

Before using any of the request data below, make the following replacements:

  • project-id: Your Google Cloud project ID.
  • insight-id: The ID of the insight that you want to view. To see the IDs of the policy insights in your project, list the policy insights in your project. The ID of an insight is everything after insights/ in the name field for the insight.

HTTP method and URL:

GET https://recommender.googleapis.com/v1/projects/project-id/locations/global/insightTypes/google.iam.policy.Insight/insights/insight-id

To send your request, expand one of these options:

The response contains the policy insight. For example:

{
  "name": "projects/1234567890/locations/global/insightTypes/google.iam.policy.Insight/insights/07841f74-02ce-4de8-bbe6-fc4eabb68568",
  "description": "0 permission checks were authorized by this policy binding tuple.",
  "content": {
    "role": "roles/viewer",
    "member": "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com",
    "condition": {
      "expression": "",
      "title": "",
      "description": "",
      "location": ""
    },
    "exercisedPermissions": [],
    "inferredPermissions": []
  },
  "lastRefreshTime": "2020-07-12T07:00:00Z",
  "observationPeriod": "7776000s",
  "stateInfo": {
    "state": "ACTIVE"
  },
  "category": "SECURITY",
  "associatedRecommendations": [
    {
      "recommendation": "projects/1234567890/locations/global/recommenders/google.iam.policy.Recommender/recommendations/b1932220-867d-43d1-bd74-fb95876ab656"
    }
  ],
  "targetResources": [
    "//cloudresourcemanager.googleapis.com/projects/1234567890"
  ],
  "insightSubtype": "PERMISSIONS_USAGE",
  "etag": "\"b153ab487e4ae100\""
}

To learn more about the components of a IAM insight, see Reviewing policy insights on this page.

Reviewing policy insights

IAM policy insights currently support the PERMISSION_USAGE insight subtype. PERMISSION_USAGE insights contain findings about a member's permission usage within your project.

PERMISSION_USAGE insights have the following components, not necessarily in this order:

name

The name of the insight. PERMISSION_USAGE insight names have the following format:

projects/project-id/locations/global/insightTypes/google.iam.policy.Insight/insights/insight-id

where:

  • project-id is the ID of the project where the insight was generated.
  • insight-idis a unique ID for the insight.
targetResources
The fully qualified name of the Google Cloud project that the insight is for. For example, //cloudresourcemanager.googleapis.com/projects/1234567890
insightSubtype
The insight subtype for a PERMISSION_USAGE insight is always PERMISSION_USAGE.
observationPeriod
The time period leading up to the insight. The source data used to generate the insight ends at lastRefreshTime and begins at lastRefreshTime minus observationPeriod.
content

The content field of a PERMISSION_USAGE insight reports a member's permission usage for a specific role. This field contains the following components:

  • member: The member whose permission usage was analyzed.
  • role: The role for which the permission usage was analyzed.
  • condition: Any conditions attached to binding that grants the member the role. If there are no conditions, this field contains an empty condition.
  • exercisedPermissions: The permissions in the role that the member used during the observationPeriod.
  • inferredPermissions: The permissions in the role that the IAM recommender has determined, through ML, that the member is likely to need based on their exercisedPermissions.
description
A description of how many of the role's permissions the member used during the observation period.
lastRefreshTime
The date when the insight was last refreshed, which indicates the freshness of the data used to generate the insight.
stateInfo

Insights go through multiple state transitions after they are proposed:

  • ACTIVE, which means that the insight has been generated, but no actions have been taken in response. Content for active insights is updated when the underlying data changes. Active insights can be marked DISMISSED or ACCEPTED.
  • ACCEPTED, which means that some action has been taken based on the insight. Insights become accepted when an associated recommendation has been marked CLAIMED, SUCCEEDED, or FAILED. Insights can also be accepted directly. Content for accepted insights is immutable. Accepted insights are retained for 90 days from the time of the state change.
  • DISMISSED, which means that the recommendation associated with the insight has been dismissed without taking any action based on it. Content for dismissed insights is updated when the underlying data changes.
category
The category for PERMISSION_USAGE insights is always SECURITY.
etag

A unique fingerprint that identifies the current state of an insight. Each time the insight changes, a new etag value is assigned.

In order to change insight state, you must provide the etag of the existing insight. This makes sure that any operations are performed only if the insight has not changed since you last retrieved it.

associatedRecommendations
The reference for any recommendations associated with the insight. If there are no recommendations associated with the insight, this field is empty.

Marking a policy insight as ACCEPTED

If you apply an action based on an active insight, you can mark that insight as ACCEPTED. This action tells the Recommender API that you have applied this insight, which helps refine your recommendations.

Accepted insights are retained for 90 days after they are marked as ACCEPTED.

gcloud

Use the gcloud recommender insights mark-accepted command with your insight ID, the insight type google.iam.policy.Insight, and the location global to mark a policy insight as ACCEPTED.

Before using the sample command, replace the following values:

  • insight-id: The ID of the insight that you want to mark as ACCEPTED. To see the IDs of the policy insights in your project, list the policy insights in your project.

  • etag: An identifier for a version of the insight. To get the etag, do the following:

    1. Get the policy insight using the gcloud recommender insights describe command.
    2. Find and copy the etag value from the output, including any special characters. For example, '"d3cdec23cc712bd0"'.
gcloud recommender insights mark-accepted insight-id \
  --insight-type=google.iam.policy.Insight --location=global --etag=etag

The output will show the policy insight, now with the state of ACCEPTED. For example:

associatedRecommendations:
- recommendation: projects/1234567890/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 permission checks were authorized by this policy binding tuple.
etag: '"d3cdec23cc712bd0"'
insightSubtype: PERMISSIONS_USAGE
lastRefreshTime: '2020-07-11T07:00:00Z'
name: projects/1234567890/locations/global/insightTypes/google.iam.policy.Insight/insights/0d3ce433-f067-4e78-b6ae-03d7d1f6f040
observationPeriod: 7776000s
stateInfo:
  state: ACCEPTED
targetResources:
- //cloudresourcemanager.googleapis.com/projects/1234567890

To learn more about the state info of a policy insight, see Reviewing policy insights on this page.

REST API

The Recommender API's insights.markAccepted method marks an insight as ACCEPTED. Use this method with the insight type google.iam.policy.Insight the location global to mark a IAM policy insight as ACCEPTED.

Before using any of the request data below, make the following replacements:

  • project-id: Your Google Cloud project ID.
  • insight-id: The ID of the insight that you want to mark as ACCEPTED. To see the IDs of the policy insights in your project, list the policy insights in your project.
  • The ID of an insight is everything after insights/ in the name field for the insight.
  • etag: An identifier for a version of the insight. To get the etag, do the following:
    1. Get the insight using the insights.get method.
    2. Find and copy the etag value from the response.

HTTP method and URL:

POST https://recommender.googleapis.com/v1/projects/project-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. For example:

{
  "name": "projects/1234567890/locations/global/insightTypes/google.iam.policy.Insight/insights/07841f74-02ce-4de8-bbe6-fc4eabb68568",
  "description": "0 permission checks were authorized by this policy binding tuple.",
  "content": {
    "role": "roles/viewer",
    "member": "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com",
    "condition": {
      "expression": "",
      "title": "",
      "description": "",
      "location": ""
    },
    "exercisedPermissions": [],
    "inferredPermissions": []
  },
  "lastRefreshTime": "2020-07-12T07: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/1234567890"
  ],
  "insightSubtype": "PERMISSIONS_USAGE",
  "etag": "\"b153ab487e4ae100\""
}

To learn more about the state info of a policy insight, see Reviewing policy insights on this page.

What's next