Analisar insights de política para conjuntos de dados do BigQuery

Nesta página, mostramos como gerenciar insights de política no nível do conjunto de dados, que são descobertas baseadas em machine learning sobre o uso de permissões para os conjuntos de dados do BigQuery. Os insights de política podem ajudar a identificar quais principais têm permissões desnecessárias.

Nesta página, o foco são os insights de políticas para conjuntos de dados. O recomendador também oferece insights de política para os seguintes tipos de recursos:

Às vezes, os insights de política no nível do conjunto de dados estão vinculados às recomendações de papéis. As recomendações de papéis sugerem ações que podem ser tomadas para corrigir os problemas identificados pelos insights de políticas no nível do conjunto de dados.

Antes de começar

Funções exigidas

Se quiser ter as permissões necessárias para gerenciar insights de política no nível do conjunto de dados, peça ao administrador para conceder a você os seguintes papéis do IAM no seu projeto:

  • Proprietário de dados do BigQuery (`roles/bigquery.dataOwner`)
  • Administrador do recomendador do IAM ("roles/recommender.iamAdmin")
  • Gerencie insights de política no nível do conjunto de dados com a CLI gcloud ou a API REST: Service Usage Consumer ("roles/serviceusage.serviceUsageConsumer")

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esses papéis predefinidos têm as permissões necessárias para gerenciar insights de política 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 insights de política no nível do conjunto de dados:

  • Confira insights de política no nível do conjunto de dados:
    • recommender.iamPolicyInsights.get
    • recommender.iamPolicyInsights.list
  • Modifique insights de política no nível do conjunto de dados: recommender.iamPolicyInsights.update
  • Gerencie insights de política no nível do conjunto de dados com a CLI gcloud ou a API REST: serviceusage.services.use

Talvez você também consiga receber essas permissões com papéis personalizados ou outros papéis predefinidos.

Listar insights de política no nível do conjunto de dados

Para listar todos os insights de política no nível do conjunto de dados do seu projeto, use um dos seguintes métodos:

gcloud

Use o comando gcloud recommender insights list para visualizar todos os insights de política no nível do conjunto de dados para seu projeto.

Antes de executar o comando, substitua os seguintes valores:

  • PROJECT_ID: o ID do projeto para o qual você quer listar insights.
  • LOCATION: o local dos conjuntos de dados que têm insights você quer listar.
gcloud recommender insights list --insight-type=google.iam.policy.Insight \
    --project=PROJECT_ID \
    --location=LOCATION\
    --filter="insightSubtype:PERMISSIONS_USAGE_BIGQUERY_DATASET"

A saída lista todos os insights de política no nível do conjunto de dados para seu projeto no local especificado. Exemplo:

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

O método insights.list da API Recommender lista todos os insights de políticas no nível do conjunto de dados para seu projeto.

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

  • PROJECT_ID: o ID do projeto para o qual você quer listar insights.
  • LOCATION: o local dos conjuntos de dados que têm insights você quer listar.

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

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

A resposta lista todos os insights de política no nível do conjunto de dados para seu projeto no local especificado. Exemplo:

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

Para saber mais sobre os componentes de um insight, consulte Analisar insights de política no nível do conjunto de dados nesta página.

Receber um único insight de política no nível do conjunto de dados

Para mais informações sobre um único insight, incluindo a descrição, o status e as recomendações associadas, use um dos seguintes métodos:

gcloud

Use o comando gcloud recommender insights describe com o ID do insight para ver as informações sobre um único insight.

  • INSIGHT_ID: o ID do insight que você quer ver. Para encontrar o ID, liste os insights do projeto.
  • PROJECT_ID: o ID do projeto para o qual você quer gerenciar insights.
  • LOCATION: o local do conjunto de dados cujo insight você quer receber.
gcloud recommender insights describe INSIGHT_ID \
    --insight-type=google.iam.policy.Insight \
    --project=PROJECT_ID \
    --location=LOCATION

A saída mostra os insights detalhados. Por exemplo, o insight a seguir indica que todos os usuários com o papel de editor no projeto my-project (projectEditor:my-project) têm o papel Editor de dados do BigQuery (roles/bigquery.dataEditor) no conjunto de dados dataset-1, mas que nenhuma das permissões nesse papel foi usada nos últimos 90 dias:

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

Para saber mais sobre os componentes de um insight, consulte Analisar insights de política no nível do conjunto de dados nesta página.

REST

O método insights.get da API Recommender recebe um insight.

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

  • PROJECT_ID: o ID do projeto para o qual você quer gerenciar insights.
  • LOCATION: o local do conjunto de dados cujo insight você quer receber.
  • INSIGHT_ID: o ID do insight que você quer ver. Se não souber o ID, é possível encontrá-lo listando os insights no projeto. O ID de um insight é tudo o que aparece depois de insights/ no campo name do insight.

Método HTTP e URL:

GET https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID

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

A resposta contém o insight. Por exemplo, o insight a seguir indica que todos os usuários com o papel de editor no projeto my-project (projectEditor:my-project) têm o papel Editor de dados do BigQuery (roles/bigquery.dataEditor) no conjunto de dados dataset-1, mas que nenhuma das permissões nesse papel foi usada nos últimos 90 dias:

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

Para saber mais sobre os componentes de um insight, consulte Analisar insights de política no nível do conjunto de dados nesta página.

Analise os insights de política no nível do conjunto de dados

Depois de receber um único insight, é possível analisar o conteúdo para entender o padrão de uso de recursos destacado

O conteúdo do insight é determinado pelos subtipos dele. Os insights de política no nível do conjunto de dados (google.iam.policy.Insight) têm o subtipo PERMISSIONS_USAGE_BIGQUERY_DATASET.

Os insights PERMISSIONS_USAGE_BIGQUERY_DATASET têm os seguintes componentes, não necessariamente nesta ordem:

  • associatedRecommendations: os identificadores de qualquer recomendação associada ao insight. Se não houver recomendações associadas ao insight, esse campo estará vazio.
  • category: a categoria de insights do IAM é sempre SECURITY.
  • content: relata o uso das permissões de um membro referentes a um papel específico. Este campo contém os seguintes componentes:

    • condition: qualquer condição anexada à vinculação que concede o papel ao principal. Se não houver condições, esse campo conterá uma condição vazia.
    • exercisedPermissions: as permissões no papel que o principal usou durante o período de observação.
    • inferredPermissions: as permissões do papel que o recomendador determinou, por ML, que o principal provavelmente precisará com base nas permissões exercidas.
    • member: o principal com o uso analisado das permissões.
    • role: o papel com o uso analisado das permissões.
  • description: um resumo legível do insight.
  • etag: um identificador exclusivo do estado atual de um insight. Sempre que o insight for alterado, um novo valor de etag será atribuído.

    Para alterar o estado de um insight, informe a etag do insight atual. O uso de etag ajuda a garantir que qualquer operação seja executada somente se o insight não tiver sido alterado desde a última vez que você o recuperou.

  • insightSubtype: o subtipo de insight.
  • lastRefreshTime: a data em que o insight foi atualizado pela última vez, o que indica a atualização dos dados usados para gerá-lo.
  • name: o nome do insight no seguinte formato:

    projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID

    Os marcadores têm os seguintes valores:

    • PROJECT_ID: o ID do projeto em que o insight foi gerado.
    • LOCATION: o local do conjunto de dados relacionado ao insight.
    • INSIGHT_ID: um ID exclusivo para o insight.
  • observationPeriod: o período antes do insight. Os dados de origem usados para gerar o insight terminam em lastRefreshTime e começam em lastRefreshTime menos observationPeriod.
  • stateInfo: os insights passam por várias transições de estado após serem propostos:

    • ACTIVE: o insight foi gerado, mas nenhuma ação foi realizada, ou uma ação foi realizada sem atualizar o estado dele. Os insights ativos são atualizados quando os dados subjacentes são alterados.
    • ACCEPTED: ocorreu uma ação com base no insight. Os insights são aceitos quando uma recomendação associada é marcada como CLAIMED, SUCCEEDED ou FAILED, ou quando o insight é aceito diretamente. Quando o estado do insight é ACCEPTED, o conteúdo dele não pode ser alterado. Os insights aceitos são mantidos por 90 dias após a aceitação.
  • targetResources: o nome completo do recurso do conjunto de dados relacionado ao insight. Por exemplo, //bigquery.googleapis.com/projects/my-project/datasets/my-dataset.

Marcar um insight de política no nível do conjunto de dados como ACCEPTED

Se você executar uma ação com base em um insight ativo, será possível marcá-lo como ACCEPTED. O estado ACCEPTED informa à API Recommender que você tomou medidas com base nesse insight, o que ajuda a refinar as recomendações.

Os insights aceitos são mantidos por 90 dias depois de serem marcados como ACCEPTED.

gcloud

Use o comando gcloud recommender insights mark-accepted com o ID do insight para marcar um insight como ACCEPTED.

  • INSIGHT_ID: o ID do insight que você quer ver. Para encontrar o ID, liste os insights do projeto.
  • PROJECT_ID: o ID do projeto para o qual você quer gerenciar insights.
  • LOCATION: o local do conjunto de dados cujo insight você quer marcar como ACCEPTED.
  • ETAG: um identificador de uma versão do insight. Para receber o etag, faça o seguinte:

    1. Receba o insight usando o comando gcloud recommender insights describe.
    2. Encontre e copie o valor da etag na saída, incluindo as aspas delimitadoras. Por exemplo, "d3cdec23cc712bd0".
gcloud recommender insights mark-accepted INSIGHT_ID \
    --insight-type=google.iam.policy.Insight \
    --project=PROJECT_ID \
    --location=LOCATION \
    --etag=ETAG

A saída mostra o insight, agora com o estado 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

Para saber mais sobre as informações de estado de um insight, consulte Analisar insights de política no nível do conjunto de dados nesta página.

REST

O método insights.markAccepted da API Recommender marca um insight como ACCEPTED.

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

  • PROJECT_ID: o ID do projeto para o qual você quer gerenciar insights.
  • LOCATION: o local do conjunto de dados cujo insight você quer marcar como ACCEPTED.
  • INSIGHT_ID: o ID do insight que você quer ver. Se não souber o ID, é possível encontrá-lo listando os insights no projeto. O ID de um insight é tudo o que aparece depois de insights/ no campo name do insight.
  • ETAG: identificador de uma versão do insight. Para receber o etag, faça o seguinte:
    1. Receba o insight usando o método insights.get.
    2. Encontre e copie o valor etag da resposta.

Método HTTP e URL:

POST https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID:markAccepted

Corpo JSON da solicitação:

{
  "etag": "ETAG"
}

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

A resposta contém o insight, agora com o estado 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"
}

Para saber mais sobre as informações de estado de um insight, consulte Analisar insights de política no nível do conjunto de dados nesta página.

A seguir