gcloud

Review your recommendations:

To list your dataset-level recommendations, run thegcloud recommender recommendations listcommand, filtering for only BigQuery dataset recommendations:

gcloudrecommenderrecommendationslist\--location=LOCATION\--recommender=google.iam.policy.Recommender\--project=PROJECT_ID\--format=json\--filter="recommenderSubtype:REMOVE_ROLE_BIGQUERY_DATASET OR recommenderSubtype:REPLACE_ROLE_BIGQUERY_DATASET"

Replace the following values:

• LOCATION: The region where your Cloud Storagedatasets are located—for example,us orus-central1.
• PROJECT_ID: The ID of the Google Cloud projectthat contains your BigQuery datasets. Project IDs arealphanumeric strings, likemy-project.

The response is similar to the following example. In this example, all userswith the Editor role on the projectmy-project(projectEditor:my-project) have the BigQuery Data Editor role(roles/bigquery.dataEditor) on the datasetdataset-1.However, this role hasn't been used in the past90 days. As a result, the role recommendation suggests thatyou revoke the role:

[{"associatedInsights":[{"insight":"projects/1069248613794/locations/us/insightTypes/google.iam.policy.Insight/insights/984eccca-0241-472f-baab-2557dd0d7282"}],"content":{"operationGroups":[{"operations":[{"action":"remove","path":"/iamPolicy/bindings/*/members/*","pathFilters":{"/iamPolicy/bindings/*/condition/expression":"","/iamPolicy/bindings/*/members/*":"projectEditor:my-project","/iamPolicy/bindings/*/role":"roles/bigquery.dataEditor"},"resource":"//bigquery.googleapis.com/projects/my-project/datasets/dataset-1","resourceType":"bigquery.googleapis.com/Dataset"}]}],"overview":{"addedRoles":[],"member":"projectEditor:my-project","minimumObservationPeriodInDays":"0","removedRole":"roles/bigquery.dataEditor","resource":"//bigquery.googleapis.com/projects/my-project/datasets/dataset-1"}},"description":"This role has not been used during the observation window.","etag":"\"3b123bc08d028128\"","lastRefreshTime":"2024-02-04T08:00:00Z","name":"projects/1069248613794/locations/us/recommenders/google.iam.policy.Recommender/recommendations/0e9831fe-6810-476b-b14d-2b64bda17288","primaryImpact":{"category":"SECURITY","securityProjection":{"details":{"revokedIamPermissionsCount":37}}},"priority":"P4","recommenderSubtype":"REMOVE_ROLE_BIGQUERY_DATASET","stateInfo":{"state":"ACTIVE"},"targetResources":["//bigquery.googleapis.com/projects/my-project/datasets/dataset-1"]},{"associatedInsights":[{"insight":"projects/1069248613794/locations/us/insightTypes/google.iam.policy.Insight/insights/9d11057e-9c71-410f-ad55-fc82d87761d0"}],"content":{"operationGroups":[{"operations":[{"action":"remove","path":"/iamPolicy/bindings/*/members/*","pathFilters":{"/iamPolicy/bindings/*/condition/expression":"","/iamPolicy/bindings/*/members/*":"user:alicexz@google.com","/iamPolicy/bindings/*/role":"roles/bigquery.dataOwner"},"resource":"//bigquery.googleapis.com/projects/my-project/datasets/dataset-1","resourceType":"bigquery.googleapis.com/Dataset"}]}],"overview":{"addedRoles":[],"member":"user:alicexz@google.com","minimumObservationPeriodInDays":"0","removedRole":"roles/bigquery.dataOwner","resource":"//bigquery.googleapis.com/projects/my-project/datasets/dataset-1"}},"description":"This role has not been used during the observation window.","etag":"\"1da285f7aa6438f1\"","lastRefreshTime":"2024-02-04T08:00:00Z","name":"projects/1069248613794/locations/us/recommenders/google.iam.policy.Recommender/recommendations/56013294-cf81-402a-8cde-25489545777c","primaryImpact":{"category":"SECURITY","securityProjection":{"details":{"revokedIamPermissionsCount":64}}},"priority":"P4","recommenderSubtype":"REMOVE_ROLE_BIGQUERY_DATASET","stateInfo":{"state":"ACTIVE"},"targetResources":["//bigquery.googleapis.com/projects/my-project/datasets/dataset-1"]}]

Review each recommendation carefully and consider when it was last refreshedand how it will change the principal's access to Google Cloud resources.To learn how to review recommendations from the gcloud CLI, seeReview recommendations on this page.

To apply a recommendation:

1. Use thegcloud recommender recommendations mark-claimed commandto change the recommendation's state toCLAIMED, which prevents therecommendation from changing while you apply it:

   gcloudrecommenderrecommendationsmark-claimed\RECOMMENDATION_ID\--location=LOCATION\--recommender=google.iam.policy.Recommender\--project=PROJECT_ID\--format=FORMAT\--etag=ETAG\--state-metadata=STATE_METADATA

   Replace the following values:

   • RECOMMENDATION_ID: The unique identifier for the recommendation. This value appears at the end of thename field in the recommendation. For example, if thename field isprojects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f, the recommendation ID isfb927dc1-9695-4436-0000-f0f285007c0f.
   • LOCATION: The region where your BigQuery dataset is located—for example,us orus-central1.
   • PROJECT_ID: The ID of the Google Cloud project that contains your BigQuery datasets. Project IDs are alphanumeric strings, likemy-project.
   • FORMAT: The format of the response. Usejson oryaml.
   • ETAG: The value of theetag field in the recommendation, such as"dd0686e7136a4cbb". Note that this value can include quotes.
   • STATE_METADATA: Optional. Comma-separated key-value pairs that contain your choice of metadata about the recommendation. For example,--state-metadata=reviewedBy=alice,priority=high. The metadata replaces thestateInfo.stateMetadata field in the recommendation.

   If the command succeeds, the response shows the recommendation in aCLAIMED state, as shown in the following example. For clarity, the exampleomits most fields:

   ..."priority":"P1","recommenderSubtype":"REMOVE_ROLE_BIGQUERY_DATASET","stateInfo":{"state":"CLAIMED"}...

2. Get the allow policy for the dataset, thenmodify and set the allow policy so that it reflects therecommendation.

3. Update the recommendation's state toSUCCEEDED, if you were able to applythe recommendation, orFAILED, if you could not apply the recommendation:

   gcloudrecommenderrecommendationsCOMMAND\RECOMMENDATION_ID\--location=LOCATION\--recommender=google.iam.policy.Recommender\--project=PROJECT_ID\--format=FORMAT\--etag=ETAG\--state-metadata=STATE_METADATA

   Replace the following values:

   • COMMAND: Usemark-succeeded, if you were able to apply the recommendation, ormark-failed, if you could not apply the recommendation.
   • RECOMMENDATION_ID: The unique identifier for the recommendation. This value appears at the end of thename field in the recommendation. For example, if thename field isprojects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f, the recommendation ID isfb927dc1-9695-4436-0000-f0f285007c0f.
   • LOCATION: The region where your BigQuery dataset is located—for example,us orus-central1.
   • PROJECT_ID: The ID of the Google Cloud project that contains your BigQuery datasets. Project IDs are alphanumeric strings, likemy-project.
   • FORMAT: The format of the response. Usejson oryaml.
   • ETAG: The value of theetag field in the recommendation, such as"dd0686e7136a4cbb". Note that this value can include quotes.
   • STATE_METADATA: Optional. Comma-separated key-value pairs that contain your choice of metadata about the recommendation. For example,--state-metadata=reviewedBy=alice,priority=high. The metadata replaces thestateInfo.stateMetadata field in the recommendation.

   For example, if you marked the recommendation as having succeeded, theresponse shows the recommendation in aSUCCEEDED state. For clarity, thisexample omits most fields:

   ..."priority":"P1","recommenderSubtype":"REMOVE_ROLE_BIGQUERY_DATASET","stateInfo":{"state":"SUCCEEDED"}...

REST

Review your recommendations:

To list all available recommendations for your BigQuery datasets, use the Recommender API'srecommendations.list method.

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

• PROJECT_ID: The ID of theGoogle Cloud project that contains your BigQuery datasets. Project IDs arealphanumeric strings, likemy-project.
• LOCATION: The region where yourBigQuery datasets are located—for example,us orus-central1.
• PAGE_SIZE: Optional. The maximum number of results to return from this request. If not specified, the server will determine the number of results to return. If the number of recommendations is greater than the page size, the response contains a pagination token that you can use to retrieve the next page of results.
• PAGE_TOKEN: Optional. The pagination token returned in an earlier response from this method. If specified, the list of recommendations will start where the previous request ended.
• PROJECT_ID: Your Google Cloud projectID. Project IDs are alphanumeric strings, likemy-project.

HTTP method and URL:

GET https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/recommenders/google.iam.policy.Recommender/recommendations?filter=recommenderSubtype%20%3D%20REMOVE_ROLE_BIGQUERY_DATASET%20OR%20recommenderSubtype%20%3D%20REPLACE_ROLE_BIGQUERY_DATASET&pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN

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/projects/PROJECT_ID/locations/LOCATION/recommenders/google.iam.policy.Recommender/recommendations?filter=recommenderSubtype%20%3D%20REMOVE_ROLE_BIGQUERY_DATASET%20OR%20recommenderSubtype%20%3D%20REPLACE_ROLE_BIGQUERY_DATASET&pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN"

$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/recommenders/google.iam.policy.Recommender/recommendations?filter=recommenderSubtype%20%3D%20REMOVE_ROLE_BIGQUERY_DATASET%20OR%20recommenderSubtype%20%3D%20REPLACE_ROLE_BIGQUERY_DATASET&pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" | Select-Object -Expand Content

The response is similar to the following example. In this example, 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 datasetdataset-1. However, this role hasn't been used in the past 90 days. As a result, the role recommendation suggests that you revoke the role:

{  "recommendations": [    {      "name": "projects/1069248613794/locations/us/recommenders/google.iam.policy.Recommender/recommendations/0e9831fe-6810-476b-b14d-2b64bda17288",      "description": "This role has not been used during the observation window.",      "lastRefreshTime": "2024-02-02T08:00:00Z",      "primaryImpact": {        "category": "SECURITY",        "securityProjection": {          "details": {            "revokedIamPermissionsCount": 37          }        }      },      "content": {        "operationGroups": [          {            "operations": [              {                "action": "remove",                "resourceType": "bigquery.googleapis.com/Dataset",                "resource": "//bigquery.googleapis.com/projects/my-project/datasets/dataset-1",                "path": "/iamPolicy/bindings/*/members/*",                "pathFilters": {                  "/iamPolicy/bindings/*/condition/expression": "",                  "/iamPolicy/bindings/*/members/*": "projectEditor:my-project",                  "/iamPolicy/bindings/*/role": "roles/bigquery.dataEditor"                }              }            ]          }        ],        "overview": {          "resource": "//bigquery.googleapis.com/projects/my-project/datasets/dataset-1",          "member": "projectEditor:my-project",          "removedRole": "roles/bigquery.dataEditor",          "addedRoles": [],          "minimumObservationPeriodInDays": "0"        }      },      "stateInfo": {        "state": "ACTIVE"      },      "etag": "\"d008ad3780bad5e0\"",      "recommenderSubtype": "REMOVE_ROLE_BIGQUERY_DATASET",      "associatedInsights": [        {          "insight": "projects/1069248613794/locations/us/insightTypes/google.iam.policy.Insight/insights/984eccca-0241-472f-baab-2557dd0d7282"        }      ],      "priority": "P4",      "targetResources": [        "//bigquery.googleapis.com/projects/my-project/datasets/dataset-1"      ]    }  ]}

Review each recommendation carefully and consider when it was last refreshedand how it will change the principal's access to Google Cloud resources.To learn how to review recommendations from the REST API, seeReview recommendations on this page.

To apply a recommendation:

1. Mark the recommendation asCLAIMED:

   To mark a recommendation asCLAIMED, which prevents the recommendation from changing while you apply it, use the Recommender API'srecommendations.markClaimed method.

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

   • PROJECT_ID: The ID of theGoogle Cloud project that contains your BigQuery datasets. Project IDs arealphanumeric strings, likemy-project.
   • LOCATION: The region where yourBigQuery dataset is located—for example,us orus-central1.
   • RECOMMENDATION_ID: The unique identifierfor the recommendation. This value appears at the end of thename field in therecommendation. For example, if thename field isprojects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f,the recommendation ID isfb927dc1-9695-4436-0000-f0f285007c0f.
   • ETAG: The value of theetag field in the recommendation, such as"dd0686e7136a4cbb". Usebackslashes to escape quotes, for example,"\"df7308cca9719dcc\"".
   • STATE_METADATA: Optional. An object thatcontains key-value pairs with your choice of metadata about the recommendation. For example,{"reviewedBy": "alice", "priority": "high"}. The metadata replaces thestateInfo.stateMetadata field in the recommendation.

   HTTP method and URL:

   POST https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/recommenders/google.iam.policy.Recommender/recommendations/RECOMMENDATION_ID:markClaimed

   Request JSON body:

   {  "etag": "ETAG",  "stateMetadata": {    "STATE_METADATA"  }}

   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 thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

   Save the request body in a file namedrequest.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/recommenders/google.iam.policy.Recommender/recommendations/RECOMMENDATION_ID:markClaimed"

   PowerShell (Windows)

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

   Save the request body in a file namedrequest.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/recommenders/google.iam.policy.Recommender/recommendations/RECOMMENDATION_ID:markClaimed" | Select-Object -Expand Content

   The response shows the recommendation in aCLAIMED state, as shown in the following example. For clarity, this example omits most fields:

   ..."stateInfo": {  "state": "CLAIMED"},"etag": "\"7caf4103d7669e12\"","recommenderSubtype": "REMOVE_ROLE_BIGQUERY_DATASET",...

2. Get the allow policy for the project, thenmodify the allow policy so that it reflects therecommendation.

3. Update the recommendation's state toSUCCEEDED, if you were able to applythe recommendation, orFAILED, if you could not apply the recommendation:

   SUCCEEDED

   To mark a recommendation asSUCCEEDED, indicating that you were able to apply it, use the Recommender API'srecommendations.markSucceeded method.

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

   • PROJECT_ID: The ID of theGoogle Cloud project that contains your BigQuery datasets. Project IDs arealphanumeric strings, likemy-project.
   • LOCATION: The region where yourBigQuery dataset is located—for example,us orus-central1.
   • RECOMMENDATION_ID: The unique identifierfor the recommendation. This value appears at the end of thename field in therecommendation. For example, if thename field isprojects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f,the recommendation ID isfb927dc1-9695-4436-0000-f0f285007c0f.
   • ETAG: The value of theetag field in the recommendation, such as"dd0686e7136a4cbb". Usebackslashes to escape quotes, for example,"\"df7308cca9719dcc\"".
   • STATE_METADATA: Optional. An object thatcontains key-value pairs with your choice of metadata about the recommendation. For example,{"reviewedBy": "alice", "priority": "high"}. The metadata replaces thestateInfo.stateMetadata field in the recommendation.

   HTTP method and URL:

   POST https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/recommenders/google.iam.policy.Recommender/recommendations/RECOMMENDATION_ID:markSucceeded

   Request JSON body:

   {  "etag": "ETAG",  "stateMetadata": {    "STATE_METADATA"  }}

   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 thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

   Save the request body in a file namedrequest.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/recommenders/google.iam.policy.Recommender/recommendations/RECOMMENDATION_ID:markSucceeded"

   PowerShell (Windows)

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

   Save the request body in a file namedrequest.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/recommenders/google.iam.policy.Recommender/recommendations/RECOMMENDATION_ID:markSucceeded" | Select-Object -Expand Content

   The response shows the recommendation in aSUCCEEDED state, as shown in the following example. For clarity, this example omits most fields:

   ..."stateInfo": {  "state": "SUCCEEDED"},"etag": "\"7caf4103d7669e12\"","recommenderSubtype": "REMOVE_ROLE_BIGQUERY_DATASET",...

   FAILED

   To mark a recommendation asFAILED, indicating that you were not able to apply it, use the Recommender API'srecommendations.markFailed method.

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

   • PROJECT_ID: The ID of theGoogle Cloud project that contains your BigQuery datasets. Project IDs arealphanumeric strings, likemy-project.
   • LOCATION: The region where yourBigQuery dataset is located—for example,us orus-central1.
   • RECOMMENDATION_ID: The unique identifierfor the recommendation. This value appears at the end of thename field in therecommendation. For example, if thename field isprojects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f,the recommendation ID isfb927dc1-9695-4436-0000-f0f285007c0f.
   • ETAG: The value of theetag field in the recommendation, such as"dd0686e7136a4cbb". Usebackslashes to escape quotes, for example,"\"df7308cca9719dcc\"".
   • STATE_METADATA: Optional. An object thatcontains key-value pairs with your choice of metadata about the recommendation. For example,{"reviewedBy": "alice", "priority": "high"}. The metadata replaces thestateInfo.stateMetadata field in the recommendation.

   HTTP method and URL:

   POST https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/recommenders/google.iam.policy.Recommender/recommendations/RECOMMENDATION_ID:markFailed

   Request JSON body:

   {  "etag": "ETAG",  "stateMetadata": {    "STATE_METADATA"  }}

   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 thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

   Save the request body in a file namedrequest.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/recommenders/google.iam.policy.Recommender/recommendations/RECOMMENDATION_ID:markFailed"

   PowerShell (Windows)

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

   Save the request body in a file namedrequest.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/recommenders/google.iam.policy.Recommender/recommendations/RECOMMENDATION_ID:markFailed" | Select-Object -Expand Content

   The response shows the recommendation in aFAILED state, as shown in the following example. For clarity, this example omits most fields:

   ..."stateInfo": {  "state": "FAILED"},"etag": "\"7caf4103d7669e12\"","recommenderSubtype": "REMOVE_ROLE_BIGQUERY_DATASET",...