Analisar e aplicar recomendações de função para conjuntos de dados do BigQuery

Nesta página, explicamos como visualizar, entender e aplicar recomendações de função do IAM para conjuntos de dados do BigQuery. As recomendações de papéis ajudam a aplicar o princípio de privilégio mínimo, garantindo que os participantes tenham apenas as permissões de que realmente precisam.

Antes de começar

  • Enable the IAM and Recommender APIs.

    Enable the APIs

  • Entenda as recomendações por papel.

  • Configure a autenticação.

    Select the tab for how you plan to use the samples on this page:

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    REST

    Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para gcloud CLI.

      Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init

    Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud.

Papéis do IAM obrigatórios

Para conseguir as permissões necessárias para gerenciar recomendações de função no nível do conjunto de dados, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para gerenciar recomendações de função no nível do conjunto de dados. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para gerenciar recomendações de função no nível do conjunto de dados:

  • Para conferir as recomendações:
    • iam.roles.get no seu projeto
    • iam.roles.list no seu projeto
    • recommender.iamPolicyRecommendations.get no seu projeto
    • recommender.iamPolicyRecommendations.list no seu projeto
    • recommender.iamPolicyInsights.get no seu projeto
    • recommender.iamPolicyInsights.list no seu projeto
    • bigquery.datasets.getIamPolicy no conjunto de dados
  • Para aplicar e dispensar recomendações:
    • recommender.iamPolicyRecommendations.update no seu projeto
    • bigquery.datasets.setIamPolicy no conjunto de dados

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Analisar e aplicar recomendações

É possível analisar e aplicar recomendações de função no nível do conjunto de dados com a Google Cloud CLI e a API Recommender.

gcloud

Revisar suas recomendações:

Para listar as recomendações no nível do conjunto de dados, execute o comando gcloud recommender recommendations list, filtrando apenas as recomendações do conjunto de dados do BigQuery:

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

Substitua os seguintes valores:

  • LOCATION: a região em que seus conjuntos de dados do Cloud Storage estão localizados. Por exemplo, us ou us-central1.
  • PROJECT_ID: o ID do projeto Google Cloud que contém seus conjuntos de dados do BigQuery. Os IDs do projeto são strings alfanuméricas, como my-project.

A resposta é semelhante ao exemplo a seguir. Neste exemplo, todos os usuários com a função de editor no projeto my-project (projectEditor:my-project) têm a função de editor de dados do BigQuery (roles/bigquery.dataEditor) no conjunto de dados dataset-1. No entanto, esse papel não foi usado nos últimos 90 dias. Por isso, a recomendação de função sugere que você revogue o papel:

[
  {
    "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"
    ]
  }
]

Avalie cada recomendação com cuidado e pense em como isso mudará o acesso do participante aos recursos Google Cloud . Para saber como analisar as recomendações da CLI gcloud, consulte Analisar recomendações nesta página.

Para aplicar uma recomendação:

  1. Use o comando gcloud recommender recommendations mark-claimed para alterar o estado da recomendação para CLAIMED,, o que impede que a recomendação seja alterada enquanto você a aplica:

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

    Substitua os seguintes valores:

    • RECOMMENDATION_ID: o identificador exclusivo da recomendação. Esse valor é exibido no final do campo name na recomendação. Por exemplo, se o campo name for projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f, o ID de recomendação será fb927dc1-9695-4436-0000-f0f285007c0f.
    • LOCATION: a região em que o conjunto de dados do BigQuery está localizado, por exemplo, us ou us-central1.
    • PROJECT_ID: o ID do projeto Google Cloud que contém os conjuntos de dados do BigQuery. Os IDs do projeto são strings alfanuméricas, como my-project.
    • FORMAT: o formato da resposta. Use json ou yaml.
    • ETAG: o valor do campo etag na recomendação, como "dd0686e7136a4cbb". Observe que esse valor pode incluir aspas.
    • STATE_METADATA: opcional. Pares de chave-valor separados por vírgula que contenham a opção de metadados sobre a recomendação. Por exemplo, --state-metadata=reviewedBy=alice,priority=high. Os metadados substituem o campo stateInfo.stateMetadata na recomendação.

    Se o comando for bem-sucedido, a resposta mostrará a recomendação em um estado CLAIMED, conforme mostrado no exemplo a seguir. Para esclarecer, o exemplo omite a maioria dos campos:

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

  2. Receba a política de permissão do conjunto de dados e, em seguida, modifique e defina a política de permissão para que ela reflita a recomendação.

  3. Se você tiver conseguido aplicar a recomendação, atualize o estado dela para SUCCEEDED. Caso contrário, atualize o estado para FAILED:

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

    Substitua os seguintes valores:

    • COMMAND: use mark-succeeded se tiver conseguido aplicar a recomendação. Caso contrário, use mark-failed.

    • RECOMMENDATION_ID: o identificador exclusivo da recomendação. Esse valor é exibido no final do campo name na recomendação. Por exemplo, se o campo name for projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f, o ID de recomendação será fb927dc1-9695-4436-0000-f0f285007c0f.
    • LOCATION: a região em que o conjunto de dados do BigQuery está localizado, por exemplo, us ou us-central1.
    • PROJECT_ID: o ID do projeto Google Cloud que contém os conjuntos de dados do BigQuery. Os IDs do projeto são strings alfanuméricas, como my-project.
    • FORMAT: o formato da resposta. Use json ou yaml.
    • ETAG: o valor do campo etag na recomendação, como "dd0686e7136a4cbb". Observe que esse valor pode incluir aspas.
    • STATE_METADATA: opcional. Pares de chave-valor separados por vírgula que contenham a opção de metadados sobre a recomendação. Por exemplo, --state-metadata=reviewedBy=alice,priority=high. Os metadados substituem o campo stateInfo.stateMetadata na recomendação.

    Por exemplo, se você tiver marcado a recomendação como bem-sucedida, a resposta mostrará a recomendação em um estado SUCCEEDED. Para esclarecer, este exemplo omite a maioria dos campos:

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

REST

Revisar suas recomendações:

Para listar todas as recomendações disponíveis para seus conjuntos de dados do BigQuery, use o método recommendations.list da API Recommender.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projetoGoogle Cloud que contém os conjuntos de dados do BigQuery. Os IDs do projeto são strings alfanuméricas, como my-project.
  • LOCATION: a região em que os conjuntos de dados do BigQuery estão localizados, por exemplo, us ou us-central1.
  • PAGE_SIZE: opcional. O número máximo de resultados a serem retornados a partir dessa solicitação. Se não especificado, o servidor determinará o número de resultados a serem retornados. Se o número de recomendações for maior que o tamanho da página, a resposta conterá um token de paginação que é possível usar para recuperar a próxima página de resultados.
  • PAGE_TOKEN: opcional. O token de paginação retornado em uma resposta anterior desse método. Se especificada, a lista de recomendações começará onde a solicitação anterior foi finalizada.
  • PROJECT_ID: o ID do projeto Google Cloud . Os IDs do projeto são strings alfanuméricas, como my-project.

Método HTTP e 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

Para enviar a solicitação, expanda uma destas opções:

A resposta é semelhante ao exemplo a seguir. Neste exemplo, todos os usuários com a função de editor no projeto "my-project" (projectEditor:my-project) têm a função de editor de dados do BigQuery (roles/bigquery.dataEditor) no conjunto de dados dataset-1. No entanto, esse papel não foi usado nos últimos 90 dias. Por isso, a recomendação do papel sugere que você revogue o papel: 

{
  "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"
      ]
    }
  ]
}

Avalie cada recomendação com cuidado e pense em como isso mudará o acesso do participante aos recursos Google Cloud . Para saber como analisar as recomendações da API REST, consulte Analisar recomendações nesta página.

Para aplicar uma recomendação:

  1. Marque a recomendação como CLAIMED:

    Para marcar uma recomendação como CLAIMED, o que impede que ela seja alterada enquanto você a aplica, use o método recommendations.markClaimed da API Recommender.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do projetoGoogle Cloud que contém os conjuntos de dados do BigQuery. Os IDs do projeto são strings alfanuméricas, como my-project.
    • LOCATION: a região em que o conjunto de dados do BigQuery está localizado, por exemplo, us ou us-central1.
    • RECOMMENDATION_ID: o identificador exclusivo da recomendação. Esse valor é exibido no final do campo name na recomendação. Por exemplo, se o campo name for projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f, o ID de recomendação será fb927dc1-9695-4436-0000-f0f285007c0f.
    • ETAG: o valor do campo etag na recomendação, como "dd0686e7136a4cbb". Use barras invertidas para escapar das aspas, por exemplo, "\"df7308cca9719dcc\"".
    • STATE_METADATA: opcional. Um objeto que contém pares de chave-valor com a opção de metadados sobre a recomendação. Por exemplo, {"reviewedBy": "alice", "priority": "high"}. Os metadados substituem o campo stateInfo.stateMetadata na recomendação.

    Método HTTP e URL:

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

    Corpo JSON da solicitação:

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

    Para enviar a solicitação, expanda uma destas opções:

    A resposta mostra a recomendação em um estado CLAIMED, conforme mostrado no exemplo a seguir. Para esclarecer, este exemplo omite a maioria dos campos: 

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

  2. Verifique a política de permissão do projeto e modifique a política de permissão para que ela reflita a recomendação.

  3. Se você tiver conseguido aplicar a recomendação, atualize o estado dela para SUCCEEDED. Caso contrário, atualize o estado para FAILED:

    SUCCEEDED

    Para marcar uma recomendação como SUCCEEDED, indicando que você conseguiu aplicá-la, use o método recommendations.markSucceeded da API Recommender.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do projetoGoogle Cloud que contém os conjuntos de dados do BigQuery. Os IDs do projeto são strings alfanuméricas, como my-project.
    • LOCATION: a região em que o conjunto de dados do BigQuery está localizado, por exemplo, us ou us-central1.
    • RECOMMENDATION_ID: o identificador exclusivo da recomendação. Esse valor é exibido no final do campo name na recomendação. Por exemplo, se o campo name for projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f, o ID de recomendação será fb927dc1-9695-4436-0000-f0f285007c0f.
    • ETAG: o valor do campo etag na recomendação, como "dd0686e7136a4cbb". Use barras invertidas para escapar das aspas, por exemplo, "\"df7308cca9719dcc\"".
    • STATE_METADATA: opcional. Um objeto que contém pares de chave-valor com a opção de metadados sobre a recomendação. Por exemplo, {"reviewedBy": "alice", "priority": "high"}. Os metadados substituem o campo stateInfo.stateMetadata na recomendação.

    Método HTTP e URL:

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

    Corpo JSON da solicitação:

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

    Para enviar a solicitação, expanda uma destas opções:

    A resposta mostra a recomendação em um estado SUCCEEDED, conforme mostrado no exemplo a seguir. Para esclarecer, este exemplo omite a maioria dos campos: 

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

    FAILED

    Para marcar uma recomendação como FAILED, indicando que não foi possível aplicá-la, use o método recommendations.markFailed da API Recommender.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do projetoGoogle Cloud que contém os conjuntos de dados do BigQuery. Os IDs do projeto são strings alfanuméricas, como my-project.
    • LOCATION: a região em que o conjunto de dados do BigQuery está localizado, por exemplo, us ou us-central1.
    • RECOMMENDATION_ID: o identificador exclusivo da recomendação. Esse valor é exibido no final do campo name na recomendação. Por exemplo, se o campo name for projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f, o ID de recomendação será fb927dc1-9695-4436-0000-f0f285007c0f.
    • ETAG: o valor do campo etag na recomendação, como "dd0686e7136a4cbb". Use barras invertidas para escapar das aspas, por exemplo, "\"df7308cca9719dcc\"".
    • STATE_METADATA: opcional. Um objeto que contém pares de chave-valor com a opção de metadados sobre a recomendação. Por exemplo, {"reviewedBy": "alice", "priority": "high"}. Os metadados substituem o campo stateInfo.stateMetadata na recomendação.

    Método HTTP e URL:

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

    Corpo JSON da solicitação:

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

    Para enviar a solicitação, expanda uma destas opções:

    A resposta mostra a recomendação em um estado FAILED, conforme mostrado no exemplo a seguir. Para esclarecer, este exemplo omite a maioria dos campos: 

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

Entender as recomendações

Cada recomendação inclui informações para ajudar você a entender por que ela foi feita.

Para detalhes sobre os campos de uma recomendação, consulte a referência Recommendation.

Para ver o uso da permissão na qual essa recomendação se baseia, consulte os insights associados a ela. Esses insights são listados no campo associatedInsights. Para visualizar um insight de política associado à recomendação, faça o seguinte:

  1. Copie o ID do insight associado. O ID é tudo depois de insights/ no campo insight. Por exemplo, se o campo insight for projects/123456789012/locations/us/insightTypes/google.iam.policy.Insight/insights/7849add9-73c0-419e-b169-42b3671173fb, o ID do insight será 7849add9-73c0-419e-b169-42b3671173fb.
  2. Siga as instruções para receber um insight de política usando o ID do insight que você copiou.

A seguir