Gravar a análise de políticas no BigQuery

Nesta página, explicamos como analisar políticas de gerenciamento de identidade e acesso (IAM) de forma assíncrona e gravar resultados no BigQuery. O processo é semelhante à análise de políticas do IAM, mas o resultado da análise é gravado nas tabelas do BigQuery.

Antes de começar

Ative a Cloud Asset API.

Ative a API

Ative a API no projeto ou na organização que você usará para enviar a consulta. Ele não precisa ser o mesmo recurso que você definiu para a consulta.

Papéis e permissões necessárias

Os papéis e permissões a seguir são necessários para executar uma análise de política e exportar os resultados para o BigQuery.

Papéis do IAM obrigatórios

Para receber as permissões necessárias para analisar uma política e exportar os resultados para o BigQuery, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto, na pasta ou na organização para os quais você definirá o escopo da consulta:

  • Editor de dados do BigQuery (roles/bigquery.dataEditor)
  • Leitor de recursos do Cloud (roles/cloudasset.viewer)
  • Para analisar políticas com papéis de IAM personalizados: Visualizador de papéis (roles/iam.roleViewer)
  • Usar a CLI do Google Cloud para analisar políticas: consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer)

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

Esses papéis predefinidos contêm as permissões necessárias para analisar uma política e exportar os resultados para o BigQuery. Para ver as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

  • bigquery.datasets.create
  • bigquery.jobs.create
  • bigquery.tables.create
  • bigquery.tables.get
  • bigquery.tables.updateData
  • bigquery.tables.update
  • cloudasset.assets.analyzeIamPolicy
  • cloudasset.assets.searchAllResources
  • cloudasset.assets.searchAllIamPolicies
  • Para analisar políticas com papéis personalizados do IAM: iam.roles.get
  • Se quiser usar a CLI do Google Cloud para analisar políticas, siga estas etapas: serviceusage.services.use

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

Permissões necessárias do Google Workspace

Se você quiser ver se um principal tem determinados papéis ou permissões como resultado da associação em um grupo do Google Workspace, precisará da permissão groups.read do Google Workspace. Essa permissão está incluída no papel de administrador do Grupos e em papéis mais poderosos, como os de administrador ou superadministrador do Grupos. Consulte Atribuir funções administrativas específicas para mais informações.

Chamando AnalyzeIamPolicyLongrunning

O método AnalyzeIamPolicyLongrunning permite que você emita uma solicitação de análise e receba resultados no destino BigQuery especificado.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

  • RESOURCE_TYPE: o tipo do recurso que você quer usar como escopo da pesquisa. Somente as políticas de permissão do IAM anexadas a esse recurso e aos descendentes serão analisadas. Use o valor project, folder ou organization.
  • RESOURCE_ID: o ID do projeto, da pasta ou da organização do Google Cloud para o qual você quer definir o escopo da pesquisa. Somente as políticas de permissão do IAM anexadas a esse recurso e aos descendentes dele serão analisadas. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
  • PRINCIPAL: o principal cujo acesso você quer analisar, no formato PRINCIPAL_TYPE:ID. Por exemplo, user:my-user@example.com. Para ver uma lista completa dos tipos principais, consulte Identificadores principais.
  • PERMISSIONS: uma lista separada por vírgulas das permissões que você quer verificar, por exemplo, compute.instances.get,compute.instances.start. Se você listar várias permissões, o Policy Analyzer verificará qualquer uma das permissões listadas.
  • DATASET: o conjunto de dados do BigQuery no formato projects/PROJECT_ID/datasets/DATASET_ID, em que PROJECT_ID é o ID alfanumérico do seu projeto do Google Cloud e DATASET_ID é o ID do seu conjunto de dados.
  • TABLE_PREFIX: o prefixo das tabelas do BigQuery em que os resultados da análise serão gravados. Se não existir uma tabela com o prefixo especificado, o BigQuery criará uma nova tabela.
  • PARTITION_KEY: opcional. A chave de partição da tabela particionada do BigQuery. O analisador de políticas é compatível apenas com chaves de partição REQUEST_TIME.
  • WRITE_DISPOSITION: opcional. Especifica a ação que ocorre se a tabela ou partição de destino já existe. Para ver uma lista de possíveis valores, consulte writeDisposition. Por padrão, se a tabela ou a partição já existir, o BigQuery anexará os dados à tabela ou à partição mais recente.

Execute o comando gcloud asset parse-iam-policy-longrunning:

Linux, macOS ou Cloud Shell

gcloud asset analyze-iam-policy-longrunning --RESOURCE_TYPE=RESOURCE_ID \
    --full-resource-name=FULL_RESOURCE_NAME \
    --identity=PRINCIPAL \
    --permissions='PERMISSIONS' \
    --bigquery-dataset=DATASET \
    --bigquery-table-prefix=TABLE_PREFIX \
    --bigquery-partition-key=PARTITION_KEY \
    --bigquery-write-disposition=WRITE_DISPOSITION

Windows (PowerShell)

gcloud asset analyze-iam-policy-longrunning --RESOURCE_TYPE=RESOURCE_ID `
    --full-resource-name=FULL_RESOURCE_NAME `
    --identity=PRINCIPAL `
    --permissions='PERMISSIONS' `
    --bigquery-dataset=DATASET `
    --bigquery-table-prefix=TABLE_PREFIX `
    --bigquery-partition-key=PARTITION_KEY `
    --bigquery-write-disposition=WRITE_DISPOSITION

Windows (cmd.exe)

gcloud asset analyze-iam-policy-longrunning --RESOURCE_TYPE=RESOURCE_ID ^
    --full-resource-name=FULL_RESOURCE_NAME ^
    --identity=PRINCIPAL ^
    --permissions='PERMISSIONS' ^
    --bigquery-dataset=DATASET ^
    --bigquery-table-prefix=TABLE_PREFIX ^
    --bigquery-partition-key=PARTITION_KEY ^
    --bigquery-write-disposition=WRITE_DISPOSITION

Você receberá uma resposta semelhante a esta:

Analyze IAM Policy in progress.
Use [gcloud asset operations describe projects/my-project/operations/AnalyzeIamPolicyLongrunning/1195028485971902504711950280359719028666] to check the status of the operation.

REST

Para analisar uma política de permissão do IAM e exportar os resultados para o BigQuery, use o método analyzeIamPolicyLongrunning da API Cloud Asset Inventory.

Antes de usar qualquer um dos dados da solicitação, faça as seguintes substituições:

  • RESOURCE_TYPE: o tipo do recurso que você quer usar como escopo da pesquisa. Somente as políticas de permissão do IAM anexadas a esse recurso e aos descendentes serão analisadas. Use o valor projects, folders ou organizations.
  • RESOURCE_ID: o ID do projeto, da pasta ou da organização do Google Cloud para o qual você quer definir o escopo da pesquisa. Somente as políticas de permissão do IAM anexadas a esse recurso e aos descendentes dele serão analisadas. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
  • FULL_RESOURCE_NAME: opcional. O nome completo do recurso com o acesso que você quer analisar. Para ver uma lista de formatos de nome de recurso completos, consulte Formato de nome de recurso.
  • PRINCIPAL: opcional. O principal cujo acesso você quer analisar, no formato PRINCIPAL_TYPE:ID, por exemplo, user:my-user@example.com. Para ver uma lista completa dos tipos principais, consulte Identificadores principais.
  • PERMISSION_1, PERMISSION_2... PERMISSION_N: opcional. As permissões que você quer verificar, por exemplo, compute.instances.get. Se você listar várias permissões, o Policy Analyzer verificará qualquer uma das permissões listadas.
  • DATASET: o conjunto de dados do BigQuery no formato projects/PROJECT_ID/datasets/DATASET_ID, em que PROJECT_ID é o ID alfanumérico do seu projeto do Google Cloud e DATASET_ID é o ID do seu conjunto de dados.
  • TABLE_PREFIX: o prefixo das tabelas do BigQuery em que os resultados da análise serão gravados. Se não existir uma tabela com o prefixo especificado, o BigQuery criará uma nova tabela.
  • PARTITION_KEY: opcional. A chave de partição da tabela particionada do BigQuery. O analisador de políticas é compatível apenas com chaves de partição REQUEST_TIME.
  • WRITE_DISPOSITION: opcional. Especifica a ação que ocorre se a tabela ou partição de destino já existe. Para ver uma lista de possíveis valores, consulte writeDisposition. Por padrão, se a tabela ou a partição já existir, o BigQuery anexará os dados à tabela ou à partição mais recente.

Método HTTP e URL:

POST https://cloudasset.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID:analyzeIamPolicyLongrunning

Corpo JSON da solicitação:

{
  "analysisQuery": {
    "resourceSelector": {
      "fullResourceName": "FULL_RESOURCE_NAME"
    },
    "identitySelector": {
      "identity": "PRINCIPAL"
    },
    "accessSelector": {
      "permissions": [
        "PERMISSION_1",
        "PERMISSION_2",
        "PERMISSION_N"
      ]
    }
  },
  "outputConfig": {
    "bigqueryDestination": {
      "dataset": "DATASET",
      "tablePrefix": "TABLE_PREFIX",
      "partitionKey": "PARTITION_KEY",
      "writeDisposition": "WRITE_DISPOSITION"
    }
  }
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/my-project/operations/AnalyzeIamPolicyLongrunning/1206385342502762515812063858425027606003",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.asset.v1.AnalyzeIamPolicyLongrunningMetadata",
    "createTime": "2022-04-12T21:31:10.753173929Z"
  }
}

Como ver os resultados da análise de política do IAM

Para visualizar sua análise de política do IAM, faça o seguinte:

Console

  1. Acesse a página do BigQuery no console do Cloud.
    Acessar a página do BigQuery

  2. Para exibir as tabelas e visualizações no conjunto de dados, abra o painel de navegação. Na seção Recursos, selecione seu projeto para expandi-lo e selecione um conjunto de dados.

  3. Na lista, selecione as tabelas com seu prefixo. A tabela com o sufixo analysis contém a consulta e os metadados (por exemplo, nome da operação, horário da solicitação e erros não críticos). A tabela com o sufixo analysis_result é a tupla de listagem de resultados de {identity, role(s)/permission(s), resource} com as políticas do IAM que geram essas tuplas.

  4. Para visualizar um conjunto de dados de amostra, selecione Visualizar.

API

Para procurar os dados da tabela, chame tabledata.list. No parâmetro tableId, especifique o nome da sua tabela.

É possível configurar os seguintes parâmetros opcionais para controlar a saída.

  • maxResults é o número máximo de resultados a serem retornados.
  • selectedFields é uma lista de colunas separadas por vírgulas a ser retornada. Se não for especificado, todas as colunas serão retornadas.
  • startIndex é o índice baseado em zero da primeira linha a ser lida.

Os valores são retornados incorporados em um objeto JSON para análise, conforme descrito na documentação de referência de tabledata.list.

Como consultar o BigQuery

Nesta seção, apresentamos exemplos de consultas SQL para mostrar como usar tabelas do BigQuery escritas por AnalyzeIamPolicyLongrunning. Para mais informações sobre a sintaxe do BigQuery, consulte Sintaxe de consulta SQL padrão.

OP_ID é necessário para a maioria das consultas. É possível recebê-lo na resposta AnalyzeIamPolicyLongrunning. Por exemplo, no gcloud, você encontrará OP_ID como 123456 em "Usar [gcloud asset operations describe organizations/123456789/operations/AnalyzeIamPolicyLongrunning/123456] para verificar o status da operação".

Listar operações

A tabela pode armazenar resultados de várias operações AnalyzeIamPolicyLongrunning. Use a seguinte consulta para listar todos eles:

SELECT DISTINCT
  requestTime,
  opName
FROM `BQ_PROJECT_ID.BQ_DATASET_NAME.BQ_TABLE_PREFIX_analysis`
ORDER BY 1 DESC
;

Listar análises em uma operação

Em uma operação AnalyzeIamPolicyLongrunning, pode haver vários registros de análise gerados. Por exemplo, quando você ativa a opção analyze_service_account_impersonation na solicitação, o resultado pode conter uma análise principal (com analysisId 0) e várias análises de representação de contas de serviço.

Use a consulta a seguir para encontrar toda a análise fornecendo um nome de operação.

DECLARE _opName STRING DEFAULT "organizations/ORG_ID/operations/AnalyzeIamPolicyLongrunning/OP_ID";

SELECT
  analysisId,
  requestTime,
  TO_JSON_STRING(analysis.analysisQuery, true) as analysisQuery,
  analysis.fullyExplored,
  TO_JSON_STRING(analysis.nonCriticalErrors, true) as nonCriticalErrors
FROM `BQ_PROJECT_ID.BQ_DATASET_NAME.BQ_TABLE_PREFIX_analysis`
WHERE opName=_opName
ORDER BY 1
;

Listar ACEs (Entradas de controle de acesso) em uma análise

Uma ACE é uma entrada de controle de acesso {identity, role(s)/permission(s), resource}. Você pode usar a consulta a seguir para listar as ACE em uma análise.

DECLARE _opName STRING DEFAULT "organizations/ORG_ID/operations/AnalyzeIamPolicyLongrunning/OP_ID";

SELECT DISTINCT
  ids.name AS identity,
  resources.fullResourceName AS resource,
  accesses.role AS role,
  accesses.permission AS permission
FROM `BQ_PROJECT_ID.BQ_DATASET_NAME.BQ_TABLE_PREFIX_analysis_result`,
  UNNEST(analysisResult.identityList.identities) AS ids,
  UNNEST(analysisResult.accessControlLists) AS acls,
  UNNEST(acls.accesses) AS accesses,
  UNNEST(acls.resources) AS resources
WHERE opName=_opName
AND analysisId = 0
ORDER BY 1,2,3,4
;

Listar ACEs (Entradas no controle de acesso) com a vinculação de política do IAM em uma análise

Nessa consulta, listamos a ACE e a vinculação de política do IAM que gera essa ACE para uma análise.

DECLARE _opName STRING DEFAULT "organizations/ORG_ID/operations/AnalyzeIamPolicyLongrunning/OP_ID";

SELECT
  ids.name AS identity,
  resources.fullResourceName AS resource,
  accesses.role AS role,
  accesses.permission AS permission,
  analysisResult.attachedResourceFullName as iam_policy_attached_resource,
  TO_JSON_STRING(analysisResult.iamBinding, true) as iam_policy_binding
FROM `BQ_PROJECT_ID.BQ_DATASET_NAME.BQ_TABLE_PREFIX_analysis_result`,
  UNNEST(analysisResult.identityList.identities) AS ids,
  UNNEST(analysisResult.accessControlLists) AS acls,
  UNNEST(acls.accesses) AS accesses,
  UNNEST(acls.resources) AS resources
WHERE opName=_opName AND analysisId = 0
ORDER BY 1,2,3,4
;

Listar vinculações de políticas do IAM em uma análise

Nesta consulta, listamos as vinculações de política do IAM exibidas em uma análise.

DECLARE _opName STRING DEFAULT "organizations/ORG_ID/operations/AnalyzeIamPolicyLongrunning/OP_ID";

SELECT DISTINCT
  analysisResult.attachedResourceFullName as iam_policy_attached_resource,
  TO_JSON_STRING(analysisResult.iamBinding, true) as iam_policy_binding
FROM `BQ_PROJECT_ID.BQ_DATASET_NAME.BQ_TABLE_PREFIX_analysis_result`
WHERE opName=_opName AND analysisId = 0
ORDER BY 1, 2
;

Listar vinculações da política do IAM com a ACE (Entrada de controle de acesso) em uma análise

Nesta consulta, listamos as vinculações de política do IAM com as ACEs derivadas em uma análise.

DECLARE _opName STRING DEFAULT "organizations/ORG_ID/operations/AnalyzeIamPolicyLongrunning/OP_ID";

SELECT
  analysisResult.attachedResourceFullName as iam_policy_attached_resource,
  TO_JSON_STRING(analysisResult.iamBinding, true) as iam_policy_binding,
  TO_JSON_STRING(analysisResult.identityList.identities, true) as identities,
  TO_JSON_STRING(acls.accesses, true) as accesses,
  TO_JSON_STRING(acls.resources, true) as resources
FROM `BQ_PROJECT_ID.BQ_DATASET_NAME.BQ_TABLE_PREFIX_analysis_result`,
  UNNEST(analysisResult.accessControlLists) AS acls
WHERE opName=_opName AND analysisId = 0
ORDER BY 1,2
;