Review policy insights for BigQuery datasets

This page shows how to manage dataset-level policy insights, which are machine learning-based findings about permission usage for your BigQuery datasets. Policy insights can help you identify which principals have permissions that they don't need.

This page focuses on policy insights for datasets. Recommender also offers policy insights for the following resource types:

Dataset-level policy insights are sometimes linked to role recommendations. Role recommendations suggest actions that you can take to remediate the issues identified by dataset-level policy insights.

Before you begin

Enable the Recommender API.
Enable the API
Be familiar with IAM role recommendations.
Optional: Read about Recommender insights.

Required roles

To get the permissions that you need to manage dataset-level policy insights, ask your administrator to grant you the following IAM roles on your project:

BigQuery Data Owner (`roles/bigquery.dataOwner`)
IAM Recommender Admin (`roles/recommender.iamAdmin`)
Manage dataset-level policy insights with the gcloud CLI or REST API: Service Usage Consumer (`roles/serviceusage.serviceUsageConsumer`)

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to manage dataset-level policy insights. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to manage dataset-level policy insights:

View dataset-level policy insights:
- recommender.iamPolicyInsights.get
- recommender.iamPolicyInsights.list
Modify dataset-level policy insights: recommender.iamPolicyInsights.update
Manage dataset-level policy insights with the gcloud CLI or REST API: serviceusage.services.use

You might also be able to get these permissions with custom roles or other predefined roles.

List dataset-level policy insights

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

gcloud

Use the gcloud recommender insights list command to view all dataset-level policy insights for your project.

Before you run the command, replace the following values:

PROJECT_ID: The ID of the project that you want to list insights for.
LOCATION: The location of the datasets whose insights you want to list.

gcloud recommender insights list --insight-type=google.iam.policy.Insight \
    --project=PROJECT_ID \
    --location=LOCATION\
    --filter="insightSubtype:PERMISSIONS_USAGE_BIGQUERY_DATASET"

The output lists all of the dataset-level policy insights for your project in the specified location. For example:

INSIGHT_ID                            CATEGORY  INSIGHT_STATE  LAST_REFRESH_TIME     SEVERITY  INSIGHT_SUBTYPE                     DESCRIPTION
101d03ad-6148-4628-943e-fcf1a3af6b57  SECURITY  ACTIVE         2024-02-02T08:00:00Z  LOW       PERMISSIONS_USAGE_BIGQUERY_DATASET  0 of the permissions in this role binding were used in the past 90 days.
15133dd9-4cbc-41e9-8990-b189241676d8  SECURITY  ACTIVE         2024-02-02T08:00:00Z  LOW       PERMISSIONS_USAGE_BIGQUERY_DATASET  0 of the permissions in this role binding were used in the past 90 days.
1590aeae-d5bf-4e3d-b7d5-e230212f5faf  SECURITY  ACTIVE         2024-02-02T08:00:00Z  LOW       PERMISSIONS_USAGE_BIGQUERY_DATASET  4 of the permissions in this role binding were used in the past 90 days.
280e5a14-4d09-4ac6-8e14-be7407611ad7  SECURITY  ACTIVE         2024-02-02T08:00:00Z  LOW       PERMISSIONS_USAGE_BIGQUERY_DATASET  0 of the permissions in this role binding were used in the past 90 days.
34102078-085f-45d3-ae72-81da16c75781  SECURITY  ACTIVE         2024-02-02T08:00:00Z  LOW       PERMISSIONS_USAGE_BIGQUERY_DATASET  10 of the permissions in this role binding were used in the past 90 days.

REST

The Recommender API's insights.list method lists all dataset-level policy insights for your project.

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

PROJECT_ID: The ID of the project that you want to list insights for.
LOCATION: The location of the datasets whose insights you want to list.

HTTP method and URL:

GET https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights?filter=insightSubtype%20%3D%20PERMISSIONS_USAGE_BIGQUERY_DATASET

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/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights?filter=insightSubtype%20%3D%20PERMISSIONS_USAGE_BIGQUERY_DATASET"

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/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights?filter=insightSubtype%20%3D%20PERMISSIONS_USAGE_BIGQUERY_DATASET" | Select-Object -Expand Content

The response lists all of the dataset-level policy insights for your project in the specified location. For example:

{
  "insights": [
    {
      "name": "projects/1069248613794/locations/us/insightTypes/google.iam.policy.Insight/insights/101d03ad-6148-4628-943e-fcf1a3af6b57",
      "description": "0 of the permissions in this role binding were used in the past 90 days.",
      "content": {
        "role": "roles/bigquery.dataEditor",
        "member": "projectEditor:my-project",
        "condition": {
          "expression": "",
          "title": "",
          "description": "",
          "location": ""
        },
        "exercisedPermissions": [],
        "inferredPermissions": [],
        "currentTotalPermissionsCount": "37"
      },
      "lastRefreshTime": "2024-02-02T08:00:00Z",
      "observationPeriod": "7779600s",
      "stateInfo": {
        "state": "ACTIVE"
      },
      "category": "SECURITY",
      "associatedRecommendations": [
        {
          "recommendation": "projects/1069248613794/locations/us/recommenders/google.iam.policy.Recommender/recommendations/9327f952-1ceb-488e-9e49-f17eb21f6e5e"
        }
      ],
      "targetResources": [
        "//bigquery.googleapis.com/projects/my-project/datasets/dataset-1"
      ],
      "insightSubtype": "PERMISSIONS_USAGE_BIGQUERY_DATASET",
      "etag": "\"35d4af47524d3f0c\"",
      "severity": "LOW"
    },
    {
      "name": "projects/1069248613794/locations/us/insightTypes/google.iam.policy.Insight/insights/15133dd9-4cbc-41e9-8990-b189241676d8",
      "description": "0 of the permissions in this role binding were used in the past 90 days.",
      "content": {
        "role": "roles/bigquery.dataViewer",
        "member": "projectViewer:my-project",
        "condition": {
          "expression": "",
          "title": "",
          "description": "",
          "location": ""
        },
        "exercisedPermissions": [],
        "inferredPermissions": [],
        "currentTotalPermissionsCount": "17"
      },
      "lastRefreshTime": "2024-02-02T08:00:00Z",
      "observationPeriod": "7779600s",
      "stateInfo": {
        "state": "ACTIVE"
      },
      "category": "SECURITY",
      "associatedRecommendations": [
        {
          "recommendation": "projects/1069248613794/locations/us/recommenders/google.iam.policy.Recommender/recommendations/bc9b4c28-cc93-4a91-97ea-ff67e3cef1b4"
        }
      ],
      "targetResources": [
        "//bigquery.googleapis.com/projects/my-project/datasets/dataset-2"
      ],
      "insightSubtype": "PERMISSIONS_USAGE_BIGQUERY_DATASET",
      "etag": "\"eafa79df1b329063\"",
      "severity": "LOW"
    }
  ]
}

To learn more about the components of an insight, see Review dataset-level policy insights on this page.

Get a single dataset-level 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 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.
PROJECT_ID: The ID of the project that you want to manage insights for.
LOCATION: The location of the dataset whose insight you want to get.

gcloud recommender insights describe INSIGHT_ID \
    --insight-type=google.iam.policy.Insight \
    --project=PROJECT_ID \
    --location=LOCATION

The output shows the insight in detail. For example, the following insight indicates that all users with the Editor role on the project my-project (projectEditor:my-project) have the BigQuery Data Editor role (roles/bigquery.dataEditor) on the dataset dataset-1, but that none of the permissions in that role were used in the past 90 days:

associatedRecommendations:
- recommendation: projects/1069248613794/locations/us/recommenders/google.iam.policy.Recommender/recommendations/9327f951-1ceb-488e-9e49-f17eb21f6e5e
category: SECURITY
content:
  condition:
    description: ''
    expression: ''
    location: ''
    title: ''
  currentTotalPermissionsCount: '37'
  exercisedPermissions: []
  inferredPermissions: []
  member: projectEditor:my-project
  role: roles/bigquery.dataEditor
description: 0 of the permissions in this role binding were used in the past 90 days.
etag: '"5f2f352a738f7a24"'
insightSubtype: PERMISSIONS_USAGE_BIGQUERY_DATASET
lastRefreshTime: '2024-02-04T08:00:00Z'
name: projects/1069248613794/locations/us/insightTypes/google.iam.policy.Insight/insights/101d03ad-6148-4628-943e-fcf1a3af6b57
observationPeriod: 7776000s
severity: LOW
stateInfo:
  state: ACTIVE
targetResources:
- //bigquery.googleapis.com/projects/my-project/datasets/dataset-1

To learn more about the components of an insight, see Review dataset-level 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:

PROJECT_ID: The ID of the project that you want to manage insights for.
LOCATION: The location of the dataset whose insight you want to get.
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. 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/LOCATION/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/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID"

PowerShell (Windows)

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/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID" | Select-Object -Expand Content

The response contains the insight. For example, the following insight indicates that all users with the Editor role on the project my-project (projectEditor:my-project) have the BigQuery Data Editor role (roles/bigquery.dataEditor) on the dataset dataset-1, but that none of the permissions in that role were used in the past 90 days:

{
  "name": "projects/1069248613794/locations/us/insightTypes/google.iam.policy.Insight/insights/101d03ad-6148-4628-943e-fcf1a3af6b57",
  "description": "0 of the permissions in this role binding were used in the past 90 days.",
  "content": {
    "role": "roles/bigquery.dataEditor",
    "member": "projectEditor:my-project",
    "condition": {
      "expression": "",
      "title": "",
      "description": "",
      "location": ""
    },
    "exercisedPermissions": [],
    "inferredPermissions": [],
    "currentTotalPermissionsCount": "37"
  },
  "lastRefreshTime": "2024-02-02T08:00:00Z",
  "observationPeriod": "7779600s",
  "stateInfo": {
    "state": "ACTIVE"
  },
  "category": "SECURITY",
  "associatedRecommendations": [
    {
      "recommendation": "projects/1069248613794/locations/us/recommenders/google.iam.policy.Recommender/recommendations/9327f952-1ceb-488e-9e49-f17eb21f6e5e"
    }
  ],
  "targetResources": [
    "//bigquery.googleapis.com/projects/my-project/datasets/dataset-1"
  ],
  "insightSubtype": "PERMISSIONS_USAGE_BIGQUERY_DATASET",
  "etag": "\"35d4af47524d3f0c\"",
  "severity": "LOW"
}

To learn more about the components of an insight, see Review dataset-level policy insights on this page.

Review dataset-level policy insights

After you get a single insight, you can review its contents to understand the pattern of resource usage that it highlights.

An insight's content is determined by its subtypes. Dataset-level policy insights (google.iam.policy.Insight) insights have the PERMISSIONS_USAGE_BIGQUERY_DATASET subtype.

PERMISSIONS_USAGE_BIGQUERY_DATASET 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 always SECURITY.
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 new etag value is assigned.

To change the state of an insight, you must provide the etag of the existing insight. Using the etag 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:
```
projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID
```
The placeholders have the following values:
- PROJECT_ID: The ID of the project where the insight was generated.
- LOCATION: The location of the dataset that the insight is for.
- 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 at lastRefreshTime and begins at lastRefreshTime minus observationPeriod.
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 marked CLAIMED, SUCCEEDED, or FAILED, or the insight was accepted directly. When an insight is in the ACCEPTED 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 dataset that the insight is for. For example, //bigquery.googleapis.com/projects/my-project/datasets/my-dataset.

Mark a dataset-level 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.

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.
PROJECT_ID: The ID of the project that you want to manage insights for.
LOCATION: The location of the dataset whose insight you want to mark as ACCEPTED.
ETAG: An identifier for a version of the insight. To get the etag, do the following:
1. Get the insight using the gcloud recommender insights describe command.
2. Find and copy the etag value from the output, including the enclosing quotes. For example, "d3cdec23cc712bd0".

gcloud recommender insights mark-accepted INSIGHT_ID \
    --insight-type=google.iam.policy.Insight \
    --project=PROJECT_ID \
    --location=LOCATION \
    --etag=ETAG

The output shows the insight, now with the state of ACCEPTED:

associatedRecommendations:
- recommendation: projects/1069248613794/locations/us/recommenders/google.iam.policy.Recommender/recommendations/9327f951-1ceb-488e-9e49-f17eb21f6e5e
category: SECURITY
content:
  condition:
    description: ''
    expression: ''
    location: ''
    title: ''
  currentTotalPermissionsCount: '37'
  exercisedPermissions: []
  inferredPermissions: []
  member: projectEditor:my-project
  role: roles/bigquery.dataEditor
description: 0 of the permissions in this role binding were used in the past 90 days.
etag: '"5f2f352a738f7a24"'
insightSubtype: PERMISSIONS_USAGE_BIGQUERY_DATASET
lastRefreshTime: '2024-02-04T08:00:00Z'
name: projects/1069248613794/locations/us/insightTypes/google.iam.policy.Insight/insights/101d03ad-6148-4628-943e-fcf1a3af6b57
observationPeriod: 7776000s
severity: LOW
stateInfo:
  state: ACCEPTED
targetResources:
- //bigquery.googleapis.com/projects/my-project/datasets/dataset-1

To learn more about the state info of an insight, see Review dataset-level 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:

PROJECT_ID: The ID of the project that you want to manage insights for.
LOCATION: The location of the dataset whose insight you want to mark as ACCEPTED.
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. 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/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID:markAccepted

Request JSON body:

{
  "etag": "ETAG"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Save the request body in a file named request.json, and execute the following command:

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/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID:markAccepted"

PowerShell (Windows)

Save the request body in a file named request.json, and execute the following command:

$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/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID:markAccepted" | Select-Object -Expand Content

The response contains the insight, now with the state of ACCEPTED:

{
  "name": "projects/1069248613794/locations/us/insightTypes/google.iam.policy.Insight/insights/101d03ad-6148-4628-943e-fcf1a3af6b57",
  "description": "0 of the permissions in this role binding were used in the past 90 days.",
  "content": {
    "role": "roles/bigquery.dataEditor",
    "member": "projectEditor:my-project",
    "condition": {
      "expression": "",
      "title": "",
      "description": "",
      "location": ""
    },
    "exercisedPermissions": [],
    "inferredPermissions": [],
    "currentTotalPermissionsCount": "37"
  },
  "lastRefreshTime": "2024-02-02T08:00:00Z",
  "observationPeriod": "7779600s",
  "stateInfo": {
    "state": "ACCEPTED"
  },
  "category": "SECURITY",
  "associatedRecommendations": [
    {
      "recommendation": "projects/1069248613794/locations/us/recommenders/google.iam.policy.Recommender/recommendations/9327f952-1ceb-488e-9e49-f17eb21f6e5e"
    }
  ],
  "targetResources": [
    "//bigquery.googleapis.com/projects/my-project/datasets/dataset-1"
  ],
  "insightSubtype": "PERMISSIONS_USAGE_BIGQUERY_DATASET",
  "etag": "\"35d4af47524d3f0c\"",
  "severity": "LOW"
}

To learn more about the state info of an insight, see Review dataset-level policy insights on this page.

What's next

Learn how to view and apply policy recommendations for BigQuery datasets.
Use the Recommendation Hub to view and manage all recommendations for your project, including IAM recommendations.

Review policy insights for BigQuery datasets

Before you begin

Required roles

Required permissions

List dataset-level policy insights

gcloud

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Get a single dataset-level policy insight

gcloud

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Review dataset-level policy insights

Mark a dataset-level policy insight as ACCEPTED

gcloud

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

What's next

Mark a dataset-level policy insight as `ACCEPTED`